From 700eb13ec69982cb8b789826abaa8f7e824a7435 Mon Sep 17 00:00:00 2001 From: suyanhanx Date: Sun, 25 Jun 2023 17:42:24 +0800 Subject: [PATCH 1/8] doc:polish release note Signed-off-by: suyanhanx --- .../reference/generate_release_note.md | 2 +- .../docs/contributing/reference/setup_gpg.md | 16 +++--- website/docs/contributing/release.md | 53 ++++++++++--------- 3 files changed, 38 insertions(+), 33 deletions(-) diff --git a/website/docs/contributing/reference/generate_release_note.md b/website/docs/contributing/reference/generate_release_note.md index 6ce3119a1d6..441670683df 100644 --- a/website/docs/contributing/reference/generate_release_note.md +++ b/website/docs/contributing/reference/generate_release_note.md @@ -2,7 +2,7 @@ title: Generate Release Note --- -This document describes how to generate release notes using Github: +This document describes how to generate release notes using GitHub: 1. Go to https://github.com/apache/incubator-opendal/releases/new to start a new release. 2. Fill the tag with `draft`. diff --git a/website/docs/contributing/reference/setup_gpg.md b/website/docs/contributing/reference/setup_gpg.md index 2b74918f85b..cc88e02e26b 100644 --- a/website/docs/contributing/reference/setup_gpg.md +++ b/website/docs/contributing/reference/setup_gpg.md @@ -4,7 +4,7 @@ title: Setup GPG Key > This section is a brief from the [Cryptography with OpenPGP](https://infra.apache.org/openpgp.html) guideline. -## Install gpg +## Install GPG For more details, please refer to [GPG official website](https://www.gnupg.org/download/index.html). Here shows one approach to install GPG with `apt`: @@ -12,7 +12,7 @@ For more details, please refer to [GPG official website](https://www.gnupg.org/d sudo apt install gnupg2 ``` -## Generate gpg Key +## Generate GPG Key Attentions: @@ -73,7 +73,7 @@ generator a better chance to gain enough entropy. │ │ │ │ └──────────────────────────────────────────────────────┘ -# key generatio[n will be done after your inputting the key with the following output +# key generation will be done after your inputting the key with the following output gpg: key E49B00F626B marked as ultimately trusted gpg: revocation certificate stored as '/Users/hulk/.gnupg/openpgp-revocs.d/F77B887A4F25A9468C513E9AA3008E49B00F626B.rev' public and secret key created and signed. @@ -84,7 +84,7 @@ uid [ultimate] hulk sub rsa4096 2022-07-12 [E] ``` -## Upload your key to public gpg keyserver +## Upload your key to public GPG keyserver Firstly, list your key: @@ -112,15 +112,15 @@ Among them, `keys.openpgp.org` is a randomly selected keyserver, you can use `ke ## Check whether the key is created successfully -Uploading takes about one minute, after that, you can check by your email at the corresponding keyserver. +Uploading takes about one minute; after that, you can check by your email at the corresponding keyserver. Uploading keys to the keyserver is mainly for joining a [Web of Trust](https://infra.apache.org/release-signing.html#web-of-trust). -## Add your gpg public key to the KEYS document +## Add your GPG public key to the KEYS document :::info -SVN is required for this step. +`SVN` is required for this step. ::: @@ -139,5 +139,5 @@ svn ci -m "add gpg key for YOUR_NAME" # Later on, if you are asked to enter a us ## Upload the GPG public key to your GitHub account -- Enter https://github.com/settings/keys to add GPG KEYS. +- Enter https://github.com/settings/keys to add your GPG key. - Please remember to bind the email address used in the GPG key to your GitHub account (https://github.com/settings/emails) if you find "unverified" after adding it. diff --git a/website/docs/contributing/release.md b/website/docs/contributing/release.md index a88fa4af420..76d71d93086 100644 --- a/website/docs/contributing/release.md +++ b/website/docs/contributing/release.md @@ -3,13 +3,16 @@ title: Release sidebar_position: 1 --- -This document mainly introduces how the Release Manager releases a new version in accordance with the Apache requirements. +This document mainly introduces +how the release manager releases a new version in accordance with the Apache requirements. ## Introduction -Source Release is the key point which Apache values, also, is necessary for a release. And OpenDAL will only have source release. +`Source Release` is the key point which Apache values, also, is necessary for a release. And OpenDAL will only have source release. -Please remember that publishing software has legal consequences. This guide complements the foundation-wide policies and guides: +Please remember that publishing software has legal consequences. + +This guide complements the foundation-wide policies and guides: - [Release Policy](https://www.apache.org/legal/release-policy.html) - [Release Distribution Policy](https://infra.apache.org/release-distribution) @@ -19,47 +22,49 @@ Please remember that publishing software has legal consequences. This guide comp :::caution -This section is the requirements for release manager who is the first time to be a release manager +This section is the requirements for the release manager who is the first time to be a release manager ::: -Refer to [Setup GPG Key](reference/setup_gpg.md) to make sure GPG key has been setup. +Refer to [Setup GPG Key](reference/setup_gpg.md) to make sure the GPG key has been set up. -## Github Release +## GitHub Release ### Bump Version -OpenDAL will release all package in the same version. +OpenDAL will release all packages in the same version. -- Bump version in `Cargo.toml` -- For nodejs binding, bump version in `bindings/nodejs/npm/*/package.json` -- For java binding, bump version in `bindings/java/pom.xml` +- Bump version in `Cargo.toml`. +- For the nodejs binding, bump version in `bindings/nodejs/package.json`, then use the command `napi version` in `bindings/nodejs` to bump all sub-packages' version. +- For th java binding, bump version in `bindings/java/pom.xml`. - Update `CHANGELOG.md`, refer to [Generate Release Note](reference/generate_release_note.md) for more information. -- If there are breaking changes in `core`, please also update `core/src/docs/upgrade.md` -- After all those changes, submit a PR with name `Bump to version x.y.z` +- If there are breaking changes in `core`, please also update `core/src/docs/upgrade.md`. +- After all those changes, submit a PR with name `Bump to version x.y.z`. -Take [Bump to version 0.36.1](https://github.com/apache/incubator-opendal/pull/2401) as an example. +Take [Bump to version 0.36.0](https://github.com/apache/incubator-opendal/pull/2366) as an example. -### Create Github Release +### Create a GitHub Release -After bump version PR get merged, we can create a github release: +After bump version PR gets merged, we can create a GitHub release: -- Create a tag at `main` branch on the `Bump Version` commit: `git tag -s "v0.36.1"` -- Push tags to Github: `git push --tags`. +- Create a tag at `main` branch on the `Bump Version` commit: `git tag -s "v0.36.0"` +- 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. ## ASF Release -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. +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. -### Create ASF Release +### Create an ASF Release -After Github Release has been created, we can start to create ASF Release. +After GitHub Release has been created, we can start to create ASF Release. - Checkout to released tag. -- Use release script to create a new release: `OPENDAL_VERSION= OPENDAL_VERSION_RC= ./scripts/release.sh` -- Push the newly created branch to github +- Use the release script to create a new release: `OPENDAL_VERSION= OPENDAL_VERSION_RC= ./scripts/release.sh` +- Push the newly created branch to GitHub This script will create a new release under `dist`. @@ -73,7 +78,7 @@ dist └── apache-opendal-incubating-0.36.0-src.tar.gz.sha512 ``` -### Upload artifacts to SVN dist repo +### Upload artifacts to the SVN dist repo :::info @@ -110,7 +115,7 @@ svn status svn commit -m "Prepare for ${release_version}" ``` -Visit to make sure the artifacts is uploaded correctly. +Visit to make sure the artifacts are uploaded correctly. ## Voting From 722fd2d1a73770c7261864f177b5d441eaa6b581 Mon Sep 17 00:00:00 2001 From: suyanhanx Date: Sun, 25 Jun 2023 17:50:13 +0800 Subject: [PATCH 2/8] add `build-from-source` Signed-off-by: suyanhanx --- CONTRIBUTING.md | 25 +++++++++++++++++++++++++ website/docs/contributing/release.md | 2 +- 2 files changed, 26 insertions(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 1ad43a8945c..859f7301bdf 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -96,6 +96,31 @@ Some components may require specific setup steps. Please refer to their respecti - [Node.js Binding](bindings/nodejs/CONTRIBUTING.md) - [Python Binding](bindings/python/CONTRIBUTING.md) +## Build from source + +OpenDAL uses [Cargo](https://doc.rust-lang.org/cargo/) as its build system. +To build OpenDAL, run the following command under OpenDAL's root directory: + +Only build the core component: + +```shell +cargo build +``` + +With full features enabled: + +```shell +cargo build --all-features +``` + +Build all components: + +```shell +cargo build --all +``` + +For building every component, you can refer to each component's `CONTRIBUTING` documentation for more details. + ## Code of Conduct We expect all community members to follow our [Code of Conduct](https://www.apache.org/foundation/policies/conduct.html). diff --git a/website/docs/contributing/release.md b/website/docs/contributing/release.md index 76d71d93086..19bbce558a3 100644 --- a/website/docs/contributing/release.md +++ b/website/docs/contributing/release.md @@ -284,7 +284,7 @@ More detailed checklist please refer to: 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 +https://github.com/apache/incubator-opendal/blob/main/CONTRIBUTING.md#build-from-source Thanks From a5f54b9684e99bc6a9461a03b914c0e438cbf1a8 Mon Sep 17 00:00:00 2001 From: Suyan Date: Sun, 25 Jun 2023 18:04:34 +0800 Subject: [PATCH 3/8] Update website/docs/contributing/release.md Co-authored-by: Xuanwo --- website/docs/contributing/release.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/contributing/release.md b/website/docs/contributing/release.md index 19bbce558a3..a03ac4371f4 100644 --- a/website/docs/contributing/release.md +++ b/website/docs/contributing/release.md @@ -36,7 +36,7 @@ OpenDAL will release all packages in the same version. - Bump version in `Cargo.toml`. - For the nodejs binding, bump version in `bindings/nodejs/package.json`, then use the command `napi version` in `bindings/nodejs` to bump all sub-packages' version. -- For th java binding, bump version in `bindings/java/pom.xml`. +- For the java binding, bump version in `bindings/java/pom.xml`. - Update `CHANGELOG.md`, refer to [Generate Release Note](reference/generate_release_note.md) for more information. - If there are breaking changes in `core`, please also update `core/src/docs/upgrade.md`. - After all those changes, submit a PR with name `Bump to version x.y.z`. From a510f9a86ed7640e4ef160e25e5636e14f043f66 Mon Sep 17 00:00:00 2001 From: suyanhanx Date: Sun, 25 Jun 2023 18:49:27 +0800 Subject: [PATCH 4/8] Revert "add `build-from-source`" This reverts commit 722fd2d1a73770c7261864f177b5d441eaa6b581. --- CONTRIBUTING.md | 25 ------------------------- website/docs/contributing/release.md | 2 +- 2 files changed, 1 insertion(+), 26 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 859f7301bdf..1ad43a8945c 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -96,31 +96,6 @@ Some components may require specific setup steps. Please refer to their respecti - [Node.js Binding](bindings/nodejs/CONTRIBUTING.md) - [Python Binding](bindings/python/CONTRIBUTING.md) -## Build from source - -OpenDAL uses [Cargo](https://doc.rust-lang.org/cargo/) as its build system. -To build OpenDAL, run the following command under OpenDAL's root directory: - -Only build the core component: - -```shell -cargo build -``` - -With full features enabled: - -```shell -cargo build --all-features -``` - -Build all components: - -```shell -cargo build --all -``` - -For building every component, you can refer to each component's `CONTRIBUTING` documentation for more details. - ## Code of Conduct We expect all community members to follow our [Code of Conduct](https://www.apache.org/foundation/policies/conduct.html). diff --git a/website/docs/contributing/release.md b/website/docs/contributing/release.md index 19bbce558a3..76d71d93086 100644 --- a/website/docs/contributing/release.md +++ b/website/docs/contributing/release.md @@ -284,7 +284,7 @@ More detailed checklist please refer to: 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#build-from-source +https://github.com/apache/incubator-opendal/blob/main/CONTRIBUTING.md Thanks From baae2afc93a199ea54cc7c69de91979e1293547d Mon Sep 17 00:00:00 2001 From: suyanhanx Date: Sun, 25 Jun 2023 21:10:41 +0800 Subject: [PATCH 5/8] polish Signed-off-by: suyanhanx --- website/docs/contributing/release.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/contributing/release.md b/website/docs/contributing/release.md index 76d71d93086..c320795f851 100644 --- a/website/docs/contributing/release.md +++ b/website/docs/contributing/release.md @@ -35,7 +35,7 @@ Refer to [Setup GPG Key](reference/setup_gpg.md) to make sure the GPG key has be OpenDAL will release all packages in the same version. - Bump version in `Cargo.toml`. -- For the nodejs binding, bump version in `bindings/nodejs/package.json`, then use the command `napi version` in `bindings/nodejs` to bump all sub-packages' version. +- For the nodejs binding, bump version in `bindings/nodejs/package.json` and `bindings/nodejs/npm/*/package.json`. - For th java binding, bump version in `bindings/java/pom.xml`. - Update `CHANGELOG.md`, refer to [Generate Release Note](reference/generate_release_note.md) for more information. - If there are breaking changes in `core`, please also update `core/src/docs/upgrade.md`. From 5c14777a5cb9b056a5d547f7e6ac5632e050bcf4 Mon Sep 17 00:00:00 2001 From: suyanhanx Date: Sun, 25 Jun 2023 22:06:57 +0800 Subject: [PATCH 6/8] add verify release candidate doc Signed-off-by: suyanhanx --- .../reference/verify_a_release_candidate.md | 165 ++++++++++++++++++ 1 file changed, 165 insertions(+) create mode 100644 website/docs/contributing/reference/verify_a_release_candidate.md diff --git a/website/docs/contributing/reference/verify_a_release_candidate.md b/website/docs/contributing/reference/verify_a_release_candidate.md new file mode 100644 index 00000000000..0f2737d6ab1 --- /dev/null +++ b/website/docs/contributing/reference/verify_a_release_candidate.md @@ -0,0 +1,165 @@ +--- +title: Verify a release candidate +--- + +To verify a release candidate, the following checklist could be used: + +- [ ] Download links are valid. +- [ ] Checksums and signatures. +- [ ] LICENSE/NOTICE files exist. +- [ ] No unexpected binary files. +- [ ] All source files have ASF headers. +- [ ] Can compile from source. + +:::note + +It is NOT necessary to run all checks to cast a vote for a release candidate. + +However, you should clearly state which checks you did. The release manager needs to ensure that each check was done. + +::: + +## Download links are valid + +To verify the release candidate, you need to download the release candidate from the [dist](https://dist.apache.org/repos/dist/dev/incubator/opendal/) directory. + +Use the following command to download all artifacts, replace "${release_version}-${rc_version}" with the version ID of the version to be released: + +```shell +svn co https://dist.apache.org/repos/dist/dev/opendal/${release_version}-${rc_version}/ +``` + +## Checksums and signatures + +The release candidate should have a checksum and signature file. + +For example, if the release candidate is `0.36.0-rc1`, the checksum and signature file should be: + +``` +https://dist.apache.org/repos/dist/dev/incubator/opendal/0.36.0-rc1/apache-opendal-0.36.0-rc1-src.tar.gz.sha512 +https://dist.apache.org/repos/dist/dev/incubator/opendal/0.36.0-rc1/apache-opendal-0.36.0-rc1-src.tar.gz.asc +``` + +### Verify checksums and signatures + +GnuPG is recommended here. It can be installed with the following command: + +```shell +apt-get install gnupg +# or +yum install gnupg +# or +brew install gnupg +``` + +Firstly, import the OpenDAL release manager's public key: + +```shell +curl https://downloads.apache.org/opendal/KEYS > KEYS # Download KEYS +gpg --import KEYS # Import KEYS to local +``` + +Then, trust the public key: + +```shell +gpg --edit-key # Edit the key +``` + +It will enter the interactive mode, use the following command to trust the key: + +```shell +gpg> trust +``` + +And then, select the level of trust, for example: + +``` +Please decide how far you trust this user to correctly verify other users' keys +(by looking at passports, checking fingerprints from different sources, etc.) + + 1 = I don't know or won't say + 2 = I do NOT trust + 3 = I trust marginally + 4 = I trust fully + 5 = I trust ultimately + m = back to the main menu +``` + +Select `5` to trust the key ultimately. + +Now, we could start the verification. + +Save the following content as `verify.sh`: + +```shell +#!/bin/bash + + +set -e + +YELLOW="\033[37;1m" +GREEN="\033[32;1m" +ENDCOLOR="\033[0m" + +if [ "$#" -ne 1 ]; then + echo "Usage: $0 {YOUR RELEASE TAR FILE}" >&2 + exit 1 +fi + +PKG=$1 + +if [ ! -f "$PKG" ]; then + echo "File '$PKG' does not exist." + exit 1 +fi + +echo "> Check signature" +gpg --verify "$PKG.asc" "$PKG" + +if [ $? -eq 0 ] +then + printf $GREEN"Success to verify the gpg sign"$ENDCOLOR"\n" +else + printf $YELLOW"Failed to verify the gpg sign"$ENDCOLOR"\n" +fi + +echo "> Check sha512sum" +sha512sum --check "$PKG.sha512" + +if [ $? -eq 0 ] +then + printf $GREEN"Success to verify the checksum"$ENDCOLOR"\n" +else + printf $YELLOW"Failed to verify the checksum"$ENDCOLOR"\n" +fi +``` + +Run the following command to verify the checksum and signature: + +```shell +./verify.sh apache-opendal-${release_version}-${rc_version}-src.tar.gz +``` + +You will see the following output if the verification is successful: + +``` +gpg: Signature made Wed 21 Jul 2021 10:00:00 AM CST +gpg: using RSA key 0x1234567890ABCDEF +gpg: Good signature from "Xuanwo Date: Mon, 26 Jun 2023 18:13:42 +0800 Subject: [PATCH 7/8] polish Signed-off-by: suyanhanx --- .../reference/verify_a_release_candidate.md | 51 +++---------------- 1 file changed, 8 insertions(+), 43 deletions(-) diff --git a/website/docs/contributing/reference/verify_a_release_candidate.md b/website/docs/contributing/reference/verify_a_release_candidate.md index 0f2737d6ab1..45ae55cf158 100644 --- a/website/docs/contributing/reference/verify_a_release_candidate.md +++ b/website/docs/contributing/reference/verify_a_release_candidate.md @@ -89,55 +89,20 @@ Select `5` to trust the key ultimately. Now, we could start the verification. -Save the following content as `verify.sh`: +We've provided a script to verify the checksum and signature of the release candidate. -```shell -#!/bin/bash - - -set -e - -YELLOW="\033[37;1m" -GREEN="\033[32;1m" -ENDCOLOR="\033[0m" - -if [ "$#" -ne 1 ]; then - echo "Usage: $0 {YOUR RELEASE TAR FILE}" >&2 - exit 1 -fi - -PKG=$1 +The script is in the `scripts` directory of our repository. +You can download it directly from [here](https://raw.githubusercontent.com/apache/incubator-opendal/main/scripts/check.sh) +or check it out from the repository: -if [ ! -f "$PKG" ]; then - echo "File '$PKG' does not exist." - exit 1 -fi - -echo "> Check signature" -gpg --verify "$PKG.asc" "$PKG" - -if [ $? -eq 0 ] -then - printf $GREEN"Success to verify the gpg sign"$ENDCOLOR"\n" -else - printf $YELLOW"Failed to verify the gpg sign"$ENDCOLOR"\n" -fi - -echo "> Check sha512sum" -sha512sum --check "$PKG.sha512" - -if [ $? -eq 0 ] -then - printf $GREEN"Success to verify the checksum"$ENDCOLOR"\n" -else - printf $YELLOW"Failed to verify the checksum"$ENDCOLOR"\n" -fi +```shell +git clone git@github.com:apache/incubator-opendal.git ``` -Run the following command to verify the checksum and signature: +Run the script on a specific release candidate: ```shell -./verify.sh apache-opendal-${release_version}-${rc_version}-src.tar.gz +./check.sh apache-opendal-${release_version}-${rc_version}-src.tar.gz ``` You will see the following output if the verification is successful: From a5b39674ced5035cf6129aeda7f834ad9fde0a70 Mon Sep 17 00:00:00 2001 From: suyanhanx Date: Mon, 26 Jun 2023 18:35:53 +0800 Subject: [PATCH 8/8] fix Signed-off-by: suyanhanx --- .../docs/contributing/reference/verify_a_release_candidate.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/contributing/reference/verify_a_release_candidate.md b/website/docs/contributing/reference/verify_a_release_candidate.md index 45ae55cf158..ab799a80f7c 100644 --- a/website/docs/contributing/reference/verify_a_release_candidate.md +++ b/website/docs/contributing/reference/verify_a_release_candidate.md @@ -102,7 +102,7 @@ git clone git@github.com:apache/incubator-opendal.git Run the script on a specific release candidate: ```shell -./check.sh apache-opendal-${release_version}-${rc_version}-src.tar.gz +./scripts/check.sh apache-opendal-${release_version}-${rc_version}-src.tar.gz ``` You will see the following output if the verification is successful: