diff --git a/website/docs/contributing/_category_.yml b/website/docs/contributing/_category_.yml new file mode 100644 index 000000000000..b5c31ea49153 --- /dev/null +++ b/website/docs/contributing/_category_.yml @@ -0,0 +1,24 @@ +# Licensed to the Apache Software Foundation (ASF) under one +# or more contributor license agreements. See the NOTICE file +# distributed with this work for additional information +# regarding copyright ownership. The ASF licenses this file +# to you under the Apache License, Version 2.0 (the +# "License"); you may not use this file except in compliance +# with the License. You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, +# software distributed under the License is distributed on an +# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +# KIND, either express or implied. See the License for the +# specific language governing permissions and limitations +# under the License. + +position: 4 +label: 'Contributing' +collapsible: true +collapsed: true +link: + type: generated-index + title: Contributing diff --git a/website/docs/contributing/reference/_category_.yml b/website/docs/contributing/reference/_category_.yml new file mode 100644 index 000000000000..2cd55b984f7c --- /dev/null +++ b/website/docs/contributing/reference/_category_.yml @@ -0,0 +1,24 @@ +# Licensed to the Apache Software Foundation (ASF) under one +# or more contributor license agreements. See the NOTICE file +# distributed with this work for additional information +# regarding copyright ownership. The ASF licenses this file +# to you under the Apache License, Version 2.0 (the +# "License"); you may not use this file except in compliance +# with the License. You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, +# software distributed under the License is distributed on an +# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +# KIND, either express or implied. See the License for the +# specific language governing permissions and limitations +# under the License. + +position: 2 +label: 'Reference' +collapsible: true +collapsed: true +link: + type: generated-index + title: Reference diff --git a/website/docs/contributing/reference/generate_release_note.md b/website/docs/contributing/reference/generate_release_note.md new file mode 100644 index 000000000000..6ce3119a1d64 --- /dev/null +++ b/website/docs/contributing/reference/generate_release_note.md @@ -0,0 +1,12 @@ +--- +title: Generate Release Note +--- + +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`. +3. Click on `Generate release notes` to generate them. +4. Copy the generated content and close the page. + +Please note that we only use this feature to generate release notes, so please do not click on `Publish Release` or `Save draft`. We will publish it after creating the tag. diff --git a/website/docs/contributing/reference/setup_gpg.md b/website/docs/contributing/reference/setup_gpg.md new file mode 100644 index 000000000000..2b74918f85be --- /dev/null +++ b/website/docs/contributing/reference/setup_gpg.md @@ -0,0 +1,143 @@ +--- +title: Setup GPG Key +--- + +> This section is a brief from the [Cryptography with OpenPGP](https://infra.apache.org/openpgp.html) guideline. + +## 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`: + +```shell +sudo apt install gnupg2 +``` + +## Generate gpg Key + +Attentions: + +- Name is best to keep consistent with your full name of Apache ID; +- Email should be the Apache email; +- Name is best to only use English to avoid garbled. + +Run `gpg --full-gen-key` and complete the generation interactively: + +```shell +gpg (GnuPG) 2.2.20; Copyright (C) 2020 Free Software Foundation, Inc. +This is free software: you are free to change and redistribute it. +There is NO WARRANTY, to the extent permitted by law. + +Please select what kind of key you want: + (1) RSA and RSA (default) + (2) DSA and Elgamal + (3) DSA (sign only) + (4) RSA (sign only) + (14) Existing key from card +Your selection? 1 # input 1 +RSA keys may be between 1024 and 4096 bits long. +What keysize do you want? (2048) 4096 # input 4096 +Requested keysize is 4096 bits +Please specify how long the key should be valid. + 0 = key does not expire + = key expires in n days + w = key expires in n weeks + m = key expires in n months + y = key expires in n years +Key is valid for? (0) 0 # input 0 +Key does not expire at all +Is this correct? (y/N) y # input y + +GnuPG needs to construct a user ID to identify your key. + +Real name: Hulk Lin # input your name +Email address: hulk@apache.org # input your email +Comment: # input some annotations, optional +You selected this USER-ID: + "Hulk " + +Change (N)ame, (C)omment, (E)mail or (O)kay/(Q)uit? O # input O +We need to generate a lot of random bytes. It is a good idea to perform +some other action (type on the keyboard, move the mouse, utilize the +disks) during the prime generation; this gives the random number +generator a better chance to gain enough entropy. +We need to generate a lot of random bytes. It is a good idea to perform +some other action (type on the keyboard, move the mouse, utilize the +disks) during the prime generation; this gives the random number +generator a better chance to gain enough entropy. + +# Input the security key +┌──────────────────────────────────────────────────────┐ +│ Please enter this passphrase │ +│ │ +│ Passphrase: _______________________________ │ +│ │ +│ │ +└──────────────────────────────────────────────────────┘ +# key generatio[n 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. + +pub rsa4096 2022-07-12 [SC] + F77B887A4F25A9468C513E9AA3008E49B00F626B +uid [ultimate] hulk +sub rsa4096 2022-07-12 [E] +``` + +## Upload your key to public gpg keyserver + +Firstly, list your key: + +```shell +gpg --list-keys +``` + +The output is like: + +```shell +------------------------------- +pub rsa4096 2022-07-12 [SC] + F77B887A4F25A9468C513E9AA3008E49B00F626B +uid [ultimate] hulk +sub rsa4096 2022-07-12 [E] +``` + +Then, send your key id to key server: + +```shell +gpg --keyserver keys.openpgp.org --send-key # e.g., F77B887A4F25A9468C513E9AA3008E49B00F626B +``` + +Among them, `keys.openpgp.org` is a randomly selected keyserver, you can use `keyserver.ubuntu.com` or any other full-featured keyserver. + +## 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 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 + +:::info + +SVN is required for this step. + +::: + +The svn repository of the release branch is: https://dist.apache.org/repos/dist/release/incubator/opendal + +Please always add the public key to KEYS in the release branch: + +```shell +svn co https://dist.apache.org/repos/dist/release/incubator/opendal opendal-dist +# As this step will copy all the versions, it will take some time. If the network is broken, please use svn cleanup to delete the lock before re-execute it. +cd opendal-dist +(gpg --list-sigs YOUR_NAME@apache.org && gpg --export --armor YOUR_NAME@apache.org) >> KEYS # Append your key to the KEYS file +svn add . # It is not needed if the KEYS document exists before. +svn ci -m "add gpg key for YOUR_NAME" # Later on, if you are asked to enter a username and password, just use your apache username and password. +``` + +## Upload the GPG public key to your GitHub account + +- Enter https://github.com/settings/keys to add GPG KEYS. +- 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 new file mode 100644 index 000000000000..a88fa4af420e --- /dev/null +++ b/website/docs/contributing/release.md @@ -0,0 +1,372 @@ +--- +title: Release +sidebar_position: 1 +--- + +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. + +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) +- [Release Creation Process](https://infra.apache.org/release-publishing.html) + +## Preparation + +:::caution + +This section is the requirements for 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. + +## Github Release + +### Bump Version + +OpenDAL will release all package 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` +- 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` + +Take [Bump to version 0.36.1](https://github.com/apache/incubator-opendal/pull/2401) as an example. + +### Create Github Release + +After bump version PR get 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 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. + +### 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 + +This script will create a new release under `dist`. + +For example: + +```shell +> tree dist +dist +├── apache-opendal-incubating-0.36.0-src.tar.gz +├── apache-opendal-incubating-0.36.0-src.tar.gz.asc +└── apache-opendal-incubating-0.36.0-src.tar.gz.sha512 +``` + +### Upload artifacts to SVN dist repo + +:::info + +SVN is required for this step. + +::: + +The svn repository of the dev branch is: https://dist.apache.org/repos/dist/dev/incubator/opendal + +First, checkout OpenDAL to local directory: + +```shell +# As this step will copy all the versions, it will take some time. If the network is broken, please use svn cleanup to delete the lock before re-execute it. +svn co https://dist.apache.org/repos/dist/dev/incubator/opendal opendal-dist-dev +``` + +Then, upload the artifacts: + +> The `${release_version}` here should be like `0.36.0-rc1` + +```shell +cd opendal-dist-dev +# create a directory named by version +mkdir ${release_version} +# copy source code and signature package to the versioned directory +cp ${repo_dir}/dist/* ${release_version}/ +# check svn status +svn status +# add to svn +svn add ${release_version} +# check svn status +svn status +# commit to SVN remote server +svn commit -m "Prepare for ${release_version}" +``` + +Visit to make sure the artifacts is uploaded correctly. + +## 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-rc1` + +### OpenDAL Community Vote + +OpenDAL Community Vote should send email to: : + +Title: + +``` +[VOTE] Release Apache OpenDAL(incubating) ${release_version} - OpenDAL Vote Round 1 +``` + +Content: + +``` +Hello, Apache OpenDAL(incubating) Community, + +This is a call for a vote to release Apache OpenDAL(incubating) version ${opendal_version}. + +The tag to be voted on is ${opendal_version}. + +The release candidate: + +https://dist.apache.org/repos/dist/dev/incubator/opendal/${release_version}/ + +Keys to verify the release candidate: + +https://downloads.apache.org/incubator/opendal/KEYS + +Git branch for the release: + +https://github.com/apache/incubator-opendal/tree/release-${release_version} + +Please download, verify, and test. + +The VOTE will pass after got 3 binding approve. + +[ ] +1 approve +[ ] +0 no opinion +[ ] -1 disapprove with the reason + +To learn more about apache opendal, please see https://opendal.apache.org/ + +Checklist for reference: + +[ ] 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 + +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 + +Thanks + +${name} +``` + +Example: + +After at least 3 +1 binding vote (from OpenDAL Podling PMC member and committers) and no veto, claim the vote result: + +Title: + +``` +[Result][VOTE] Release Apache OpenDAL(incubating) ${release_version} - OpenDAL Vote Round 1 +``` + +Content: + +``` +Hello, Apache OpenDAL(incubating) Community, + +The vote to release Apache OpenDAL(Incubating) ${release_version} has passed. + +The vote PASSED with 3 binding +1 and 0 -1 vote: + +Binding votes: + +- xxx +- yyy +- zzz + +Vote thread: ${vote_thread_url} + +Thanks + +${name} +``` + +Example: + +### Incubator Community Vote + +Incubator Community Vote should send email to: : + +Title: + +``` +[VOTE] Release Apache OpenDAL(incubating) ${release_version} - Incubator Vote Round 1 +``` + +Content: + +``` +Hello Incubator PMC, + +The Apache OpenDAL community has voted and approved the release of Apache +OpenDAL(incubating) ${release_version}. We now kindly request the IPMC members +review and vote for this release. + +OpenDAL is a data access layer that allows users to easily and efficiently +retrieve data from various storage services in a unified way. + +OpenDAL community vote thread: + +${community_vote_thread_url} + +Vote result thread: + +${community_vote_result_thread_url} + +The release candidate: + +https://dist.apache.org/repos/dist/dev/incubator/opendal/${release_version}/ + +This release has been signed with a PGP available here: + +https://downloads.apache.org/incubator/opendal/KEYS + +Git branch for the release: + +https://github.com/apache/incubator-opendal/tree/release-${release_version} + +Please download, verify, and test. + +The VOTE will pass after got 3 binding approve. + +[ ] +1 approve +[ ] +0 no opinion +[ ] -1 disapprove with the reason + +To learn more about apache opendal, please see https://opendal.apache.org/ + +Checklist for reference: + +[ ] 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 + +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 + +Thanks + +${name} +``` + +After at least 72 hours with at least 3 +1 binding vote (from Incubator PMC member) and no veto, claim the vote result: + +Title: + +``` +[RESULT][VOTE] Release Apache OpenDAL(incubating) ${release_version} - Incubator Vote Round 1 +``` + +Content: + +``` +Hi Incubator PMC, + +The vote to release Apache OpenDAL(incubating) ${release_version} has passed with +4 +1 binding and 3 +1 non-binding votes, no +0 or -1 votes. + +Binding votes： + +- xxx +- yyy +- zzz + +Non-Binding votes: + +- aaa + +Vote thread: ${incubator_vote_thread_url} + +Thanks for reviewing and voting for our release candidate. + +We will proceed with publishing the approved artifacts and sending out the announcement soon. +``` + +## Official Release + +### 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-rc1` + +```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}" +``` + +### Send the announcement + +Send the release announcement to `dev@opendal.apache.org` and CC `announce@apache.org`. + +Title: + +``` +[ANNOUNCE] Release Apache OpenDAL(incubating) ${release_version} +``` + +Content: + +``` +Hi all, + +The Apache OpenDAL(incubating) community is pleased to announce +that Apache OpenDAL(incubating) ${release_version} has been released! + +OpenDAL is a data access layer that allows users to easily and efficiently +retrieve data from various storage services in a unified way. + +The notable changes since ${release_version} include: +1. xxxxx +2. yyyyyy +3. zzzzzz + +Please refer to the change log for the complete list of changes: +https://github.com/apache/incubator-opendal/releases/tag/v${release_version} + +Apache OpenDAL website: https://opendal.apache.org/ + +Download Links: https://opendal.apache.org/download + +OpenDAL Resources: +- Issue: https://github.com/apache/incubator-opendal/issues +- Mailing list: dev@opendal.apache.org + +Thanks +On behalf of Apache OpenDAL community +``` diff --git a/website/docusaurus.config.js b/website/docusaurus.config.js index 4bcb79796972..9f1935613421 100644 --- a/website/docusaurus.config.js +++ b/website/docusaurus.config.js @@ -101,6 +101,10 @@ const config = { label: 'General', to: '/docs/overview' }, + { + label: 'Contributing', + to: '/docs/category/contributing' + }, { label: 'Services', to: '/docs/category/services'