This is an automated email from the ASF dual-hosted git repository.
lukaszlenart pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/struts-site.git
The following commit(s) were added to refs/heads/main by this push:
new 9fe357d0f docs: add breaking-change detection to
documenting-struts-release skill (#305)
9fe357d0f is described below
commit 9fe357d0f25302ce437e8a508c9a021282e8dd19
Author: Lukasz Lenart <[email protected]>
AuthorDate: Sun Jun 14 20:32:22 2026 +0200
docs: add breaking-change detection to documenting-struts-release skill
(#305)
Breaking changes were the skill's biggest gap: a baseline subagent test
showed
agents missed backward-incompatible items because they (a) only scanned New
Feature/Improvement, and (b) dropped dependency bumps as 'internal' —
exactly
where breakage hides (OGNL, commons-fileupload method renames, UIBean field
visibility).
Adds a dedicated breaking-changes pass: a keyword shortlist over ALL issue
types,
a 6-point checklist (changed default, new enforcement, removed/narrowed API,
raised minimum requirement, breaking dependency bump, output/encoding
change),
net-delta dependency verification against the tag POM, and migration-note
output.
Re-verified with a with-skill subagent test (correctly found the 7.2.0
breaking
changes and ruled out non-breaking items).
Co-authored-by: Claude Opus 4.8 <[email protected]>
---
.claude/skills/documenting-struts-release/SKILL.md | 61 +++++++++++++++++++---
1 file changed, 55 insertions(+), 6 deletions(-)
diff --git a/.claude/skills/documenting-struts-release/SKILL.md
b/.claude/skills/documenting-struts-release/SKILL.md
index 3338d4982..17918d45b 100644
--- a/.claude/skills/documenting-struts-release/SKILL.md
+++ b/.claude/skills/documenting-struts-release/SKILL.md
@@ -1,6 +1,6 @@
---
name: documenting-struts-release
-description: Use when a new Apache Struts version has been released and you
need to audit its release notes (JIRA / Version Notes) and update the website's
feature/behavior documentation to match. For the GA announcement mechanics
(announce-YYYY, _config.yml, releases.md, [ANN] email) use
announcing-struts-release instead.
+description: Use when a new Apache Struts version has been released and you
need to audit its release notes (JIRA / Version Notes) and update the website's
feature/behavior documentation to match, including spotting breaking /
backward-incompatible changes that need migration notes. For the GA
announcement mechanics (announce-YYYY, _config.yml, releases.md, [ANN] email)
use announcing-struts-release instead.
---
# Documenting a Struts Release
@@ -27,12 +27,56 @@ content lives in:
- `source/plugins/<name>/` — per-plugin docs (json, rest, spring, convention,
…)
- `source/security/` — security bulletins
+## Breaking changes — always run this pass
+
+Breaking changes are the highest-value thing to document, and the easiest to
+miss: they rarely sit under *New Feature*, and the JIRA notes have no
"breaking"
+category. They hide inside *Improvement*, *Bug*, *Task*, and *Dependency*
items.
+A breaking change needs a migration / behaviour-change callout
+(`{:.alert .alert-warning}`) on the affected page, even when the item itself
has
+no obvious "feature" page.
+
+**Shortlist first, then judge.** Don't eyeball ~60 issues — filter titles for
the
+words that signal breakage, then read the source diff for each hit:
+
+```
+enforce|authoriz|deprecat|remove|delete|rename|narrow|private|require|
+default|harden|bump|upgrade|migrat|incompat|minimum|drop|reject
+```
+
+Then scan **every** shortlisted issue (all types, not just New
Feature/Improvement)
+against this checklist:
+
+- **Changed default** — a constant/default flips so existing apps behave
differently.
+- **New enforcement** — stricter validation/authorization now rejects input
that
+ previously worked (e.g. `@StrutsParameter` enforcement reaching a new
channel).
+- **Removed / deprecated / narrowed API** — deleted methods,
`protected`→`private`
+ field changes that break subclasses, renamed/removed config keys.
+- **Raised minimum requirement** — higher Java / Servlet / Jakarta / Spring /
+ Tomcat baseline. Confirm against the tag's `pom.xml` / parent POM and
compare to
+ the previous tag; do **not** trust the announcement's copied boilerplate
paragraph.
+- **Dependency major bump that changes a user-facing API** — e.g. OGNL or
+ commons-fileupload method renames. These are NOT "purely internal" if user
code
+ or config touches them. Several JIRA "Bump X from A to B" tickets may stack
for
+ one dependency; verify the **net** version delta in the tag's `pom.xml`
against
+ the *previous* tag, not the single hop shown in any one ticket.
+- **Output/encoding changes** — altered rendered HTML, escaping, redirect
bodies.
+
+Check the **Version Notes** page (`{{ site.wiki_url }}/Version+Notes+<X.Y.Z>`)
for
+an upgrade/migration section — but treat it as a bonus, not the source of
truth: it
+is often empty for a release. The JIRA scan above is the primary discovery
method.
+Verify each suspected breaking change against the source tag (see Workflow
step 4)
+before writing the migration note. If a breaking change touches minimum runtime
+requirements, also flag it for `announcing-struts-release` (its spec-versions
+paragraph and the getting-started prerequisites may need updating).
+
## Workflow
1. **Get the itemized release notes.** Fetch the JIRA `ReleaseNote.jspa` URL
and
- list **every** issue under *New Feature* and *Improvement* verbatim with its
- `WW-XXXX` key, plus any *Bug* whose title implies a user-visible change
- (changed default, new option, behavior change). Ignore purely internal
items.
+ list **every** issue (all types) with its `WW-XXXX` key. Mark each as: a
+ documentation candidate (New Feature, Improvement, or a *Bug* implying a
+ user-visible change — changed default, new option, behavior change) and/or a
+ **breaking change** per the checklist above. An item can be both.
2. **Check existing coverage FIRST — before planning any edit.** For each
candidate:
- `git log --oneline -- <likely page>` and search recent commits/PRs for the
@@ -43,8 +87,10 @@ content lives in:
3. **Map each remaining item to its page**, then classify it:
- **documented** — already covered (drop).
- **gap** — has a doc home, not yet covered (fix it).
- - **no-doc-home** — internal (perf, refactors, dependency bumps, IDE-plugin,
- logging) → list as out-of-scope, do not invent a page.
+ - **no-doc-home** — *purely* internal (perf, refactors, IDE-plugin, logging,
+ dependency bumps with no user-facing effect) → list as out-of-scope, do
not
+ invent a page. Note: a dependency bump or removal that breaks user
code/config
+ is a **breaking change**, not no-doc-home — it still needs a migration
note.
4. **Verify exact details against the released source tag — NOT JIRA.** JIRA
descriptions are *proposals*; constant names, defaults, and class names
often
@@ -79,3 +125,6 @@ content lives in:
| Inventing a page for an internal change | If there is no doc home, list it
as out-of-scope. |
| Bundling announcement changes | Announcement mechanics belong to
`announcing-struts-release`; keep this branch content-only. |
| Claiming the build passed when it didn't run | Say the local build couldn't
run and rely on staging; never assert unverified success. |
+| Only scanning New Feature/Improvement for changes | Breaking changes hide in
Bug/Task/Dependency items — run the breaking-changes pass over **every** issue.
|
+| Dropping dependency bumps as "internal" | A dep bump/removal that changes a
user-facing API (OGNL, fileupload renames) is breaking — document it, don't
drop it. |
+| Re-copying the announcement's minimum-requirements paragraph | Verify
Java/Servlet/Jakarta baselines against the tag's POM vs the previous tag; flag
raised minimums. |
