This is an automated email from the ASF dual-hosted git repository.
xuanwo pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/incubator-opendal.git
The following commit(s) were added to refs/heads/main by this push:
new 82f987723 docs: update release doc (#3306)
82f987723 is described below
commit 82f98772363a1548f9184c07f58cc85fcdf857ae
Author: Suyan <[email protected]>
AuthorDate: Mon Oct 16 20:08:48 2023 +0800
docs: update release doc (#3306)
---
scripts/release.sh | 2 +-
website/community/committers/release.md | 82 +++++++++++++++++++++------------
2 files changed, 53 insertions(+), 31 deletions(-)
diff --git a/scripts/release.sh b/scripts/release.sh
index 6854b97cf..50eebd04a 100755
--- a/scripts/release.sh
+++ b/scripts/release.sh
@@ -28,7 +28,7 @@ fi
# tar source code
release_version=${OPENDAL_VERSION}
# rc versions
-rc_version=${OPENDAL_VERSION_RC:rc.1}
+rc_version="${OPENDAL_VERSION_RC:-rc.1}"
# Corresponding git repository branch
git_branch=release-${release_version}-${rc_version}
diff --git a/website/community/committers/release.md
b/website/community/committers/release.md
index 75a00a5ef..f6aa69d56 100644
--- a/website/community/committers/release.md
+++ b/website/community/committers/release.md
@@ -18,11 +18,22 @@ This guide complements the foundation-wide policies and
guides:
- [Release Distribution Policy](https://infra.apache.org/release-distribution)
- [Release Creation Process](https://infra.apache.org/release-publishing.html)
+## Some Terminology of release
+
+In the context of our release, we use several terms to describe different
stages of the release process.
+
+Here's an explanation of these terms:
+
+- `opendal_version`: the version of OpenDAL to be released, like `0.36.0`.
+- `release_version`: the version of release candidate, like `0.36.0-rc.1`.
+- `rc_version`: the minor version for voting round, like `rc.1`.
+- `maven_artifact_number`: the number for Maven staging artifacts, like
`1010`. The number can be found by searching "opendal" on
https://repository.apache.org/#stagingRepositories. And the Maven staging
artifacts will be created automatically when we push a git tag to GitHub for
now.
+
## Preparation
:::caution
-This section is the requirements for the release manager who is the first time
to be a release manager.
+This section is the requirements for individuals who are new to the role of
release manager.
:::
@@ -56,7 +67,7 @@ Thanks
${name}
```
-## Start tracking issues about the next release
+## Start a tracking issue about the next release
Start a tracking issue on GitHub for the upcoming release to track all tasks
that need to be completed.
@@ -116,32 +127,37 @@ For details of each step, please refer to:
https://opendal.apache.org/docs/contr
### Bump version in project
-Bump all parts' version in the project to the new opendal version.
+Bump all components' version in the project to the new opendal version.
Please note that this version is the exact version of the release, not the
release candidate version.
- rust core: bump version in `Cargo.toml`
- cpp binding: bump version in `bindings/cpp/CMakeLists.txt`
- haskell binding: bump version and update the `tag` field of
`source-repository this` in `bindings/haskell/opendal.cabal`
- java binding: bump version in `bindings/java/pom.xml`
-- nodejs binding: bump version in `bindings/nodejs/package.json` and
`bindings/nodejs/npm/*/package.json`
+- node.js binding: bump version in `bindings/nodejs/package.json` and
`bindings/nodejs/npm/*/package.json`
### Update docs
- Update `CHANGELOG.md`, refer to [Generate Release
Note](reference/generate_release_note.md) for more information.
- Update `core/src/docs/upgrade.md` if there are breaking changes in `core`
+- Make sure every released bindings' `upgrade.md` has been updated.
+ - java: `bindings/java/upgrade.md`
+ - node.js: `bindings/nodejs/upgrade.md`
+ - python: `bindings/python/upgrade.md`
### Push release candidate tag
-After bump version PR gets merged, we can create a GitHub release:
+After bump version PR gets merged, we can create a GitHub release for the
release candidate:
- Create a tag at `main` branch on the `Bump Version` / `Patch up version`
commit: `git tag -s "v0.36.0-rc.1"`, please correctly check out the
corresponding commit instead of directly tagging on the main branch.
- Push tags to GitHub: `git push --tags`.
- Create Release on the newly created tag
- - If there are breaking changes, please add the content from `upgrade.md`
before.
+ - If there are breaking changes, please add the content from `upgrade.md`
before.
:::note
Pushing a Git tag to GitHub repo will trigger a GitHub Actions workflow that
creates a staging Maven release on https://repository.apache.org which can be
verified on voting.
+And
:::
@@ -151,16 +167,21 @@ If any step in the ASF Release process fails and requires
code changes,
we will abandon that version and prepare for the next one.
Our release page will only display ASF releases instead of GitHub Releases.
-- `opendal_version`: the version for opendal, like `0.36.0`.
-- `release_version`: the version for voting, like `0.36.0-rc.1`.
-- `rc_version`: the minor version for voting, like `rc.1`.
+Additionally, we should also drop the staging Maven artifacts on
https://repository.apache.org.
### Create an ASF Release
After GitHub Release has been created, we can start to create ASF Release.
-- Checkout to released tag.
-- Use the release script to create a new release:
`OPENDAL_VERSION=<opendal_version> OPENDAL_VERSION_RC=<rc_version>
./scripts/release.sh`
+- Checkout to released tag. (e.g. `git checkout v0.36.0-rc.1`, tag is created
in the previous step)
+- Use the release script to create a new release:
`OPENDAL_VERSION=<opendal_version> OPENDAL_VERSION_RC=<rc_version>
./scripts/release.sh`(e.g. `OPENDAL_VERSION=0.36.0 OPENDAL_VERSION_RC=rc.1
./scripts/release.sh`)
+ - This script will do the following things:
+ - Create a new branch named by `release-${release_version}` from the
tag
+ - Generate the release candidate artifacts under `dist`, including:
+ - `apache-opendal-incubating-${release_version}-src.tar.gz`
+ - `apache-opendal-incubating-${release_version}-src.tar.gz.asc`
+ - `apache-opendal-incubating-${release_version}-src.tar.gz.sha512`
+ - Check the header of the source code. This step needs docker to run.
- Push the newly created branch to GitHub
This script will create a new release under `dist`.
@@ -218,10 +239,10 @@ Visit
<https://dist.apache.org/repos/dist/dev/incubator/opendal/> to make sure t
To verify the Maven staging artifacts in the next step, close the Nexus
staging repo as below.
-- `maven_artifact_number`: the number for Maven staging artifacts, like `1010`.
-
1. Open https://repository.apache.org/#stagingRepositories with your Apache ID
login.
-2. Find the artifact `orgapacheopendal-${maven_artifact_number}`, click
"Close".
+2. Find the artifact `orgapacheopendal-${maven_artifact_number}`, click the
"Close" button.
+
+The `close` operation means that the artifacts are ready for voting.
:::caution
@@ -234,17 +255,13 @@ If the vote failed, click "Drop" to drop the staging
Maven artifacts.
If you accidentally published wrong or unexpected artifacts, like wrong
signature files, wrong sha256 files,
please cancel the release for the current `release_version`,
_increase th RC counting_ and re-initiate a release with the new
`release_version`.
+And remember to delete the wrong artifacts from the SVN dist repo.
+Additionally, you should also drop the staging Maven artifacts on
https://repository.apache.org.
## Voting
As an incubating project, OpenDAL requires votes from both the OpenDAL
Community and Incubator Community.
-- `opendal_version`: the version for opendal, like `0.36.0`.
-- `release_version`: the version for voting, like `0.36.0-rc.1`.
-- `maven_artifact_number`: the number for Maven staging artifacts, like `1010`.
-
-Specifically, the `maven_artifact_number` can be found by searching "opendal"
on https://repository.apache.org/#stagingRepositories.
-
### OpenDAL Community Vote
OpenDAL Community Vote should send email to: <[email protected]>:
@@ -306,7 +323,7 @@
https://github.com/apache/incubator-opendal/tree/main/scripts
To compile from source, please refer to:
https://github.com/apache/incubator-opendal/blob/main/CONTRIBUTING.md
-Here is python script in release to help you verify the release candidate:
+Here is a Python script in release to help you verify the release candidate:
./scripts/verify.py
@@ -471,9 +488,6 @@ Example:
<https://lists.apache.org/thread/h3x9pq1djpg76q3ojpqmdr3d0o03fld1>
### Push the release git tag
-- `opendal_version`: the version for opendal, like `0.36.0`.
-- `release_version`: the version for the passed candidate, like `0.36.0-rc.1`.
-
```shell
# Checkout the tags that passed VOTE
git checkout ${release_version}
@@ -485,9 +499,6 @@ git push origin ${opendal_version}
### Publish artifacts to SVN RELEASE branch
-- `opendal_version`: the version for opendal, like `0.36.0`.
-- `release_version`: the version for voting, like `0.36.0-rc.1`.
-
```shell
svn mv
https://dist.apache.org/repos/dist/dev/incubator/opendal/${release_version}
https://dist.apache.org/repos/dist/release/incubator/opendal/${opendal_version}
-m "Release ${opendal_version}"
```
@@ -500,10 +511,10 @@ Take [Add 0.39.0 release link to
download.md](https://github.com/apache/incubato
### Release Maven artifacts
-- `maven_artifact_number`: the number for Maven staging artifacts, like `1010`.
-
1. Open https://repository.apache.org/#stagingRepositories.
-2. Find the artifact `orgapacheopendal-${maven_artifact_number}`, click
"Release".
+2. Find the artifact `orgapacheopendal-${maven_artifact_number}`, click the
"Release" button.
+
+It will take some time to sync the Maven artifacts to the Maven Central.
:::caution
@@ -511,10 +522,21 @@ If the vote failed, click "Drop" to drop the staging
Maven artifacts.
:::
+### Create a GitHub Release
+
+- Click [here](https://github.com/apache/incubator-opendal/releases/new) to
create a new release.
+- Pick the git tag of this release version from the dropdown menu.
+- Make sure the branch target is `main`.
+- Generate the release note by clicking the `Generate release notes` button.
+- Add the release note from every component's `upgrade.md` if there are
breaking changes before the content generated by GitHub. Check them carefully.
+- Publish the release.
+
### Send the announcement
Send the release announcement to `[email protected]` and CC
`[email protected]`.
+Instead of adding breaking changes, let's include the new features as "notable
changes" in the announcement.
+
Title:
```
