Skip to content

📝 Prepare changelog and upgrade guide at release time - #2556

Merged
simon1hofmann merged 4 commits into
mainfrom
docs/release-changelog
Sep 14, 2026
Merged

simon1hofmann merged 4 commits into
mainfrom
docs/release-changelog

Conversation

@simon1hofmann

@simon1hofmann simon1hofmann commented Sep 13, 2026

Copy link
Copy Markdown
Contributor

🤖 AI text below 🤖

Description

Feature and fix PRs currently edit shared Unreleased sections, causing merge conflicts. Prepare CHANGELOG.md and UPGRADING.md in release-preparation PRs. Contributors describe user-facing changes, limitations, and required migrations in their PR descriptions so release maintainers can collect them.

Update Core's development policy and agent guide, and regenerate the contributor guide and PR checklist from templates #449. Remove both per-PR release-documentation checkboxes and pin the templating workflow to its merge commit 377a3dcd360ed3e4d879901dbda7d21e889f435b. Core’s own policy allows changes to these files only during release preparation or when explicitly requested.

Remove the current changelog's Unreleased entries and both files' Unreleased headers and unused links. Between releases, both files contain published releases only. Release preparation gathers changes and migration instructions from Git history, merged PR descriptions, Release Drafter, and any existing notes, accounting for backports and earlier maintenance releases. The removed changelog notes concern #2537, #2544, and #2547; those PRs remain sources for the next release. The upgrade guide's v4 overview link now targets the published changelog section.

AI tools may draft release documentation; maintainers verify claims, links, attribution, and migration examples. Implements the review discussion in #2550, including preparing the upgrade guide at release time.

Validation:

  • uvx nox -s lint passed.
  • Regenerated all enabled template consumers from the pinned merge commit using Core’s workflow settings.
  • All 13 upstream template rendering tests passed, covering project types with and without changelog and upgrade-guide support.
  • Verified that published release sections are preserved and neither release-documentation file retains an Unreleased section or comparison link. The upgrade guide's v4 overview link is corrected.

This is a documentation and template update; no new runtime tests are needed. CI for the updated head remains pending. Codex drafted the changes, regenerated the template output, and ran validation.

Checklist

  • The pull request only contains commits that are focused and relevant to this change.
  • I have added appropriate tests that cover the new/changed functionality.
  • I have updated the documentation to reflect these changes.
  • The changes follow the project's style guidelines and introduce no new warnings.
  • The changes are fully tested and pass the CI checks.
  • I have reviewed my own code changes.

If PR contains AI-assisted content:

  • Any agent that created, edited, or submitted GitHub content was explicitly authorized for that scope, as required by our AI Usage Guidelines.
  • Every agent-authored or agent-edited public text body begins with the visible disclosure 🤖 *AI text below* 🤖 (titles are exempt).
  • I have disclosed AI assistance in the PR description.
  • I confirm that I have personally reviewed and understood all AI-generated content, and accept full responsibility for it.

🤖 *AI text below* 🤖

Move changelog preparation out of feature and fix PRs. Remove the Unreleased
section and its links while preserving published release notes. Keep migration
instructions with the changes that introduce them.

Regenerate contributor guidance and the PR checklist from templates#449, pin
its source revision, and align Core's development and agent policies.

Assisted-by: GPT-6 via Codex
@simon1hofmann simon1hofmann added documentation Improvements or additions to documentation continuous integration Anything related to the CI setup tooling Any issue or PR related to project tooling labels Sep 13, 2026
simon1hofmann added a commit that referenced this pull request Sep 13, 2026
🤖 *AI text below* 🤖

Remove this PR's changelog entry and reference in line with the release
preparation workflow proposed in #2556. Keep the user-facing behavior and
limitations documented in the PR description.

Assisted-by: GPT-6 via Codex
simon1hofmann added a commit that referenced this pull request Sep 13, 2026
🤖 *AI text below* 🤖

Remove this PR's changelog entry and reference in line with the release
preparation workflow proposed in #2556. Keep the user-facing behavior and
limitations documented in the PR description.

Assisted-by: GPT-6 via Codex
simon1hofmann added a commit that referenced this pull request Sep 13, 2026
🤖 *AI text below* 🤖

Merge the mapping-controls base update and remove the layout changelog entry
and reference. Neither PR now adds changelog text; release preparation will
collect their user-facing changes as proposed in #2556.

Assisted-by: GPT-6 via Codex
simon1hofmann added a commit that referenced this pull request Sep 13, 2026
🤖 *AI text below* 🤖

Remove this PR's upgrade-guide entry under the release documentation policy
proposed in #2556. Preserve migration details in the PR description for the
release maintainer to collect.

Assisted-by: GPT-6 via Codex
@burgholzer

Copy link
Copy Markdown
Member

Let's also drop the upgrade guide and generate that on the fly in release prep PRs.

simon1hofmann added a commit that referenced this pull request Sep 13, 2026
🤖 *AI text below* 🤖

Remove this PR's upgrade-guide entry under the release documentation policy
proposed in #2556. Preserve migration details in the PR description for the
release maintainer to collect.

Assisted-by: GPT-6 via Codex
simon1hofmann added a commit that referenced this pull request Sep 13, 2026
🤖 *AI text below* 🤖

Merge the mapping-controls base update and remove the layout upgrade-guide
entry. Both PR descriptions retain their migration details for release
preparation under the policy proposed in #2556.

Assisted-by: GPT-6 via Codex
🤖 *AI text below* 🤖

Prepare the upgrade guide with the changelog at release time and keep
migration instructions in feature PR descriptions. Remove its empty
Unreleased section, regenerate shared guidance and the PR checklist, and
update the template pin.

Assisted-by: GPT-6 via Codex
@simon1hofmann simon1hofmann changed the title 📝 Prepare changelogs during releases 📝 Prepare changelog and upgrade guide at release time Sep 13, 2026
@simon1hofmann
simon1hofmann marked this pull request as ready for review September 13, 2026 21:26
🤖 *AI text below* 🤖

Pin Templates #449 at merge commit 377a3dcd360ed3e4d879901dbda7d21e889f435b
and regenerate the shared files. Align Core’s release policy with the
merged guidance on changelog and upgrade-guide edits.

Assisted-by: GPT-6 via Codex

@burgholzer burgholzer left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Just one small correction. Otherwise looks good

Comment thread .github/workflows/templating.yml Outdated
🤖 *AI text below* 🤖

Label the pinned template commit as main now that Templates #449 has
merged. Keep the exact commit pin unchanged.

Assisted-by: GPT-6 via Codex
@simon1hofmann
simon1hofmann merged commit 046e59e into main Sep 14, 2026
16 of 17 checks passed
@simon1hofmann
simon1hofmann deleted the docs/release-changelog branch September 14, 2026 05:56
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

continuous integration Anything related to the CI setup documentation Improvements or additions to documentation tooling Any issue or PR related to project tooling

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants