[docs] Update B5 migration guide

corehq/apps/hqwebapp/management/commands/migrate_app_to_bootstrap5.py

@@ -113,7 +113,8 @@ def handle(self, app_name, **options):
             if not confirm:
                 return
 
-        if not is_app_in_progress(app_name) and not is_app_migration_complete:
+        self.no_split = options.get('no_split')
+        if not is_app_in_progress(app_name) and not is_app_migration_complete and not self.no_split:
             self.stdout.write(self.style.WARNING(
                 f"\n\n'{app_name}' is not marked as 'in progress'.\n"
             ))
@@ -129,7 +130,6 @@ def handle(self, app_name, **options):
                     show_apply_commit=not has_changes
                 )
 
-        self.no_split = options.get('no_split')
         self.skip_all = options.get('skip_all')
         if self.skip_all and self.no_split:
             self.stderr.write(

corehq/apps/hqwebapp/tests/utils/test_bootstrap_changes.py

@@ -221,10 +221,8 @@ def test_flag_inline_styles():
 def test_flag_crispy_forms_in_template():
     line = """    {% crispy form %}\n"""
     flags = flag_crispy_forms_in_template(line)
-    eq(flags, [["check crispy",
-                "This template uses crispy forms. "
-                "Please ensure the form looks good after migration, and refer to "
-                "the updated Style Guide for current best practices, especially with checkbox fields."]])
+    eq(flags[0][0], "check crispy")
+    eq(flags[0][1].startswith("This template uses crispy forms."), True)
 
 
 def test_flag_changed_javascript_plugins_bootstrap5():

corehq/apps/hqwebapp/utils/bootstrap/changes.py

@@ -252,9 +252,7 @@ def flag_crispy_forms_in_template(line):
     if re.search(regex, line):
         flags.append([
             "check crispy",
-            "This template uses crispy forms. "
-            "Please ensure the form looks good after migration, and refer to "
-            "the updated Style Guide for current best practices, especially with checkbox fields."
+            _get_change_guide("crispy")
         ])
     return flags
 

corehq/apps/hqwebapp/utils/bootstrap/changes_guide/crispy.md

@@ -0,0 +1,19 @@
+This template uses crispy forms.
+
+Please ensure the form looks good after migration, and refer to the
+<a href="https://www.commcarehq.org/styleguide/b5/organisms/forms/#crispy-forms" target="_blank">crispy forms
+section</a> of the style guide.
+
+A few useful things to know about crispy forms in Bootstrap 5:
+
+* Checkboxes, typically based on a `BooleanField`, need to be updated to use the `BootstrapCheckboxInput` as their
+`widget`, as shown in <a href="https://www.commcarehq.org/styleguide/b5/organisms/forms/#crispy-forms-simple"
+target="_blank">this style guide example</a>.
+* As described in <a href="https://www.commcarehq.org/styleguide/b5/organisms/forms/#crispy-forms-simple"
+target="_blank">this section of the style guide</a>, best practice is to use one of HQ's standard helper classes
+for layout. Doing so means you can delete <code>form_class</code>, <code>label_class</code>,
+<code>field_class</code>, and <code>offset_class</code> from the form itself. This allows us to change the layout
+of crispy forms across HQ without needing to update each individual form.
+* If you do need to troubleshoot Bootstrap issues with crispy forms, be aware that Dimagi maintains a <a
+href="https://github.com/dimagi/crispy-bootstrap3to5" target="_blank">crispy-bootstrap3to5 </a> repo with
+transitional templates. You may also need to troubleshoot in the crispy templates.