From 452af1b45e6f7382dbce63fba41ef7e1b6f49f30 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Felipe=20Say=C3=A3o=20Lobato=20Abreu?= Date: Sat, 17 Oct 2026 13:50:16 -0300 Subject: [PATCH] docs: align documentation skill with current code MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Felipe Sayão Lobato Abreu --- .agents/skills/sphinx-docs/SKILL.md | 9 +++++++++ .agents/skills/sphinx-docs/references/update-triggers.md | 9 +++++++++ CHANGELOG.md | 4 ++++ 3 files changed, 22 insertions(+) diff --git a/.agents/skills/sphinx-docs/SKILL.md b/.agents/skills/sphinx-docs/SKILL.md index a3d4a7e5c1..e6de21a56c 100644 --- a/.agents/skills/sphinx-docs/SKILL.md +++ b/.agents/skills/sphinx-docs/SKILL.md @@ -17,6 +17,15 @@ This skill provides a comprehensive checklist and structure for generating rich, - Reference relevant PSRs, RFCs, and related libraries where appropriate. - Always detect and document special features in the codebase: aliases, factories, singleton patterns, extensibility points, static helpers, PSR compliance, and integration hooks. +## Documentation Follows the Current Code + +- Document the API and workflows implemented by the code the documentation accompanies. Once a change is merged into the default branch, treat it as current there, even when the next package release has not been tagged. +- Use stable descriptions instead of temporary labels such as "unreleased next major", "not published yet", or "still in this PR". Documentation must not require a follow-up wording change in the release PR simply because publication happened. +- Apply this rule to current page titles, introductions, HTML metadata, badges, bundled skill/provenance instructions, and release-tool guides such as `.changeset/README.md` when present. Immutable provenance facts remain valid; do not turn them into temporary instructions about the current API. +- Pending Changeset bodies become published changelog text too. Describe the product change and migration impact, not PR progress, execution receipts, or temporary manifest-version instructions. Keep release automation markers with their actual semantics. +- Preserve legitimate versioned migration guides, compatibility tables, changelogs (including an `Unreleased` section), and historical release notes. Review context instead of deleting version-related words blindly. +- Verify installation and availability claims separately. Describing current code does not prove that a package version or tag is published; do not invent an installable constraint or recommend a development branch to avoid that distinction. + ## Recommended Directory and File Structure - docs/ diff --git a/.agents/skills/sphinx-docs/references/update-triggers.md b/.agents/skills/sphinx-docs/references/update-triggers.md index 53ce422037..01f110807b 100644 --- a/.agents/skills/sphinx-docs/references/update-triggers.md +++ b/.agents/skills/sphinx-docs/references/update-triggers.md @@ -2,6 +2,15 @@ When to update Sphinx docs during code development. +Update affected documentation with the code change. After merge into the default +branch it describes the current API, independent of package-release timing. +Keep current titles, metadata, badges, skill instructions and release-tool guides +free of temporary PR/publication disclaimers. Preserve meaningful migration and +versioned history, including a changelog's `Unreleased` section, and verify any +claim about an installable package version separately. +Write pending Changeset bodies as product changes suitable for the published +changelog, without PR progress or execution receipts. + ## Triggers by Change Type | Code Change | Doc Action Required | diff --git a/CHANGELOG.md b/CHANGELOG.md index e41a760791..bd292c56ce 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +### Changed + +- Align the packaged documentation skill with the current code rather than release timing, while preserving migration history and verified installation claims. + ## [1.26.0] - 2026-10-16 ### Added