Adding component versioning requirements to ensure valid component version bumping

CLAUDE.md

@@ -9,6 +9,8 @@ AEM Core Forms Components — Adaptive Forms v2 component library.
   Module structure, Java model hierarchy, form JSON model, IT infrastructure, Cypress patterns, JCR content XML patterns.
 - **Runtime internals**: [`docs/architecture/runtime-internals.md`](docs/architecture/runtime-internals.md)
   Deep dive into the form initialization pipeline, repeatable container/InstanceManager mechanics, FT_FORMS-24358 items-array export, common crash signatures, and debugging checklist.
+- **Component versioning**: [`docs/architecture/component-versioning.md`](docs/architecture/component-versioning.md)
+  When a change needs a new component version (`v1` → `v2`) vs. a fix-in-place, and the full checklist of what to update when bumping a version (clientlib self-containment, `_cq_dialog`/`_cq_styleConfig` inheritance, `pom.xml`, runtime clientlib embed lists, etc.).
 
 ### E2E Testing
 - **Feature Toggle Tests**: [`docs/e2e-testing/feature-toggles.md`](docs/e2e-testing/feature-toggles.md)

docs/architecture/component-versioning.md

@@ -0,0 +1,26 @@
+# Component Versioning
+
+When a change requires a new component version (`v1` → `v2`), and what to check when bumping.
+
+## When to bump
+
+Bump when the change breaks a contract external code depends on:
+
+- DOM structure (elements added/removed/reordered, class renames) that could break authored CSS or test selectors.
+- JS runtime contract (clientlib category, init/attach lifecycle, public events, exported model/JSON shape).
+- Authoring contract (dialog field renames that would corrupt existing authored content).
+
+Do not bump for bug fixes, including accessibility fixes, or additive/non-breaking changes. Fix these forward in the existing version. Example: the datepicker `v1`→`v2` cycle (below) shows accessibility fixes being folded back into `v1` rather than kept as a `v2`-only fix.
+
+## Checklist
+
+Based on past version bumps in this repo (button/submit/reset v2, title v2, wizard v2, radiobutton v2, checkboxgroup v2, fileinput v2–v4, container v2, datepicker v2). None of these bumps completed every item below in a single commit — treat this as a review checklist, not a fixed template.
+
+1. **New version folder**: own `.content.xml` (title suffixed `(v<N+1>)`), HTL, `README.md`. Done consistently in every past bump.
+2. **Clientlib**: only needed if JS/CSS actually changed. Several past bumps (button, submit, reset, title, wizard v2) shipped no clientlib of their own and continued sharing `v1`'s. Where a clientlib was added (radiobutton, checkboxgroup, fileinput, container, datepicker v2), it was a full standalone copy — never a path into the previous version's clientlib folder.
+3. **`_cq_dialog` / `_cq_design_dialog` / `_cq_styleConfig` / `_cq_template.xml`**: inherit via `sling:resourceSuperType` when unchanged (the common case). Add an own copy only where fields actually differ (e.g. fileinput v3/v4, container v2). Check `extraClientlibs`, `helpPath`, and `trackingFeature` values that hardcode a version number — these do not update via inheritance.
+4. **Java model**: add `FormConstants.RT_FD_FORM_<COMPONENT>_V<N+1>` and update the Sling Model's `resourceType` array only if the exported model/JSON shape changed. Most past bumps (button, submit, reset, wizard, radiobutton, checkboxgroup, fileinput v4) did not touch Java at all — HTML/JS-only changes did not need it.
+5. **`ui.af.apps/pom.xml`**: the `<replace token=".core-adaptiveform">` step controls which version is visible in the component browser. This was the step most often missed in past bumps and added later in bulk cleanup PRs — verify it explicitly rather than assuming it was done alongside the version folder.
+6. **Runtime clientlib embed lists** (`ui.af.apps/.../core-forms-components-runtime-all/.content.xml`, `it/apps/.../custom-forms-components-runtime-all/.content.xml`): update only if step 2 added a new clientlib category. See the inline comment in those files for the replace-vs-add-alongside rule.
+7. **IT content / examples**: update any `.content.xml` with `sling:resourceSuperType` pointing at the old version, if the new version becomes the default. This was skipped entirely in some past bumps (e.g. datepicker, throughout its `v2` add-and-removal).
+8. **E2E spec**: add a Cypress spec for the new version's runtime behavior. Naming has not been fully consistent historically (`<component>v<N+1>.runtime.cy.js` in most cases; `.spec.js` in older ones).

it/apps/src/main/content/jcr_root/apps/forms-core-components-it/clientlibs/custom-forms-components-runtime-all/.content.xml

@@ -1,4 +1,8 @@
 <?xml version="1.0" encoding="UTF-8"?>
+<!-- When bumping a component from vN to vN+1: if the new version's clientlib is fully
+     self-contained (own resources and fixes, no regressions), replace the old category
+     with the new one; otherwise retain the old category alongside the new one.
+     See docs/architecture/component-versioning.md for the full checklist. -->
 <jcr:root xmlns:cq="http://www.day.com/jcr/cq/1.0" xmlns:jcr="http://www.jcp.org/jcr/1.0"
     jcr:primaryType="cq:ClientLibraryFolder"
     allowProxy="{Boolean}true"

ui.af.apps/src/main/content/jcr_root/apps/core/fd/af-clientlibs/core-forms-components-runtime-all/.content.xml

@@ -1,4 +1,8 @@
 <?xml version="1.0" encoding="UTF-8"?>
+<!-- When bumping a component from vN to vN+1: if the new version's clientlib is fully
+     self-contained (own resources and fixes, no regressions), replace the old category
+     with the new one; otherwise retain the old category alongside the new one.
+     See docs/architecture/component-versioning.md for the full checklist. -->
 <jcr:root xmlns:cq="http://www.day.com/jcr/cq/1.0" xmlns:jcr="http://www.jcp.org/jcr/1.0"
     jcr:primaryType="cq:ClientLibraryFolder"
     allowProxy="{Boolean}true"