From a7eb25f40f175dc0c2776ed19ed96b76f6174f9f Mon Sep 17 00:00:00 2001 From: Jenny Schweers Date: Tue, 25 Jun 2024 14:47:28 -0400 Subject: [PATCH 1/8] Updated overview --- .../bootstrap5/migration_guide.html | 102 +++++++++++------- 1 file changed, 62 insertions(+), 40 deletions(-) diff --git a/corehq/apps/styleguide/templates/styleguide/bootstrap5/migration_guide.html b/corehq/apps/styleguide/templates/styleguide/bootstrap5/migration_guide.html index aacf9b850c8c..5ad13feee894 100644 --- a/corehq/apps/styleguide/templates/styleguide/bootstrap5/migration_guide.html +++ b/corehq/apps/styleguide/templates/styleguide/bootstrap5/migration_guide.html @@ -49,47 +49,69 @@

update this notice and leave this page as documentation for the next Bootstrap migration.

- We are taking an app-by-app approach to migrating from Bootstrap 3 to 5. This process is summarized by the following: + Bootstrap is a third-party UI library used throughout + HQ. It's essentially a set of stylesheets and javascript widgets. This means that migrating from one version to the + next involves the following kinds of work: + +

+

+

+ Because the HQ codebase is large, we are taking an incremental approach to this migration. + For organizational purposes, we are executing and tracking this migration primarily on an app-by-app basis. +

+

+ Multiple versions of Bootstrap cannot coexist on the same page. + The @use_bootstrap5 decorator marks individual views as migrated to Bootstrap 5. This decorator + sets a use_bootstrap5 attribute on the request that's used to set up the + relevant Bootstrap environment. +

+

+ This means that files that are required by both migrated and unmigrated pages need to be "split" into two + versions: one to include on Bootstrap 3 pages and another to include on Bootstrap 5 pages. This applies largely to code that + is fundamental to HQ's UI and used throughout the platform, such as the hqwebapp app, the + analytics JavaScript libraries, etc. +

+

+ It can also be helpful to "split" files in this way while migrating an app. This allows + Bootstrap 5 changes to be developed, reviewed, and merged in small pieces, before switching the Bootstrap + version used in production. It is a more complex process that adds more code during the migration, + although most of this code is automatically generated by the migration tool. + In these cases, once the app is fully migrated, the Bootstrap 3 files can be deleted. +

+

+ To support this approach, we have tooling that facilitates "splitting" and "unsplitting" files: + copying files, moving them, and updating references to them. This tooling also performs the simpler migration + updates, such as renaming CSS classes. For updates that it cannot handle automatically, it adds a TODO comment + to the relevant code and writes out a changelog. +

+

+ Once the entire platform is fully migrated to Bootstrap 5, any remaining Bootstrap 3 code can be removed: + the Bootstrap 3 versions of files in hqwebapp and similar apps, the @use_bootstrap5 + decorator, any code related to request.use_bootstrap5 or window.USE_BOOTSTRAP_5, + the Bootstrap 3 stylesheets and JavaScript library, and so forth.

-

Prepare Local Environment From a5f33c780d8c1c9eee6afcbc6a2d225fcb620c10 Mon Sep 17 00:00:00 2001 From: Jenny Schweers Date: Tue, 25 Jun 2024 14:48:41 -0400 Subject: [PATCH 2/8] Updated announcement step --- .../bootstrap5/migration_guide.html | 29 ++++++++++++------- 1 file changed, 18 insertions(+), 11 deletions(-) diff --git a/corehq/apps/styleguide/templates/styleguide/bootstrap5/migration_guide.html b/corehq/apps/styleguide/templates/styleguide/bootstrap5/migration_guide.html index 5ad13feee894..d965ad4a531a 100644 --- a/corehq/apps/styleguide/templates/styleguide/bootstrap5/migration_guide.html +++ b/corehq/apps/styleguide/templates/styleguide/bootstrap5/migration_guide.html @@ -130,18 +130,25 @@

Step 1: Announce Migration

- Before you begin the migration of an app, please announce your intention to do so in #gtd-dev. It is - important to communicate timelines for how long you expect the "split files" stage to last. Additionally, please - ask that people refrain from any front-end development in that app until changes from the split files step have - been merged. -

-
- Important: - After announcing your intent to migrate the app, please update the app's migration status in this table. This is also a good place to see what apps have not been migrated yet, if - you are in need of ideas. -
+ target="_blank">This spreadsheet is a high-level tracker of which apps have been migrated. + It contains notes on the approximate size of different apps (in terms of how many views they contain) and on + inter-app dependencies. +

+

+ The migration tool supports two general workflows for migrating an app: one based on splitting all files into + Bootstrap 3 and Bootstrap 5 versions, and one based on migrating files "in place." The splitting files approach + is necessary for apps that are dependencies for other apps, which will need to support both + Bootstrap 3 and Bootstrap 5 for a while. It is optional for small, independent apps. +

+

+ Before you begin the migration of an app, please announce your intention to do so in #gtd-dev. + It is helpful to be aware of other front-end development in the app. If the app has ongoing front-end + development, consider delaying either that development or the migration, to reduce code conflicts. + After announcing your intent to migrate the app, please update + the app's migration status. +

Step 2: Auto-Migrate & Split Files From 9d03138e3af1fdb692696f77d839fdcca5a5928d Mon Sep 17 00:00:00 2001 From: Jenny Schweers Date: Tue, 25 Jun 2024 15:07:39 -0400 Subject: [PATCH 3/8] Moved up no split process Moving this so that a first-time reader of the docs encounters it before getting into the details of more complex migrations. --- .../bootstrap5/migration_guide.html | 88 ++++++++++++------- 1 file changed, 55 insertions(+), 33 deletions(-) diff --git a/corehq/apps/styleguide/templates/styleguide/bootstrap5/migration_guide.html b/corehq/apps/styleguide/templates/styleguide/bootstrap5/migration_guide.html index d965ad4a531a..d5cf0a94aaae 100644 --- a/corehq/apps/styleguide/templates/styleguide/bootstrap5/migration_guide.html +++ b/corehq/apps/styleguide/templates/styleguide/bootstrap5/migration_guide.html @@ -15,14 +15,14 @@
On this page
  • Overview
  • Prepare Local Environment
  • Step 1: Announce Migration
    • -
  • Step 2: Auto-Migrate & Split Files +
  • Step 2 (small apps): The "No Split" Process
    • +
  • Step 2 (large apps): Auto-Migrate & Split Files
  • Step 2B: Migrate Stylesheets
    • @@ -150,8 +150,60 @@

    target="_blank">the app's migration status.

    +

    + Step 2 (small apps): The "No Split" Process +

    +

    + For small apps that are not depended on by other apps, the migration tool supports a streamlined process that + does not require splitting files into a Bootstrap 3 and Bootstrap 5 version. This is a good option for apps + with a small number of views, as it involves fewer pull requests and avoids the overhead of splitting files. + This approach does the entire migration in a single pull request, which + makes it unlikely to be a good choice for apps with 10+ views. +

    +

    + To begin a "no split" migration, first + lint the app's JavaScript + and make a pull request for any linting changes. Then, to begin the actual migration, run: +

    +
    +
    + 
    ./manage.py migrate_app_to_bootstrap5 <app_name> --no-split
    +
    +
    +

    + This will iterate through all the templates and javascript files in <app_name>, + applying all automated fixes and adding TODO comments for fixes that aren't automated. After + staging the changes to each file, you will have the option to auto-commit those changes. +

    +

    + For each migrated template, the command will wait for you to apply the @use_bootstrap5 decorator + to the relevant views (see Migrating Views) before moving on to the next template. +

    +

    + Once all the files are migrated in-place, go through the TODO comments, which reference helper documents in the + changes_guide directory. +

    +

    + After all TODOs are addressed, test your work: load the page and + test out any interactivity. Most migrations should also go through QA. Migrations can skip QA if they make + relatively superficial changes and are in low-risk areas. +

    +

    + Also mark the migration as "complete" as part of your pull request. This updates a status file where we + programmatically track the status of the overall platform migration. To do so: +

    +
    +
    + 
    ./manage.py complete_bootstrap5_migration <app_name>
    +
    +
    +

    + You're done! Ignore the rest of this document. +

    +

    - Step 2: Auto-Migrate & Split Files + Step 2 (large apps): Auto-Migrate & Split Files

    The next step is to split affected template and javascript files into bootstrap3 and @@ -336,36 +388,6 @@

    build_bootstrap5_diffs to rebuild the diffs.

    -

    - Step 2.1B: Migrating Smaller Apps -

    -

    - Some apps only have a handful of templates and javascript files, and it's possible to run the auto-migration - on the templates in-place and migrate the views to Bootstrap 5 all within the same Pull Request. In this case, - you can make use of the --no-split option for migrate_app_to_bootstrap5. -

    -
    -
    - 
    ./manage.py migrate_app_to_bootstrap5 <app_name> --no-split
    -
    -
    -

    - This option will iterate through all the templates and javascript files in <app_name>. After - staging the changes to each file, you will have the option to auto-commit those changes. -

    -

    - For each migrated template, the command will wait for you to apply the @use_bootstrap5 decorator - to the relevant views (see Migrating Views) before moving on to the next template. -

    -

    - Once all the files are migrated in-place, you can then make additional manual changes to each template and view. - When the views are fully migrated, you can then create your pull request. -

    -

    - This option is useful for smaller apps, because it avoids the split-files and reference renames. Please only - choose this option if you are confident you can migrate all the views and javascript files within 1 to 2 weeks. -

    -

    Step 2B: Migrate Stylesheets

    From dcd6219725b9f729bad3a9c748d03cf3e93afbfe Mon Sep 17 00:00:00 2001 From: Jenny Schweers Date: Tue, 25 Jun 2024 17:37:13 -0400 Subject: [PATCH 4/8] Added 'Step 0' label --- .../templates/styleguide/bootstrap5/migration_guide.html | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/corehq/apps/styleguide/templates/styleguide/bootstrap5/migration_guide.html b/corehq/apps/styleguide/templates/styleguide/bootstrap5/migration_guide.html index d5cf0a94aaae..bfd32afd8521 100644 --- a/corehq/apps/styleguide/templates/styleguide/bootstrap5/migration_guide.html +++ b/corehq/apps/styleguide/templates/styleguide/bootstrap5/migration_guide.html @@ -13,7 +13,7 @@
    On this page