Skip to content

Gate release on smoke; align CHANGELOG scaffold to an Unreleased section#5

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
nathanschepers merged 1 commit into from
Jul 23, 2026
Merged

Gate release on smoke; align CHANGELOG scaffold to an Unreleased section #5

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 11 additions & 0 deletions DOCS-STYLE.md
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -80,3 +80,14 @@ parent project) is a delta on the skeleton, not a separate template.
- The section sits between Development and License.
- At maturity, the section is deleted wholesale, along with the intro's stability hedge. It is
never softened in place.

## Changelog

- `CHANGELOG.md` at the repository root. Title heading `# Changelog`.
- One section per release: `## <version> - YYYY-MM-DD`, newest first. Versions carry no leading `v`.
- A `## Unreleased` section sits above the newest release section while unreleased changes exist. A pull request that changes observable behavior adds its entry to this section in the same pull request.
- At release, the `## Unreleased` heading becomes `## <version> - <date>`.
- An entry is one bullet: a complete sentence, verb-first past tense ("Added", "Fixed", "Removed") or the artifact as subject with "now" stating the new behavior, ending with the pull-request reference in parentheses (`(#NN)`).
- Entries state observable behavior: API, configuration, wire formats, platform and toolchain support, shipped dependencies. Internal refactors, CI changes, and documentation-only changes get no entry.
- `**BACKWARDS INCOMPATIBLE:**` prefixes a breaking-change entry; such entries lead their section. `**SECURITY:**` prefixes a security-fix entry. Neither carries further apparatus.
- An entry for changed existing behavior names the old and the new behavior.
6 changes: 3 additions & 3 deletions README.md
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -10,9 +10,9 @@ Includes:
- **GitHub Actions CI** — lint / types / docs / test matrix (`python_min` through 3.14)
- **Release pipeline** — PyPI via Trusted Publishing; projects with a Dockerfile (web services,
currently) also push a multi-arch image to GHCR. No tokens in either path — Trusted Publishing
and `GITHUB_TOKEN` respectively. Once the publish jobs succeed, a tag push creates a GitHub
Release with notes from the matching `## <version>` section of `CHANGELOG.md`; the release fails
if that section is missing.
and `GITHUB_TOKEN` respectively. Once the publish jobs succeed and the published package is
verified to install and import, a tag push creates a GitHub Release with notes from the matching
`## <version>` section of `CHANGELOG.md`; the release fails if that section is missing.
- **Dependabot** for actions and dependencies
- A generated **SETUP.md** — the go-public checklist (branch protection, RTD import, Trusted
Publisher registration)
Expand Down
2 changes: 1 addition & 1 deletion template/.github/workflows/release.yml.jinja
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -124,7 +124,7 @@ jobs:
labels: ${{ steps.meta.outputs.labels }}
[% endif %]
release:
needs: [ [% if native_extension %]wheels, sdist[% else %]build[% endif %], check-version[% if publish_to_pypi %], publish[% endif %][% if web_service %], image[% endif %] ]
needs: [ [% if native_extension %]wheels, sdist[% else %]build[% endif %], check-version[% if publish_to_pypi %], publish, smoke[% endif %][% if web_service %], image[% endif %] ]
if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/')
runs-on: ubuntu-latest
permissions:
Expand Down
2 changes: 1 addition & 1 deletion template/CHANGELOG.md.jinja
View file
Open in desktop
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
# Changelog

## 0.0.1.dev0
## Unreleased

- Initial project scaffold.
3 changes: 2 additions & 1 deletion template/SETUP.md.jinja
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -51,7 +51,8 @@ Then create the GitHub environment: `gh api -X PUT repos/[[ github_org ]]/[[ rep
## 4. Release

```
# bump pyproject version and add a matching `## <version>` section to CHANGELOG.md,
# bump pyproject version and rename CHANGELOG.md's `## Unreleased` heading to
# `## <version> - <date>` (e.g. `## 0.1.0 - 2026-01-15`),
# THEN regenerate the lock (uv sync --locked fails otherwise):
uv lock
git commit -am "Release 0.1.0" && git push # via PR if main is protected
Expand Down