Skip to content

Commit bd62e5a

Browse files
alambalamb
committed
Add release management page to the documentation
1 parent 84a79e1 commit bd62e5a

File tree

4 files changed

+133
-50
lines changed

4 files changed

+133
-50
lines changed

‎dev/release/README.md‎

Lines changed: 4 additions & 50 deletions
Original file line numberDiff line numberDiff line change
@@ -19,59 +19,13 @@
1919

2020
# Release Process
2121

22-
DataFusion typically has major releases around once per month, including breaking API changes.
22+
For contributor-facing guidance on release branches and backports, see the
23+
[Contributor Guide Release Management page](../../docs/source/contributor-guide/release_management.md).
2324

24-
Patch releases are made on an adhoc basis, but we try and avoid them given the frequent major releases.
25-
26-
## Release Process Overview
27-
28-
New development happens on the `main` branch.
29-
Releases are made from branches, e.g. `branch-50` for the `50.x.y` release series.
30-
31-
To prepare for a new release series, we:
32-
33-
- Create a new branch from `main`, such as `branch-50` in the Apache repository (not in a fork)
34-
- Continue merging new features changes to `main` branch
35-
- Prepare the release branch for release:
36-
- Update version numbers in `Cargo.toml` files and create `CHANGELOG.md`
37-
- Add additional changes to the release branch as needed
38-
- When the code is ready, create GitHub tags release candidate (rc) artifacts from the release branch.
39-
- After the release is approved, publish to [crates.io], the ASF distribution servers, and GitHub tags.
40-
41-
To add changes to the release branch, depending on the change we either:
42-
43-
- Fix the issue on `main` and then backport the change to the release branch (e.g. [#18129])
44-
- Fix the issue on the release branch and then forward-port the change back to `main` (e.g.[#18057])
25+
The rest of this guide contains the commands for maintainers to create release
26+
candidates and run the release process.
4527

4628
[crates.io]: https://crates.io/crates/datafusion
47-
[#18129]: https://github.com/apache/datafusion/pull/18129
48-
[#18057]: https://github.com/apache/datafusion/pull/18057
49-
50-
## Backporting (add changes) to `branch-*` branch
51-
52-
If you would like to propose your change for inclusion in a patch release, the
53-
change must be applied to the relevant release branch. To do so please follow
54-
these steps:
55-
56-
1. Find (or create) the issue for the incremental release ([example release issue]) and discuss the proposed change there with the maintainers.
57-
2. Follow normal workflow to create PR to `main` branch and wait for its approval and merge.
58-
3. After PR is squash merged to `main`, branch from most recent release branch (e.g. `branch-50`), cherry-pick the commit and create a PR targeting the release branch [example backport PR].
59-
60-
For example, to backport commit `12345` from `main` to `branch-50`:
61-
62-
```shell
63-
git checkout branch-50
64-
git checkout -b backport_to_50
65-
git cherry-pick 12345 # your git commit hash
66-
git push -u <your fork>
67-
# make a PR as normal targeting branch-50, prefixed with [branch-50]
68-
```
69-
70-
It is also acceptable to fix the issue directly on the release branch first
71-
and then cherry-pick the change back to `main` branch in a new PR.
72-
73-
[example release issue]: https://github.com/apache/datafusion/issues/18072
74-
[example backport pr]: https://github.com/apache/datafusion/pull/18131
7529

7630
## Release Prerequisites
7731

‎docs/source/contributor-guide/index.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -99,6 +99,11 @@ If you are concerned that a larger design will be lost in a string of small PRs,
9999

100100
Note all commits in a PR are squashed when merged to the `main` branch so there is one commit per PR after merge.
101101

102+
## Release Management and Backports
103+
104+
Contributor-facing guidance for release branches, patch releases, and backports
105+
is documented in the [Release Management](release_management.md) guide.
106+
102107
## Conventional Commits & Labeling PRs
103108

104109
We generate change logs for each release using an automated process that will categorize PRs based on the title

‎docs/source/contributor-guide/release_management.md‎

Lines changed: 123 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,123 @@
1+
<!---
2+
Licensed to the Apache Software Foundation (ASF) under one
3+
or more contributor license agreements. See the NOTICE file
4+
distributed with this work for additional information
5+
regarding copyright ownership. The ASF licenses this file
6+
to you under the Apache License, Version 2.0 (the
7+
"License"); you may not use this file except in compliance
8+
with the License. You may obtain a copy of the License at
9+
10+
http://www.apache.org/licenses/LICENSE-2.0
11+
12+
Unless required by applicable law or agreed to in writing,
13+
software distributed under the License is distributed on an
14+
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
15+
KIND, either express or implied. See the License for the
16+
specific language governing permissions and limitations
17+
under the License.
18+
-->
19+
20+
# Release Management
21+
22+
This page describes DataFusion release branches and backports. For the
23+
maintainer release guide, including release candidate artifacts, voting, and
24+
publication, see [the release process README in `dev/release`].
25+
26+
## Overview
27+
28+
DataFusion typically has a major release about once per month, including
29+
breaking API changes. Patch releases are made on an ad hoc basis, but we try to
30+
avoid them because major releases are frequent.
31+
32+
New development happens on the [`main` branch]. Releases are made from release
33+
branches named `branch-NN`, such as [`branch-50`] for the `50.x.y` release
34+
series.
35+
36+
In general:
37+
38+
- New features land on [`main`]
39+
- Patch releases are cut from the corresponding `branch-NN`
40+
- Only targeted, low-risk fixes should be added to a release branch
41+
42+
Changes reach a release branch in one of two ways:
43+
44+
- (Most common) Fix the issue on `main` and then backport the merged change to the release branch
45+
- Fix the issue on the release branch and then forward-port the change to `main`
46+
47+
Releases are coordinated in a GitHub issue, such as the
48+
[release issue for 50.3.0]. If you think a fix should be included in a patch
49+
release, discuss it on the relevant tracking issue first. You can also open the
50+
backport PR first and then link it from the tracking issue.
51+
52+
To prepare for a new release series, maintainers:
53+
54+
- Create a new branch from `main`, such as `branch-50`, in the Apache repository
55+
- Continue merging new features to `main`
56+
- Prepare the release branch for release by updating versions, changelog content,
57+
and any additional release-specific fixes via the
58+
[Backport Workflow](#backport-workflow)
59+
- Create release candidate artifacts from the release branch
60+
- After approval, publish to crates.io, ASF distribution servers, and Git tags
61+
62+
## Backport Workflow
63+
64+
The usual workflow is:
65+
66+
1. Fix on `main` first, and merge the fix via a normal PR workflow.
67+
2. Cherry-pick the merged commit onto the release branch.
68+
3. Open a backport PR targeting the release branch (examples below).
69+
70+
- [Example backport PR]
71+
- [Additional backport PR example]
72+
73+
### Inputs
74+
75+
To backport a change, gather the following information:
76+
77+
- Target branch, such as `apache/branch-52`
78+
- The release tracking issue URL, such as https://github.com/apache/datafusion/issues/19692
79+
- The original PR URL, such as https://github.com/apache/datafusion/pull/20192
80+
- Optional explicit commit SHA to backport
81+
82+
### Apply the Backport
83+
84+
Start from the target release branch, create a dedicated backport branch, and
85+
use `git cherry-pick`. For example, to backport PR #1234 to `branch-52` when
86+
the commit SHA is `abc123`, run:
87+
88+
```bash
89+
git checkout apache/branch-52
90+
git checkout -b alamb/backport_1234
91+
git cherry-pick abc123
92+
```
93+
94+
### Test
95+
96+
Run tests as described in the [testing documentation].
97+
98+
### Open the PR
99+
100+
Create a PR against the release branch, not `main`, and prefix it with
101+
`[branch-NN]` to show which release branch the backport targets. For example:
102+
103+
- `[branch-52] fix: validate inter-file ordering in eq_properties() (#20329)`
104+
105+
Use a PR description that links the tracking issue, original PR, and target
106+
branch, for example:
107+
108+
```markdown
109+
- Part of <tracking-issue-url>
110+
- Closes <backport-issue-url> on <branch-name>
111+
112+
This PR:
113+
114+
- Backports <original-pr-url> from @<author> to the <branch-name> line
115+
```
116+
117+
[`main` branch]: https://github.com/apache/datafusion/tree/main
118+
[`branch-50`]: https://github.com/apache/datafusion/tree/branch-50
119+
[the release process readme in `dev/release`]: https://github.com/apache/datafusion/blob/main/dev/release/README.md
120+
[release issue for 50.3.0]: https://github.com/apache/datafusion/issues/18072
121+
[example backport pr]: https://github.com/apache/datafusion/pull/18131
122+
[additional backport pr example]: https://github.com/apache/datafusion/pull/20792
123+
[testing documentation]: testing.md

‎docs/source/index.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -163,6 +163,7 @@ To get started, see
163163
contributor-guide/testing
164164
contributor-guide/api-health
165165
contributor-guide/howtos
166+
contributor-guide/release_management
166167
contributor-guide/roadmap
167168
contributor-guide/governance
168169
contributor-guide/inviting

0 commit comments

Comments
 (0)