Skip to content

Commit 939eead

Browse files
alambclaude
andcommitted
Release docs: do not sync the release version back to main, describe the version bump PR
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
1 parent a0803af commit 939eead

1 file changed

Lines changed: 44 additions & 11 deletions

File tree

‎dev/release/README.md‎

Lines changed: 44 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -87,7 +87,11 @@ This means that:
8787
- The `-dev` suffix is removed on the release branch as part of preparing the
8888
release (see [Prepare PR to Update the Release Version](#2-prepare-pr-to-update-the-release-version))
8989
- `main` is bumped to the next `-dev` version immediately after a new release
90-
branch is created (see [Bump Version on main](#1b-bump-version-on-main))
90+
branch is created, via a "version bump PR" (see
91+
[Bump Version on main](#1b-bump-version-on-main))
92+
- The release version is never synced back to `main`: after a release only the
93+
changelog and the user facing documentation are synced (see
94+
[Sync Changelog and Documentation to main](#11-sync-changelog-and-documentation-to-main))
9195
- The `created_by` field written to Parquet files and the output of the SQL
9296
`version()` function show whether a build came from `main` or from a release
9397

@@ -106,9 +110,11 @@ git push -u apache branch-56 # push branch to apache remote
106110

107111
### 1b. Bump Version on main
108112

109-
Right after creating a new major release branch, create a PR against `main`
110-
that bumps the version to the next development version so that new PRs merged
111-
to `main` are labeled with the correct target release.
113+
Right after creating a new major release branch, open a "version bump PR"
114+
against `main` that bumps the version to the next development version. Merge
115+
it as soon as CI passes: PRs merged to `main` before the bump are labeled with
116+
the previous release (for example `v56.0.0` instead of `v57.0.0`) by the
117+
[release version labeler](../../ci/scripts/release_version_labeler.js).
112118

113119
For example, after creating `branch-56` from `main` at version `56.0.0-dev`,
114120
bump `main` to `57.0.0-dev`:
@@ -123,9 +129,19 @@ sed -i '' "s/const target_version = '.*'/const target_version = 'v57.0.0'/" ci/s
123129
git commit -a -m 'Bump main version to 57.0.0-dev'
124130
```
125131

132+
The version bump PR should only change:
133+
134+
- `Cargo.toml` and `Cargo.lock`
135+
- `docs/source/user-guide/configs.md` (the default `created_by` includes the version)
136+
- `ci/scripts/release_version_labeler.js`
137+
126138
The user facing crate examples (such as `docs/source/download.md`) continue to
127139
reference the latest _released_ version since `-dev` versions are never
128-
published to crates.io.
140+
published to crates.io. They are updated after the release in
141+
[Sync Changelog and Documentation to main](#11-sync-changelog-and-documentation-to-main).
142+
143+
See [#26845](https://github.com/apache/datafusion/pull/26845) for an example
144+
version bump PR.
129145

130146
This step is not needed for patch releases, which are made from an existing
131147
release branch.
@@ -523,21 +539,38 @@ Caused by:
523539
Note: [`datafusion` formula](https://formulae.brew.sh/formula/datafusion) is [updated automatically](https://github.com/Homebrew/homebrew-core/pulls?q=is%3Apr+datafusion+is%3Aclosed),
524540
so no action is needed.
525541

526-
### 11. Sync Changelog and Version to main
542+
### 11. Sync Changelog and Documentation to main
543+
544+
The crate version is **not** synced back to `main`: `main` already carries the
545+
next development version (such as `57.0.0-dev`) from
546+
[Bump Version on main](#1b-bump-version-on-main), and the released version
547+
must never appear on `main`.
527548

528-
To sync changelog version and create PR against `main`:
549+
Instead, create a PR against `main` that syncs the changelog and updates the
550+
user facing documentation to reference the new release:
529551

530552
```shell
531-
git fetch apache && git checkout -b sync_change_log_version
553+
git fetch apache && git checkout -b sync_change_log apache/main
532554
```
533555

534-
- Cherry-pick or patch the version updates from step 2
535556
- Cherry-pick or patch the changelog updates from step 5
536-
- Commit changes, `git commit -a -m 'Sync changelog and version to main'`
537-
- Push to `origin/sync_change_log_version`
557+
- Update the crate version in the user facing examples to the newly released
558+
version, for example from `55.1.0` to `56.0.0`:
559+
560+
```shell
561+
sed -i '' 's/55\.1\.0/56.0.0/' docs/source/download.md docs/source/user-guide/{crate-configuration,example-usage}.md
562+
```
563+
564+
- Do **not** change `Cargo.toml`, `Cargo.lock`, `docs/source/user-guide/configs.md`
565+
or `ci/scripts/release_version_labeler.js`, which must keep the `-dev` version
566+
- Commit changes, `git commit -a -m 'Sync changelog and docs for 56.0.0 to main'`
567+
- Push to `origin/sync_change_log`
538568
- Create a PR against `main`.
539569
- Merge to `main`.
540570

571+
The version picker for the published documentation is updated separately, see
572+
[Publish the versioned documentation](#publish-the-versioned-documentation).
573+
541574
### 12. Add the release to Apache Reporter
542575

543576
When you have published the release, please help the project by adding the release to

0 commit comments

Comments
 (0)