From e4c30ed081fa6e4583c37b95bc407a63584de702 Mon Sep 17 00:00:00 2001 From: Muskan Gupta Date: Mon, 17 Aug 2026 15:07:08 +0530 Subject: [PATCH] Adding component versioning requirements to ensure valid component version bumping --- CLAUDE.md | 2 ++ docs/architecture/component-versioning.md | 26 +++++++++++++++++++ .../.content.xml | 4 +++ .../.content.xml | 4 +++ 4 files changed, 36 insertions(+) create mode 100644 docs/architecture/component-versioning.md diff --git a/CLAUDE.md b/CLAUDE.md index 9978f40e29..9d8ba79973 100644 --- a/CLAUDE.md +++ b/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) diff --git a/docs/architecture/component-versioning.md b/docs/architecture/component-versioning.md new file mode 100644 index 0000000000..8b2c155a79 --- /dev/null +++ b/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)`), 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__V` 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 `` 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 (`v.runtime.cy.js` in most cases; `.spec.js` in older ones). diff --git a/it/apps/src/main/content/jcr_root/apps/forms-core-components-it/clientlibs/custom-forms-components-runtime-all/.content.xml b/it/apps/src/main/content/jcr_root/apps/forms-core-components-it/clientlibs/custom-forms-components-runtime-all/.content.xml index 1b446738e2..333a1ce790 100644 --- a/it/apps/src/main/content/jcr_root/apps/forms-core-components-it/clientlibs/custom-forms-components-runtime-all/.content.xml +++ b/it/apps/src/main/content/jcr_root/apps/forms-core-components-it/clientlibs/custom-forms-components-runtime-all/.content.xml @@ -1,4 +1,8 @@ + +