Skip to content

Commit 15d6382

Browse files
yunfengzhou-hubyunfengzhou-hub
authored
Add release guideline
This closes #255.
1 parent 7bcd243 commit 15d6382

File tree

3 files changed

+256
-0
lines changed

3 files changed

+256
-0
lines changed

‎docs/content/README.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -37,3 +37,4 @@ applications.
3737
- [Built-in Optimizations](deep-dive/optimizations.md)
3838
- [How To](how-to)
3939
- [Deploy FeatHub Job on Alibaba Cloud](how-to/deploy-on-alibaba-cloud.md)
40+
- [Create a FeatHub Release](how-to/create-a-feathub-release.md)

‎docs/content/how-to/README.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,5 @@
11
# How To
22

33
- [Deploy FeatHub Job on Alibaba Cloud](deploy-on-alibaba-cloud.md)
4+
- [Create a FeatHub Release](create-a-feathub-release.md)
45

‎docs/content/how-to/create-a-feathub-release.md

Lines changed: 254 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,254 @@
1+
# Create a FeatHub Release
2+
3+
## Prepare for Release
4+
5+
### Create a new Milestone in Github
6+
7+
FeatHub uses [Github
8+
Milestones](https://docs.github.com/en/issues/using-labels-and-milestones-to-track-work/about-milestones)
9+
to track the issues to be solved in each release. With the release currently
10+
underway, you should create new MileStones as subsequent releases for new
11+
issues.
12+
13+
1. Navigate to the [Milestone](https://github.com/alibaba/feathub/milestones)
14+
page of FeatHub's Github Repo, and click the "New milestone" button at the
15+
top right.
16+
2. Suppose the version to be released is 0.1.0, you should create milestones
17+
whose names are "release-0.1.1" and "release-0.2.0". The milestones' due date
18+
and description need not be configured.
19+
20+
### Triage release-blocking Issues in Github
21+
22+
There could be outstanding release-blocking issues, which should be triaged
23+
before proceeding to build a release candidate. Suppose the version to be
24+
released is 0.1.0, there should have been a Milestone named "release-0.1.0"
25+
created on Github, and release-blocking issues have been attached to this
26+
milestone. Triage each unresolved issue in this milestone with one of the
27+
following resolutions:
28+
29+
- If the issue has been resolved but its state was not updated, resolve it
30+
accordingly.
31+
- If the issue has not been resolved and it is acceptable to defer this until
32+
the next release, update the issue's milestone attribute to the new version
33+
you just created. Please consider discussing this with stakeholders as
34+
appropriate.
35+
- If the issue has not been resolved and it is not acceptable to release until
36+
it is fixed, the release cannot proceed. Instead, work with the FeatHub
37+
developers to resolve the issue.
38+
39+
### Create a release branch
40+
41+
Release candidates are built from a release branch. You should create the
42+
release branch, push it to the code repository (you should probably do this once
43+
the whole process is done), and update version information on the original
44+
branch.
45+
46+
Set up the following environment variables to simplify commands that follow. (We
47+
use `bash` Unix syntax in this guide.)
48+
49+
```shell
50+
export RELEASE_VERSION="0.1.0"
51+
export SHORT_RELEASE_VERSION="0.1"
52+
export CURRENT_SNAPSHOT_VERSION="$SHORT_RELEASE_VERSION-SNAPSHOT"
53+
export NEXT_SNAPSHOT_VERSION="0.2-SNAPSHOT"
54+
```
55+
56+
If you are doing a new major/minor release (e.g. 0.1.0, 0.2.0), check out the
57+
version of the codebase from which you start the release. This may be `HEAD` of
58+
the `master` branch. Create a branch for the new version that we want to release
59+
before updating the master branch to the next development version:
60+
61+
```shell
62+
git checkout master
63+
RELEASE_VERSION=$SHORT_RELEASE_VERSION tools/releasing/create_release_branch.sh
64+
git checkout master
65+
OLD_VERSION=$CURRENT_SNAPSHOT_VERSION NEW_VERSION=$NEXT_SNAPSHOT_VERSION tools/releasing/update_branch_version.sh
66+
git checkout release-$SHORT_RELEASE_VERSION
67+
```
68+
69+
If you're creating a new bugfix release (e.g. 0.1.1), you will skip the above
70+
step and simply check out the the already existing branch for that version:
71+
72+
```shell
73+
git checkout release-$SHORT_RELEASE_VERSION
74+
```
75+
76+
If this is a major release, the newly created branch needs to be pushed to the
77+
official repository.
78+
79+
The rest of this guide assumes that commands are run in the root of a repository
80+
on the branch of the release version with the above environment variables set.
81+
82+
### Checklist to proceed to the next step
83+
84+
- All release blocking Github issues have been listed in the corresponding
85+
Milestone, and have been closed.
86+
- Release branch has been created and pushed if it is a major release.
87+
- Originating branch has the version information updated to the new version.
88+
89+
## Build a Release Candidate
90+
91+
### Build and stage Python artifacts
92+
93+
```shell
94+
OLD_VERSION=$CURRENT_SNAPSHOT_VERSION NEW_VERSION=$RELEASE_VERSION tools/releasing/update_branch_version.sh
95+
tools/releasing/create_python_sdk_release.sh
96+
```
97+
98+
You will be able to find the built source and Python release artifacts under the
99+
"tools/releasing/release/" folder.
100+
101+
102+
### Prepare a Release Note
103+
104+
See previous Release Notes [here](https://github.com/alibaba/feathub/releases)
105+
for how to write a new note for this release. The items listed in the release
106+
note should meet the following criteria:
107+
108+
- Be appropriately classified as `Bug`, `New Feature`, `Improvement`, etc.
109+
- Represent noteworthy user-facing changes, such as new functionality,
110+
backward-incompatible API changes, or performance improvements.
111+
- Have occurred since the previous release; an issue that was introduced and
112+
fixed between releases should not appear in the Release Notes.
113+
- Have an issue title that makes sense when read on its own.
114+
115+
Adjust any of the above properties to improve the clarity and presentation of
116+
the Release Notes.
117+
118+
### Stage the artifacts and Publish the Release Note
119+
120+
Set up a few environment variables to identify the release candidate being
121+
built. Start with `RC_NUM` equal to `1` and increment it for each candidate.
122+
123+
```shell
124+
export RC_NUM="1"
125+
export TAG="release-${RELEASE_VERSION}-rc${RC_NUM}"
126+
```
127+
128+
Tag and push the release commit:
129+
130+
```shell
131+
git tag -a ${TAG} -m "${TAG}"
132+
git push <remote> refs/tags/${TAG}
133+
```
134+
135+
Release manager should create a Github token with permissions to create Github
136+
release and upload the artifacts to the Feathub repository. After you have
137+
created and saved the token, create a pre-release and upload the release
138+
artifacts to Github with the following command:
139+
140+
```shell
141+
GITHUB_TOKEN=<YOUR-TOKEN> tools/releasing/create_github_release_and_upload_artifacts.sh
142+
```
143+
144+
Then, head over to the release you just created on GitHub
145+
(https://github.com/alibaba/feathub/releases/${TAG}) and publish the release
146+
note to the description of the release.
147+
148+
### Verify the artifacts
149+
150+
Release manager should guarantee the correctness of the release candidate in the
151+
following aspects:
152+
153+
- The source codes should be able to pass all the FeatHub tests. This should
154+
have been verified by FeatHub's CI on Github.
155+
- The [FeatHub end-to-end
156+
examples](https://github.com/flink-extended/feathub-examples) should be able
157+
to function correctly with the Python artifacts. This could be verified by
158+
manually triggering the corresponding
159+
[CI](https://github.com/flink-extended/feathub-examples/actions/workflows/build-and-test.yaml)
160+
with the release artifact as the Target FeatHub Python package.
161+
162+
### Checklist to proceed to the next step
163+
164+
- The release commit has been tagged and pushed to Github
165+
- The release commit has a corresponding Github Release with all the release
166+
artifacts
167+
- Release information properly described in the release note written in the
168+
Github Release.
169+
- The correctness of the source code and Python artifact have been verified and
170+
the verification result is available to reviewers (e.g. as a Github Action
171+
link).
172+
173+
## Vote on the release candidate
174+
175+
After the steps above, you should share the release candidiate with the Feathub
176+
repository admins to request their approval on this releast candidate. The
177+
sharing message should contain the following information:
178+
179+
- The link to the Github pre-release you just created, which contains the
180+
following
181+
- The release note in the description section.
182+
- The source code archive in the asset list.
183+
- The Python artifact with its .sha512 file in the asset list.
184+
- The link to the Github Action in FeatHub's repository that demonstrates the
185+
correctness of the source code.
186+
- The link to the Github Action in FeatHub's end-to-end examples' repository
187+
that demonstrates the correctness of the Python artifact.
188+
189+
Feathub repository admins are free to double-verify any of the checklist items
190+
described in sections above before they vote to approve the release candidate.
191+
The release manager and reviewers can (optionally) also do additional
192+
verification by
193+
194+
- Check hashes (e.g. `shasum -c *.sha512`)
195+
- grep for legal headers in each file.
196+
197+
If any issues are identified and should be fixed in this release during the
198+
review, fix codes should be pushed to master and release branch through the
199+
normal contributing process. Then you should go back and build a new release
200+
candidate with these changes.
201+
202+
### Checklist to proceed to the next step
203+
204+
- The Feathub repository admins agree to release the proposed candidate.
205+
206+
## Finalize the Release
207+
208+
### Deploy Python artifacts to Pypi
209+
210+
Release manager should create a PyPI account and ask the Feathub repository
211+
admins to add this account to feathub collaborator list with Maintainer role to
212+
deploy the Python artifacts to PyPI. The artifacts could be uploaded using
213+
twine(https://pypi.org/project/twine/). To install twine, just run:
214+
215+
```shell
216+
pip install --upgrade twine==1.12.0
217+
```
218+
219+
Download the python artifact (`feathub-$RELEASE_VERSION-py3-none-any.whl`) from
220+
Github release manually and upload it to [pypi.org](http://pypi.org/):
221+
222+
```shell
223+
twine upload feathub-$RELEASE_VERSION-py3-none-any.whl
224+
```
225+
226+
### Git Release
227+
228+
Create a new Git Release for the released version by copying the tag for the
229+
final release candidate, as follows:
230+
231+
```shell
232+
git tag -a "release-${RELEASE_VERSION}" refs/tags/${TAG}^{} -m "Release Feathub ${RELEASE_VERSION}"
233+
git push <remote> refs/tags/release-${RELEASE_VERSION}
234+
TAG="release-${RELEASE_VERSION}" GITHUB_TOKEN=<YOUR-TOKEN> tools/releasing/create_github_release_and_upload_artifacts.sh
235+
```
236+
237+
Then, head over to the release you just created on GitHub
238+
(https://github.com/alibaba/feathub/releases/${TAG}), publish the release note
239+
to the description of the release, and unmark it with "pre-release".
240+
241+
242+
### Close milestone for current release
243+
244+
The Github Milestone for the current release should be closed. No new issues
245+
should be linked to this milestone any longer.
246+
247+
### Final checklist
248+
249+
- Python artifacts released and indexed in the
250+
[PyPI](https://pypi.org/project/feathub/) Repository
251+
- The formal Github Release is created in the source code repository, and its
252+
description and artifact should be the same as that in the final release
253+
candidate.
254+
- Milestone for current release closed

0 commit comments

Comments
 (0)