This is an automated email from the ASF dual-hosted git repository. lukaszlenart pushed a commit to branch docs/skill-documenting-release in repository https://gitbox.apache.org/repos/asf/struts-site.git
commit 6b4c5c36a145bd978084acc344cfee389c810d4c Author: Lukasz Lenart <[email protected]> AuthorDate: Sun Jun 14 20:01:51 2026 +0200 docs: add documenting-struts-release skill Capture the repeatable content-audit procedure for a new Struts release: pull the itemized JIRA release notes, check existing coverage first (don't re-document), map each item to its page under core-developers/tag-developers/ plugins, verify constant names/defaults against the STRUTS_X_Y_Z tag source (not JIRA proposals), document only real gaps, and keep announcement mechanics in announcing-struts-release. Derived from the 7.2.0 content audit (PR #303) and validated with a baseline/with-skill subagent test. Co-Authored-By: Claude Opus 4.8 <[email protected]> --- .claude/skills/documenting-struts-release/SKILL.md | 81 ++++++++++++++++++++++ 1 file changed, 81 insertions(+) diff --git a/.claude/skills/documenting-struts-release/SKILL.md b/.claude/skills/documenting-struts-release/SKILL.md new file mode 100644 index 000000000..3338d4982 --- /dev/null +++ b/.claude/skills/documenting-struts-release/SKILL.md @@ -0,0 +1,81 @@ +--- +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. +--- + +# Documenting a Struts Release + +## Overview + +A new release ships bug fixes, improvements, and new features. Some of them +change documented behavior or add new configuration; many do not. This skill is +the **content audit**: map each release-note item to the page that documents it, +and update only the real gaps. It is separate from the release *announcement* +(see `announcing-struts-release`). + +**Core principle: find the gap, don't re-document.** Most items are either already +documented by an earlier PR or have no doc home. Blindly "documenting the release +notes" produces duplicate or wrong content. + +## Where the docs actually live + +`source/docs/` is **only an index** — do not grep it for feature guides. Real +content lives in: + +- `source/core-developers/` — interceptors, configuration, conversion, validation, file upload (~166 pages) +- `source/tag-developers/` — tags, themes, templates +- `source/plugins/<name>/` — per-plugin docs (json, rest, spring, convention, …) +- `source/security/` — security bulletins + +## 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. + +2. **Check existing coverage FIRST — before planning any edit.** For each candidate: + - `git log --oneline -- <likely page>` and search recent commits/PRs for the + version or issue keys: `git log --oneline --all | grep -iE "<version>|WW-XXXX"`. + - `grep -rn "<feature keyword / constant>" source/`. + Many items will already be documented by a prior PR. Drop those. + +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. + +4. **Verify exact details against the released source tag — NOT JIRA.** JIRA + descriptions are *proposals*; constant names, defaults, and class names often + differ in the merged code. Confirm against the `STRUTS_<X>_<Y>_<Z>` git tag, e.g.: + - `core/src/main/resources/org/apache/struts2/default.properties` + - `plugins/<name>/src/main/resources/struts-plugin.xml` + + Fetch `https://raw.githubusercontent.com/apache/struts/STRUTS_X_Y_Z/<path>`. + +5. **Edit the gap pages.** Follow each page's existing structure and the repo's + Kramdown conventions (e.g. `{:.alert .alert-warning}` for callouts). Cross-link + related pages; for parameter-authorization topics, link the + `core-developers/struts-parameter-annotation.html` hub. Confirm every internal + link target file exists. + +6. **Commit per page** (`docs:` type, with the `Co-Authored-By` trailer) on a + branch off `main` (e.g. `docs/struts-<version>-content-audit`). Do **not** touch + announcement files (`_config.yml`, `announce-*`, `releases.md`). + +7. **Verify.** Run `bundle exec jekyll build --trace` (or note if the local Ruby + env is broken — the PR auto-builds on staging). Grep-confirm new content and + links. `git diff --name-only origin/main...HEAD` should show only the intended + doc files. + +## Common mistakes + +| Mistake | Fix | +|---------|-----| +| Documenting items already covered | Step 2: check git history + grep existing pages first; drop covered items. | +| Grepping `source/docs/` for feature pages | It is only an index — search `core-developers/`, `tag-developers/`, `plugins/`. | +| Trusting JIRA for constant names/defaults | JIRA is a proposal; verify against the `STRUTS_X_Y_Z` tag source. | +| 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. |
