From 5362ef73106d1f5e68f48d685b82226bf4e7302b Mon Sep 17 00:00:00 2001 From: "Jamey M. Yates" Date: Wed, 30 Sep 2026 00:46:22 -0500 Subject: [PATCH] docs: reconcile Common Changelog release history --- .github/pull_request_template.md | 6 +++++ AGENTS.md | 5 ++++ CHANGELOG.md | 44 +++++++++++++++++++++++++++++++ CONTRIBUTING.md | 39 +++++++++++++++++++++++++++ MAINTAINING.md | 45 ++++++++++++++++++++++++++++---- README.md | 4 +++ 6 files changed, 138 insertions(+), 5 deletions(-) create mode 100644 CHANGELOG.md diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 0ce904e..71ee880 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -3,6 +3,12 @@ Describe the problem and resulting behavior. Explain material baseline or validation changes and their impact on consumers. +## Changelog + +Propose a concise changelog summary with supporting references, or briefly +explain why this change is not notable. Keep issue references descriptive; +follow the [issue-closure guidance](https://github.com/jamesreimer/agent-workflows/blob/main/roles/publication.md#github-issue-closure). + ## Validation Record checks performed and the behavior they establish. Include limitations diff --git a/AGENTS.md b/AGENTS.md index f5db13a..eefb2b4 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -21,6 +21,11 @@ to source-derived guidance, without exporting repository authorization as consum adoption. No new organization-neutral standard is authored or adopted here. A reference or available credential is not execution permission. +[Common Changelog](https://common-changelog.org/) governs changelog format only. +Repository-local contribution and release mechanics live in +[CONTRIBUTING.md](CONTRIBUTING.md#changelog) and +[MAINTAINING.md](MAINTAINING.md#prepare-the-release). + ## Working practices - Inspect branch and worktree state; preserve unrelated changes. diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..dc3127f --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,44 @@ +# Changelog + +## [0.2.0] - 2026-09-28 + +### Changed + +- Make role continuity and authorized transfer explicit, return ready-to-use handoffs when responsibility moves, and route reviewer corrections to Implementation ([`d288d77`](https://github.com/jamesreimer/agent-workflows/commit/d288d778685de43aab306f4609773c460acbef32), [#12](https://github.com/jamesreimer/agent-workflows/pull/12)) +- Require final successful local and hosted validation on the exact candidate before review readiness, and verify exact approved-source correspondence before dependent mutation ([`d288d77`](https://github.com/jamesreimer/agent-workflows/commit/d288d778685de43aab306f4609773c460acbef32), [#12](https://github.com/jamesreimer/agent-workflows/pull/12)) +- Expand publication handoffs with authorized source state, identities, correspondence, resulting-state verification, and prior-exposure assessment; review changed table labels when updating copied handoffs or integrations ([`d288d77`](https://github.com/jamesreimer/agent-workflows/commit/d288d778685de43aab306f4609773c460acbef32), [#12](https://github.com/jamesreimer/agent-workflows/pull/12)) + +### Added + +- Add Publication and Release Integrity edition 1.0 as a pinned governing source and integrate its applicable publication guidance, preserving the five existing source pins and consumer authority ([`d288d77`](https://github.com/jamesreimer/agent-workflows/commit/d288d778685de43aab306f4609773c460acbef32), [#12](https://github.com/jamesreimer/agent-workflows/pull/12)) +- Add a latest-release badge to the README ([`2d571bd`](https://github.com/jamesreimer/agent-workflows/commit/2d571bd7073752e2681b1d25201f42c714ffbd9b), [#10](https://github.com/jamesreimer/agent-workflows/pull/10)) + +## [0.1.3] - 2026-09-24 + +### Changed + +- Replace `PROVENANCE.md` with `GOVERNING-SOURCES.md` and the `project-repository-responsibility` anchor with `project-repository-model`; preserve governing-source pins and workflow requirement meaning, and account for these paths when deliberately updating consumer references ([`512c3fc`](https://github.com/jamesreimer/agent-workflows/commit/512c3fcda4b74a3639a0b51058a2c96433d7156d), [#9](https://github.com/jamesreimer/agent-workflows/pull/9)) +- Keep creation authority in `AGENTS.md` and reconciliation procedure in `MAINTAINING.md`, with reconciliation history retained in Git and PR evidence ([`512c3fc`](https://github.com/jamesreimer/agent-workflows/commit/512c3fcda4b74a3639a0b51058a2c96433d7156d), [#9](https://github.com/jamesreimer/agent-workflows/pull/9)) + +## [0.1.2] - 2026-09-23 + +### Fixed + +- Reconcile all five governing-source references to Standards Templates v1.1.1 while retaining edition 1.0 and unchanged normative text, and update the repository foundation to repo-template v1.2.1 without changing workflow semantics ([`e7f11b4`](https://github.com/jamesreimer/agent-workflows/commit/e7f11b4bf684223c071511dac7689da22346b49a), [#7](https://github.com/jamesreimer/agent-workflows/pull/7)) +- Replace stale first-release wording with current release discovery and document required-check/host correspondence for repository maintenance ([`e7f11b4`](https://github.com/jamesreimer/agent-workflows/commit/e7f11b4bf684223c071511dac7689da22346b49a), [#7](https://github.com/jamesreimer/agent-workflows/pull/7)) + +## [0.1.1] - 2026-09-23 + +### Changed + +- Use the complete version tag as the GitHub Release title and verify it after publication, reconciling repo-template v1.2.1 without changing workflow semantics or governing-source references ([`1072f19`](https://github.com/jamesreimer/agent-workflows/commit/1072f198cf64cc94f295931d0f3233ef6cb5c2fe), [#5](https://github.com/jamesreimer/agent-workflows/pull/5)) + +## [0.1.0] - 2026-09-23 + +_Initial pre-1.0 library release with four role profiles, five handoff templates, a reviewed-change composition, authority/evidence separation, and repository qualification support._ + +[0.2.0]: https://github.com/jamesreimer/agent-workflows/releases/tag/v0.2.0 +[0.1.3]: https://github.com/jamesreimer/agent-workflows/releases/tag/v0.1.3 +[0.1.2]: https://github.com/jamesreimer/agent-workflows/releases/tag/v0.1.2 +[0.1.1]: https://github.com/jamesreimer/agent-workflows/releases/tag/v0.1.1 +[0.1.0]: https://github.com/jamesreimer/agent-workflows/releases/tag/v0.1.0 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index bf5fbd0..58141d7 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -51,6 +51,45 @@ When changing the required job's name, source, or triggers, reconcile the live required check with the workflow so every pull request targeting the protected branch can report it. Preserve this repository's exact-candidate checkout. +## Changelog + +[CHANGELOG.md](CHANGELOG.md) follows [Common Changelog](https://common-changelog.org/) +for format only. It summarizes notable repository releases. Canonical roles, +handoffs, and workflows define reusable behavior; instantiated handoffs and +execution evidence remain with the consuming project. [GOVERNING-SOURCES.md](GOVERNING-SOURCES.md) +owns exact source pins and applicability. Git owns exact history, PRs and issues +retain decisions and implementation evidence, and GitHub Releases record +publication and release-specific notes. The changelog replaces none of these +or the actual publication authorization evidence. + +For each PR, retain a concise proposed changelog summary with supporting +references, or explain why the change is not notable. Distinguish reusable +workflow semantics, role/handoff behavior, repository maintenance, source-pin +changes, and publication mechanics where useful. Capture compatibility and +consumer implications. Reviewers verify that the summary reflects the final +candidate; not every PR warrants a release entry. + +Keep pending summaries in retained PR descriptions until a real release version +and date are selected. Do not create an `Unreleased` section, invent a version, +or attribute new work to an already published release. During release preparation, +update the prepared section alongside further notable changes included in that +release. Follow [release preparation](MAINTAINING.md#prepare-the-release) to +curate summaries, including carried-forward work, against the entire delta. +Use safe issue references under the [GitHub issue-closure guidance](roles/publication.md#github-issue-closure). + +The initial history from `v0.1.0` through `v0.2.0` is a retrospective backfill +supported by retained GitHub Release notes and UTC `publishedAt` dates, verified +tags, release commits, diffs, and merged PRs. It was not written contemporaneously. +It preserves the releases' pre-1.0 semantics, including maintenance-only patches +and compatible workflow additions. + +Consumers update deliberately under their own project authority and preserve +legitimate local adaptations. Copied workflows and instantiated handoffs do not +update automatically. A repository release neither adopts standards for consumers, +advances their source pins, transfers roles, nor grants execution or publication +authority. Repository governing-source pins advance only through actual reviewed +changes to their canonical entries. + ## Changing validation `.pre-commit-config.yaml` owns tool selection and file scope. Markdown rules live diff --git a/MAINTAINING.md b/MAINTAINING.md index 4bcd3ec..184834f 100644 --- a/MAINTAINING.md +++ b/MAINTAINING.md @@ -83,11 +83,40 @@ or verification failure; do not continue to a later publication step. test -z "$(git status --porcelain)" ``` -2. Select reviewed, merged work on `main` under the actual project contract, +2. Choose an unused version under the release identifiers above, checking local + and remote tags and GitHub Releases. Prepare the real `CHANGELOG.md` section + through ordinary reviewed work before selecting the final release candidate. + Review retained [PR summaries](CONTRIBUTING.md#changelog) since the previous + release, including carried-forward summaries. Compare them against the entire + release delta; resolve missing or unclear interpretation from retained evidence + and the responsible authors. Include all notable changes without treating + every PR as an entry. + + Follow [Common Changelog](https://common-changelog.org/): use + `## [MAJOR.MINOR.PATCH] - YYYY-MM-DD`, a version without `v`, the intended UTC + publication date, and a link to the corresponding GitHub Release. Order + releases newest first by semantic version and applicable groups as `Changed`, + `Added`, `Removed`, `Fixed`. Use concise imperative entries with relevant + commit/PR references and mark breaking changes. Preserve this library's + pre-1.0 version rules and distinguish consumer-impacting workflow changes + from maintenance and source-pin changes. + + This procedure publishes a verified annotated tag and its GitHub Release; + use the UTC calendar date of actual GitHub Release `publishedAt` as the + changelog date. Tagger time or later tag existence is not publication-time + evidence. Retain date evidence in the existing release work record. No + tag-only completion procedure is introduced here. If publication is delayed + or scope changes before tagging, correct the date, version, entries, and + links through reviewed work and qualify the resulting candidate again. + Preparing a section supplies no publication authority. + +3. Select reviewed, merged work on `main` under the actual project contract, including required independent review and human publication authorization. Record the reviewed PR-head SHA and the resulting published SHA with their content correspondence evidence. A merge or squash can produce a different SHA; release the qualified published commit, not an unmerged PR head. + Verify the changelog covers the notable complete delta and its version, date, + and release links match the planned publication. Confirm the required hosted `Repository validation` check passed for that published commit, and check out that exact commit for local qualification: @@ -106,7 +135,7 @@ or verification failure; do not continue to a later publication step. and logs: it must be completed successfully and checkout must resolve the intended release commit. Missing or failed CI stops release preparation. -3. Follow the [setup instructions](README.md#run-checks), then run the complete +4. Follow the [setup instructions](README.md#run-checks), then run the complete qualification against this exact checked-out commit: ```sh @@ -128,8 +157,8 @@ or verification failure; do not continue to a later publication step. select and qualify the resulting published commit before proceeding. Never release uncommitted fixes or treat CI as publication permission. -4. Check local tags, remote tags, and existing GitHub Releases to select an unused - identifier. Inspect all results and paginate the release list if necessary: +5. Recheck local tags, remote tags, and existing GitHub Releases to confirm the + selected identifier is still unused. Inspect all results and paginate the release list if necessary: ```sh git tag --list @@ -139,7 +168,8 @@ or verification failure; do not continue to a later publication step. A tag or release already using the intended identifier stops new creation; do not overwrite it. Review changes since the previous release, or the full - baseline for the first release. Prepare notes describing the actual changes, + baseline for the first release. Prepare notes from the changelog and detailed + Git/PR/issue evidence, keeping notable changes consistent and describing consumer impact, incompatibilities, and deliberate adoption steps. Keep the notes outside the checkout so it remains clean. Confirm GitHub's detected license remains CC0-1.0 and retain the exact SHA, checks, and release decision @@ -222,6 +252,11 @@ a formal release as a GitHub prerelease. Confirm the returned release page and its source ZIP and tar archives are available. Reverify the remote tag object and peeled commit after publication as above. +Verify the UTC calendar date of actual `publishedAt` against the changelog heading +and retain that timestamp in the existing release work record. If the date differs, +record the discrepancy and correct the changelog through a reviewed successor PR. +Preserve the published tag and tree; any successor release needs its own authority. + If publication fails after the tag push, inspect the actual remote tag and release state before any retry; preserve the published tag. Return failures or mismatches to Planning rather than moving, replacing, or deleting published diff --git a/README.md b/README.md index 139e18e..523e2ec 100644 --- a/README.md +++ b/README.md @@ -93,6 +93,10 @@ semantics, and deliberate consumer updates. Repeating reviewed-change in more projects alone does not meet that evidence need. No arbitrary adoption count is required. +Read [CHANGELOG.md](CHANGELOG.md) for concise release history and the +[changelog guidance](CONTRIBUTING.md#changelog) for its evidence and consumer +boundaries. + Follow [MAINTAINING.md](MAINTAINING.md) to prepare, qualify, and publish an authorized release. It defines the annotated-tag and publication verification procedure; passing validation does not authorize a release.