Skip to content

Commit d059d4d

Browse files
max-sixtyclaude
andcommitted
docs: fix the release runbook's changelog and version-bump steps
- Changelog step renames `## [unreleased]` to the version and leaves none, so it no longer collides with the one `cargo release` recreates in the post-release bump (drops the hand-delete-the-duplicate step). - Version-change and post-release bump both use one `cargo release` invocation; the old split `version` + `replace` form breaks `prev_version`. - Summary line prints `$version has N commits...`, matching the changelog convention. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
1 parent 3583057 commit d059d4d

1 file changed

Lines changed: 18 additions & 17 deletions

File tree

web/book/src/project/contributing/development.md

Lines changed: 18 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -453,27 +453,29 @@ for when we use the main prql repo vs separate repos for bindings:
453453

454454
Currently we release in a semi-automated way:
455455

456-
1. PR & merge an updated
457-
[Changelog](https://github.com/PRQL/prql/blob/main/CHANGELOG.md). GitHub will
458-
produce a draft version at <https://github.com/PRQL/prql/releases/new>,
459-
including "New Contributors".
456+
1. If the version needs changing (for example, a planned patch release that
457+
should instead be a minor release), run
458+
`cargo release $version --no-publish --no-push --execute --no-verify --no-confirm --no-tag && task prqlc:test-all`
459+
to set it, then PR the resulting commit. Otherwise the version is already
460+
correct, set by the previous release's patch bump.
460461

461-
Use this script to generate a line introducing the enumerated changes:
462+
2. PR & merge an updated
463+
[Changelog](https://github.com/PRQL/prql/blob/main/CHANGELOG.md). Rename the
464+
`## [unreleased]` heading to the new version and date (matching the format of
465+
the entries below it) and curate its entries. Leave no `## [unreleased]`
466+
section; step 5 recreates it. GitHub will produce a draft at
467+
<https://github.com/PRQL/prql/releases/new>, including "New Contributors".
468+
469+
Generate the line that introduces the enumerated changes with:
462470

463471
```sh
464-
echo "It has $(git rev-list --count $(git rev-list --tags --max-count=1)..) commits from $(git shortlog --summary $(git rev-list --tags --max-count=1).. | wc -l | tr -d '[:space:]') contributors. Selected changes:"
472+
echo "$version has $(git rev-list --count $(git rev-list --tags --max-count=1)..) commits from $(git shortlog --summary $(git rev-list --tags --max-count=1).. | wc -l | tr -d '[:space:]') contributors. Selected changes:"
465473
```
466474

467475
When a fix closes an issue reported by someone other than the PR author,
468476
thank them in the changelog entry, e.g.
469477
`(@pr-author, #5639; reported by @issue-reporter)`.
470478

471-
2. If the current version is correct, then skip ahead. But if the version needs
472-
to be changed — for example, we had planned on a patch release, but instead
473-
require a minor release — then run
474-
`cargo release version $version -x && cargo release replace -x && task prqlc:test-all`
475-
to bump the version, and PR the resulting commit.
476-
477479
3. Ensure all changes intended for the release are merged to `main`. Then create
478480
the release (which creates the tag on the latest commit on `main`):
479481

@@ -502,12 +504,11 @@ Currently we release in a semi-automated way:
502504
503505
5. Run
504506
`cargo release patch --no-publish --no-push --execute --no-verify --no-confirm --no-tag && task prqlc:test-all`
505-
to bump the versions, then PR the resulting commit. `task prqlc:test-all`
506-
refreshes the snapshot tests that embed the version. Step 1 already added the
507-
`## [unreleased]` section, so `cargo release` inserts a second, duplicate
508-
one; remove it, leaving the CHANGELOG unchanged in this commit.
507+
to bump to the next development version, then PR the resulting commit. This
508+
recreates the `## [unreleased]` section for the next cycle, and
509+
`task prqlc:test-all` refreshes the snapshot tests that embed the version.
509510
510-
<!-- Note we used to have `cargo release version patch -x --no-confirm && cargo release replace -x --no-confirm && task prqlc:test-all`, which was simpler, but in order for `prev_version` to work, we can't separate the `patch` and `replace`, and we need `prev_version` for the prqlc version constraint (search for `prev_version` if unclear). If we moved back to upgrading the tags at the time of release rather than after, we could go back to that. -->
511+
<!-- `version` and `replace` must run in one `cargo release` invocation (not separate `cargo release version` + `cargo release replace` steps) so the `prev_version` replacement for the prqlc version constraint in target.md resolves. -->
511512
512513
6. Check whether there are [milestones](https://github.com/PRQL/prql/milestones)
513514
that need to be pushed out.

0 commit comments

Comments
 (0)