From 45fcdd60ef5e8b9acf0aa8145df7e96f2b3c96a9 Mon Sep 17 00:00:00 2001 From: Jenny Schweers Date: Wed, 18 Sep 2024 11:14:13 -0400 Subject: [PATCH 1/9] Updated migration instructions --- .../bootstrap5/migration_guide.html | 22 +++++++++---------- 1 file changed, 10 insertions(+), 12 deletions(-) diff --git a/corehq/apps/styleguide/templates/styleguide/bootstrap5/migration_guide.html b/corehq/apps/styleguide/templates/styleguide/bootstrap5/migration_guide.html index a871cef678d3..2eefac99ea17 100644 --- a/corehq/apps/styleguide/templates/styleguide/bootstrap5/migration_guide.html +++ b/corehq/apps/styleguide/templates/styleguide/bootstrap5/migration_guide.html @@ -522,16 +522,20 @@

The migration process begins by either applying @use_bootstrap5 decorator the view function or - @method_decorator(use_bootstrap5, name='dispatch') to the view class. + @method_decorator(use_bootstrap5, name='dispatch') to the view class. Also update the template's + name in the view from bootstrap3/foo.html to bootstrap5/foo.html.

- Next, you should go into the view template and ensure that this template inherits from bootstrap5 - base templates. + The automation should have updated the view template so that it inherits from bootstrap5 + base templates. It should also have updated any bootstrap3 javascript dependencies to their + bootstrap5 versions.

- Finally, you should make sure any javascript files needed to render that view also inherit from bootstrap5 - dependencies. The migration tool should have handled updating any bootstrap3 dependencies to their - bootstrap5 versions. + The automation will have added comments to the template and javascript files noting what changes need to be + made. Each comment will be marked with todo B5 and the type of change that needs to be made. + Each type of change has a corresponding document in the + changes_guide directory explaining what needs to be done.

Once a view's template and javascript files are updated, it is now time to load that view and test for @@ -548,12 +552,6 @@

The most important part of the migration is ensuring that the page is functionally similar to the user and that no errors are present on the page that were not previously present in the Bootstrap 3 version. -

- There is a chance you might have to introduce changes to the stylesheet if you come across a custom component that - has not yet been migrated to Bootstrap 5. If this is the case, please flag this component with the lead developer - of the Bootstrap migration. They can assist with updating the stylesheet (if necessary) or updating guidance - for replacing this component with Bootstrap 5 best practices. -

Un-Split View Files From 1c25f256730d149c5bc49db8126f446117b446a5 Mon Sep 17 00:00:00 2001 From: Jenny Schweers Date: Wed, 18 Sep 2024 11:53:33 -0400 Subject: [PATCH 2/9] Updated TODO logic so tags match filenames exactly --- .../tests/utils/test_bootstrap_changes.py | 20 +++++++++---------- .../apps/hqwebapp/utils/bootstrap/changes.py | 8 ++++---- .../{breadcrumb.md => css-breadcrumb.md} | 0 .../{checkbox.md => css-checkbox.md} | 0 .../changes_guide/{close.md => css-close.md} | 0 ...{dl-horizontal.md => css-dl-horizontal.md} | 0 .../{dropdown.md => css-dropdown.md} | 0 .../{form-group.md => css-form-group.md} | 0 .../{form-inline.md => css-form-inline.md} | 0 .../{glyphicon.md => css-glyphicon.md} | 0 .../{has-error.md => css-has-error.md} | 0 .../{has-success.md => css-has-success.md} | 0 ...roup-addon.md => css-input-group-addon.md} | 0 ...ut-group-btn.md => css-input-group-btn.md} | 0 .../{modal-header.md => css-modal-header.md} | 0 .../changes_guide/{nav.md => css-nav.md} | 0 .../{navbar-dark.md => css-navbar-dark.md} | 0 .../{navbar-light.md => css-navbar-light.md} | 0 .../{navbar.md => css-navbar.md} | 0 .../{page-header.md => css-page-header.md} | 0 .../{pagination.md => css-pagination.md} | 0 .../changes_guide/{panel.md => css-panel.md} | 0 .../{progress.md => css-progress.md} | 0 .../changes_guide/{well.md => css-well.md} | 0 24 files changed, 14 insertions(+), 14 deletions(-) rename corehq/apps/hqwebapp/utils/bootstrap/changes_guide/{breadcrumb.md => css-breadcrumb.md} (100%) rename corehq/apps/hqwebapp/utils/bootstrap/changes_guide/{checkbox.md => css-checkbox.md} (100%) rename corehq/apps/hqwebapp/utils/bootstrap/changes_guide/{close.md => css-close.md} (100%) rename corehq/apps/hqwebapp/utils/bootstrap/changes_guide/{dl-horizontal.md => css-dl-horizontal.md} (100%) rename corehq/apps/hqwebapp/utils/bootstrap/changes_guide/{dropdown.md => css-dropdown.md} (100%) rename corehq/apps/hqwebapp/utils/bootstrap/changes_guide/{form-group.md => css-form-group.md} (100%) rename corehq/apps/hqwebapp/utils/bootstrap/changes_guide/{form-inline.md => css-form-inline.md} (100%) rename corehq/apps/hqwebapp/utils/bootstrap/changes_guide/{glyphicon.md => css-glyphicon.md} (100%) rename corehq/apps/hqwebapp/utils/bootstrap/changes_guide/{has-error.md => css-has-error.md} (100%) rename corehq/apps/hqwebapp/utils/bootstrap/changes_guide/{has-success.md => css-has-success.md} (100%) rename corehq/apps/hqwebapp/utils/bootstrap/changes_guide/{input-group-addon.md => css-input-group-addon.md} (100%) rename corehq/apps/hqwebapp/utils/bootstrap/changes_guide/{input-group-btn.md => css-input-group-btn.md} (100%) rename corehq/apps/hqwebapp/utils/bootstrap/changes_guide/{modal-header.md => css-modal-header.md} (100%) rename corehq/apps/hqwebapp/utils/bootstrap/changes_guide/{nav.md => css-nav.md} (100%) rename corehq/apps/hqwebapp/utils/bootstrap/changes_guide/{navbar-dark.md => css-navbar-dark.md} (100%) rename corehq/apps/hqwebapp/utils/bootstrap/changes_guide/{navbar-light.md => css-navbar-light.md} (100%) rename corehq/apps/hqwebapp/utils/bootstrap/changes_guide/{navbar.md => css-navbar.md} (100%) rename corehq/apps/hqwebapp/utils/bootstrap/changes_guide/{page-header.md => css-page-header.md} (100%) rename corehq/apps/hqwebapp/utils/bootstrap/changes_guide/{pagination.md => css-pagination.md} (100%) rename corehq/apps/hqwebapp/utils/bootstrap/changes_guide/{panel.md => css-panel.md} (100%) rename corehq/apps/hqwebapp/utils/bootstrap/changes_guide/{progress.md => css-progress.md} (100%) rename corehq/apps/hqwebapp/utils/bootstrap/changes_guide/{well.md => css-well.md} (100%) diff --git a/corehq/apps/hqwebapp/tests/utils/test_bootstrap_changes.py b/corehq/apps/hqwebapp/tests/utils/test_bootstrap_changes.py index 8b891810a86d..8cf57506f011 100644 --- a/corehq/apps/hqwebapp/tests/utils/test_bootstrap_changes.py +++ b/corehq/apps/hqwebapp/tests/utils/test_bootstrap_changes.py @@ -91,7 +91,7 @@ def test_flag_changed_css_classes_bootstrap5(): line, get_spec('bootstrap_3_to_5') ) eq(flags, [[ - 'css:dl-horizontal', + 'css-dl-horizontal', '`dl-horizontal` has been dropped.\nInstead, use `.row` on `
` and use grid column classes ' '(or mixins) on its `
` and `
` children.\n\nAn EXAMPLE for how to apply this change is ' 'provided below.\nPlease see docs for further details.\n\nPreviously:\n```\n
Date: Wed, 18 Sep 2024 12:04:04 -0400 Subject: [PATCH 3/9] Added docs for inline styles --- .../hqwebapp/tests/utils/test_bootstrap_changes.py | 2 +- corehq/apps/hqwebapp/utils/bootstrap/changes.py | 6 ++---- .../utils/bootstrap/changes_guide/inline-style.md | 13 +++++++++++++ 3 files changed, 16 insertions(+), 5 deletions(-) create mode 100644 corehq/apps/hqwebapp/utils/bootstrap/changes_guide/inline-style.md diff --git a/corehq/apps/hqwebapp/tests/utils/test_bootstrap_changes.py b/corehq/apps/hqwebapp/tests/utils/test_bootstrap_changes.py index 8cf57506f011..f8bae9a0c8af 100644 --- a/corehq/apps/hqwebapp/tests/utils/test_bootstrap_changes.py +++ b/corehq/apps/hqwebapp/tests/utils/test_bootstrap_changes.py @@ -214,7 +214,7 @@ def test_flag_inline_styles(): line = """method="post" style="float: left; margin-right: 5px;">""" flags = flag_inline_styles(line) eq(len(flags), 1) - eq(flags[0][0], "inline style") + eq(flags[0][0], "inline-style") eq(flags[0][1].startswith('This template uses inline styles.'), True) diff --git a/corehq/apps/hqwebapp/utils/bootstrap/changes.py b/corehq/apps/hqwebapp/utils/bootstrap/changes.py index 887df53b1959..8cf917b8d277 100644 --- a/corehq/apps/hqwebapp/utils/bootstrap/changes.py +++ b/corehq/apps/hqwebapp/utils/bootstrap/changes.py @@ -238,10 +238,8 @@ def flag_inline_styles(line): regex = r"\bstyle\s*=\s*" if re.search(regex, line): flags.append([ - "inline style", - "This template uses inline styles. Please revisit this usage.\n\n" - "Inline styles can often be replaced with Bootstrap 5's utility classes, " - "particularly the spacing utilities: https://getbootstrap.com/docs/5.0/utilities/spacing/" + "inline-style", + _get_change_guide("inline-style") ]) return flags diff --git a/corehq/apps/hqwebapp/utils/bootstrap/changes_guide/inline-style.md b/corehq/apps/hqwebapp/utils/bootstrap/changes_guide/inline-style.md new file mode 100644 index 000000000000..117eeba75891 --- /dev/null +++ b/corehq/apps/hqwebapp/utils/bootstrap/changes_guide/inline-style.md @@ -0,0 +1,13 @@ +This template uses inline styles. Please revisit this usage. + +Inline styles are not best practice. While replacing them is not strictly necessary for this migration, +Bootstrap 5 includes a host of utility classes that can replace a lot of the imline style usage in HQ. + +Some common replacements: +* Display styles like `display: none` can be replaced with classes like `d-none`. See https://getbootstrap.com/docs/5.0/utilities/display/ +* Spacing styles like `margin-bottom: 10px` can be replaced with classes like `mb-3`. See https://getbootstrap.com/docs/5.0/utilities/spacing/ +* Text alignment styles like `text-align: right` can be replaced with classes like `text-end`. See https://getbootstrap.com/docs/5.0/utilities/text/ +* Usages of the `em` unit should be updated to use the `rem` unit +* Layouts achieved using inline styling can sometimes be replaced with usage of flex. See https://getbootstrap.com/docs/5.0/utilities/flex/ + +See all of Bootstrap 5's utility classes: https://getbootstrap.com/docs/5.0/utilities/ From 43347ba3f3b4d5468320fa064716faaed1ff1b72 Mon Sep 17 00:00:00 2001 From: Jenny Schweers Date: Wed, 18 Sep 2024 12:11:36 -0400 Subject: [PATCH 4/9] Updated form-group guidance --- .../utils/bootstrap/changes_guide/css-form-group.md | 13 ++++++++----- 1 file changed, 8 insertions(+), 5 deletions(-) diff --git a/corehq/apps/hqwebapp/utils/bootstrap/changes_guide/css-form-group.md b/corehq/apps/hqwebapp/utils/bootstrap/changes_guide/css-form-group.md index 200051e7506f..7b6ac9575df2 100644 --- a/corehq/apps/hqwebapp/utils/bootstrap/changes_guide/css-form-group.md +++ b/corehq/apps/hqwebapp/utils/bootstrap/changes_guide/css-form-group.md @@ -1,7 +1,10 @@ `form-group` has been dropped. Use grid utilities instead. -Since we are opting for vertical forms (where the label is directly above the field), -the replacement for `form-group` is most likely just `mb-3` and the child `div` with a column -class surrounding the `form-control` element can be removed, along with the column class that -appears with the `