This is an automated email from the ASF dual-hosted git repository. asorokoumov pushed a commit to branch release-process in repository https://gitbox.apache.org/repos/asf/otava.git
commit 4583a139ca3107a2363c34f52fbbc761a3e1f770 Author: Alex Sorokoumov <[email protected]> AuthorDate: Sun Dec 14 21:58:12 2025 -0800 WIP: Creating Apache Otava Release --- docs/RELEASE.md | 133 +++++++++++++++++++++++++++++++++++++------------------- 1 file changed, 88 insertions(+), 45 deletions(-) diff --git a/docs/RELEASE.md b/docs/RELEASE.md index ad34714..19bfaaa 100644 --- a/docs/RELEASE.md +++ b/docs/RELEASE.md @@ -6,7 +6,7 @@ ## Introduction The Otava community treats releases with great importance. They are a public face of the project and most users interact with the project only through the releases. Releases are signed off by the entire Otava community in a public vote. -Each release is executed by a Release Manager, who is selected/proposed by the Otava PMC members. This document describes the process that the Release Manager follows to perform a release. Any changes to this process should be discussed and adopted on the [[email protected]]([email protected]) mailing list. +Each release is executed by a Release Manager, who is selected/proposed by the Otava PMC members. This document describes the process that the Release Manager follows to perform a release. Any changes to this process should be discussed and adopted on the [[email protected]](mailto:[email protected]) mailing list. Please remember that publishing software has legal consequences. This guide complements the foundation-wide [Product Release Policy](https://www.apache.org/dev/release.html) and [Release Distribution Policy](https://www.apache.org/dev/release-distribution). @@ -16,7 +16,7 @@ Please remember that publishing software has legal consequences. This guide comp Apache Otava release consists of: * ASF source zips archived on [dist.apache.org](dist.apache.org). -* PyPi wheels published to [pypi.org](https://pypi.org/project/apache-otava/). +* PyPI wheels published to [pypi.org](https://pypi.org/project/apache-otava/). * Docker images published to [Dockerhub](https://hub.docker.com/r/apache/otava). * Release tag on [GitHub](https://github.com/apache/otava/releases). @@ -42,11 +42,13 @@ In general, the community prefers to have a rotating set of 3-5 Release Managers 1. Community agrees to release 2. Community selects a Release Manager -## One-time configuration +## Prepare for the release Before your first release, you should perform one-time configuration steps. This will set up your security keys for signing the release and access to various release repositories. -### GPG Key +### One-time configuration + +#### GPG Key You need to have a GPG key to sign the release artifacts. Please be aware of the ASF-wide [release signing guidelines](https://www.apache.org/dev/release-signing.html). If you don’t have a GPG key associated with your Apache account, please create one according to the guidelines. Determine your Apache GPG Key and Key ID, as follows: @@ -65,7 +67,7 @@ sub 2048R/BA4D50BE 2016-02-23 ``` Here, the key ID is the 8-digit hex string in the pub line: 845E6689. -Now, add your Apache GPG key to the Otava’s KEYS file in the [release](https://dist.apache.org/repos/dist/release/incubator/otava/KEYS) repository at [dist.apache.org](https://dist.apache.org/repos/dist/). Follow the instructions listed at the top of these files. (Note: Only PMC members have write access to the release repository. If you end up getting 403 errors ask on the mailing list for assistance.) PMC member can refer following scripts to add your Apache GPG key to the KEYS in the [...] +Now, add your Apache GPG key to the Otava's KEYS file in the [release](https://dist.apache.org/repos/dist/release/incubator/otava/KEYS) repository at [dist.apache.org](https://dist.apache.org/repos/dist/). Follow the instructions listed at the top of these files. (Note: Only PMC members have write access to the release repository. If you end up getting 403 errors ask on the mailing list for assistance.) PMC members can refer to the following scripts to add your Apache GPG key to the KEYS [...] ```bash svn co https://dist.apache.org/repos/dist/release/incubator/otava otava-dist-release-repo @@ -80,7 +82,7 @@ Configure git to use this key when signing code by giving it your key ID, as fol git config --global user.signingkey 845E6689 ``` -You may drop the`--global` option if you’d prefer to use this key for the current repository only. +You may drop the `--global` option if you’d prefer to use this key for the current repository only. You may wish to start `gpg-agent` to unlock your GPG key only once using your passphrase. Otherwise, you may need to enter this passphrase hundreds of times. The setup for gpg-agent varies based on operating system, but may be something like this: ``` @@ -89,9 +91,9 @@ export GPG_TTY=$(tty) export GPG_AGENT_INFO ``` -### PyPI +#### PyPI -Create both [PyPI](https://pypi.org/) and [TestPypI](https://test.pypi.org) accounts. Then, ask PMC members to get added to [Otava](https://pypi.org/org/apache-otava/) organization on both platforms. +Create both [PyPI](https://pypi.org/) and [TestPyPI](https://test.pypi.org) accounts. Then, ask PMC members to get added to [Otava](https://pypi.org/org/apache-otava/) organization on both platforms. Install `twine` if you don't have it already: @@ -99,7 +101,7 @@ Install `twine` if you don't have it already: $ pip install twine ``` -### Dockerhub +#### Dockerhub Make sure you have a Dockerhub account. Create ASF INFRA issue to add your Dockerhub account to `apache` organization, `otava` team. @@ -115,6 +117,8 @@ Create ASF INFRA issue to add your Dockerhub account to `apache` organization, ` ## Build a release candidate +The core of the release process is the build-vote-fix cycle. Each cycle produces one release candidate. The Release Manager repeats this cycle until the community approves one release candidate, which is then finalized. + ### Set up ENV variables for convenience ```bash @@ -196,17 +200,21 @@ sha512sum --check apache_otava-$RELEASE_VERSION-py3-none-any.whl.sha512 ### Publish Release Candidate ```bash -cp -r release ../otava otava-dist-release-repo/$RELEASE_VERSION-incubating-$RELEASE_CANDIDATE -cd ../otava otava-dist-release-repo +cp -r release ../otava-dist-release-repo/$RELEASE_VERSION-incubating-$RELEASE_CANDIDATE +cd ../otava-dist-release-repo svn add $RELEASE_VERSION-incubating-$RELEASE_CANDIDATE/ svn ci -m "[otava] Add $RELEASE_VERSION-incubating-$RELEASE_CANDIDATE" ``` -### Start a vote on a project mailing list +## Vote on the release candidate + +Once you have built and individually reviewed the release candidate, please share it for the community-wide review. Please review foundation-wide [voting guidelines](https://www.apache.org/foundation/voting.html) for more information. -Mailing list: [[email protected]]([email protected]) -Subject: `[VOTE] Release Apache Otava (incucating) $RELEASE_VERSION-$RELEASE_CANDIDATE` -Here is a sample text: +### Start a vote on the project mailing list + +Mailing list: [[email protected]](mailto:[email protected]) +Subject: `[VOTE] Release Apache Otava (incubating) $RELEASE_VERSION-$RELEASE_CANDIDATE` +Here is a text template, please adjust as you see fit: ``` Hello everyone, @@ -216,7 +224,7 @@ Please review and vote for the releasing Apache Otava (incubating) $RELEASE_VERS Changelog for this release candidate <>. The official Apache source release has been deployed to https://dist.apache.org/repos/dist/dev/incubator/otava/$RELEASE_VERSION-incubating-$RELEASE_CANDIDATE/. GH tag for release https://github.com/apache/otava/releases/tag/$RELEASE_VERSION-incubating-$RELEASE_CANDIDATE. -The release has been signed with a key <your-signature> available here https://downloads.apache.org/incubator/otava/KEYS. +The release has been signed with a key <your-signature> available here https://downloads.apache.org/incubator/otava/KEYS. Please download, verify, and test. @@ -239,47 +247,51 @@ Checklist for reference: [ ] Can run examples using all supported Python versions. ``` -### In case project or Incubator vote fails... +*If there are any issues found in the release candidate, reply on the vote thread to cancel the vote.* There’s no need to wait 72 hours. Proceed to the Fix Issues step below and address the problem. However, some issues don’t require cancellation. For example, if an issue is found in the website pull request, just correct it on the spot and the vote can continue as-is. + +For cancelling a release, the release manager needs to send an email to the release candidate thread, stating that the release candidate is officially cancelled. Next, all artifacts created specifically for the RC in the previous steps need to be removed: +- Delete the staging repository in Nexus +- Remove the source / binary RC files from dist.apache.org +- Delete the source code tag in git -1.Create a result thread on the project dev mailing list - [email protected]. +*If there are no issues*, reply on the vote thread to close the voting. Then, tally the votes in a separate email. Here’s an email template; please adjust as you see fit: +Mailing list: [email protected] Subject: `[RESULT][VOTE] Release Apache Otava (incubating) $RELEASE_VERSION-$RELEASE_CANDIDATE` -Sample text: +Text: ``` Hey everyone, -The vote to release Apache Otava $RELEASE_VERSION-incubating-$RELEASE_CANDIDAT has failed with X -1 binding votes. - +The vote to release Apache Otava (incubating) $RELEASE_VERSION-$RELEASE_CANDIDATE has passed with X +1 binding votes, Y +1 non-binding votes and 0 -1 votes. Vote thread: <link-to-vote-thread-archive>. - ``` -2. Fix the issue. -3. Increment `RELEASE_CANDIDATE` env variable. -4. Repeat the steps above. - -### After project vote succeeds +### In case project or Incubator vote fails... -#### Create a result thread on the mailing list. +1. Create a result thread on the corresponding mailing list. -Mailing list: [email protected]. Subject: `[RESULT][VOTE] Release Apache Otava (incubating) $RELEASE_VERSION-$RELEASE_CANDIDATE` Sample text: ``` Hey everyone, -The vote to release Apache Otava (incubating) $RELEASE_VERSION-$RELEASE_CANDIDATE has passed with X +1 binding votes, Y +1 non-binding votes and 0 -1 votes. +The vote to release Apache Otava (incubating) $RELEASE_VERSION-$RELEASE_CANDIDATE has failed with X -1 binding votes. + Vote thread: <link-to-vote-thread-archive>. ``` -#### Create Incubator vote thread +2. Fix the issue. +3. Increment `RELEASE_CANDIDATE` env variable. +4. Repeat the steps above. -Mailing list: [[email protected]]([email protected]) -Subject: `[VOTE] Release Apache Otava (incucating) $RELEASE_VERSION-$RELEASE_CANDIDATE` +### Start a vote on the Incubator mailing list + +Mailing list: [[email protected]](mailto:[email protected]) +Subject: `[VOTE] Release Apache Otava (incubating) $RELEASE_VERSION-$RELEASE_CANDIDATE` +Text template, please adjust as you see fit: -Sample text: ``` Hello, @@ -311,8 +323,8 @@ To learn more about Apache Otava, please see https://otava.apache.org. Proceed only after Incubator vote succeeds. If the vote failed, see section `In case project or Incubator vote fails` above. -Mailing list: [[email protected]]([email protected]) -Subject: `[RESULT][VOTE] Release Apache Otava (incucating) $RELEASE_VERSION-$RELEASE_CANDIDATE` +Mailing list: [[email protected]](mailto:[email protected]) +Subject: `[RESULT][VOTE] Release Apache Otava (incubating) $RELEASE_VERSION-$RELEASE_CANDIDATE` Sample text: ``` @@ -321,7 +333,7 @@ Hello everyone, The vote to release Apache Otava (incubating) $RELEASE_VERSION-$RELEASE_CANDIDATE has passed with X +1 binding and Y +1 non-binding votes, no -1 votes. -Binding +1 votes： +Binding +1 votes: - ... - ... @@ -334,6 +346,10 @@ We will proceed with publishing the approved artifacts and sending out the announcement soon. ``` +## Finalize the release + +Once the release candidate has been reviewed and approved by the project and Incubator community, the release should be finalized. This involves the final deployment of the release candidate to the release repositories, merging of the website changes, etc. + ### Publish Source Release In `otava-dist-release-repo`: @@ -341,7 +357,7 @@ In `otava-dist-release-repo`: ```bash cp -r $RELEASE_VERSION-incubating-$RELEASE_CANDIDATE $RELEASE_VERSION-incubating svn add $RELEASE_VERSION-incubating -svn ci -m "[otava] Add 0.7.0-incubating" +svn ci -m "[otava] Add $RELEASE_VERSION-incubating" ``` ### Publish release tag on Github @@ -352,7 +368,9 @@ git tag -a $RELEASE_VERSION-incubating -m "$RELEASE_VERSION-incubating" git push origin $RELEASE_VERSION-incubating ``` -### Publish PyPi artifacts +Go to Github releases page and create a new release for the tag `$RELEASE_VERSION-incubating`. + +### Publish PyPI artifacts In svn release directory: @@ -363,7 +381,7 @@ cd $RELEASE_VERSION-incubating # Publish to Test PyPI twine upload --verbose --repository testpypi apache_otava-$RELEASE_VERSION-py3-none-any.whl apache_otava-$RELEASE_VERSION.tar.gz # verify that test PyPI page looks good, then publish to real PyPi -twine upload --verbose apache_otava-0.7.0-py3-none-any.whl apache_otava-0.7.0.tar.gz +twine upload --verbose apache_otava-$RELEASE_VERSION-py3-none-any.whl apache_otava-$RELEASE_VERSION.tar.gz ``` ### Publish Docker Image @@ -386,15 +404,28 @@ Push the image to Dockerhub: docker push apache/otava:$RELEASE_VERSION-incubating ``` -### Write announcement email to project incubator mailing lists +### Remove old release candidates from dist.apache.org + +In `otava-dist-release-repo`: + +```bash +svn rm $RELEASE_VERSION-incubating-$RELEASE_CANDIDATE +svn ci -m "[otava] Remove $RELEASE_VERSION-incubating-$RELEASE_CANDIDATE" +``` + + +## Promote the release + +Once the release has been finalized, the last step of the process is to promote the release within the project and beyond. Please wait for 1 hour after finalizing the release in accordance with the [ASF release policy](https://www.apache.org/legal/release-policy.html#release-announcements). + +### Send announcement email to project and incubator mailing lists Mailing lists: -- [[email protected]]([email protected]) -- [[email protected]]([email protected]) +- [[email protected]](mailto:[email protected]) +- [[email protected]](mailto:[email protected]) Subject: `[ANNOUNCE] Apache Otava (incubating) version $RELEASE_VERSION released` - -Sample text: +Text template: ``` Apache Otava (incubating) version $RELEASE_VERSION has been released. @@ -409,6 +440,8 @@ A typical use-case of Otava is as follows: 5. Otava is capable of finding even small, but persistent shifts in metric values, despite noise in data. It adapts automatically to the level of noise in data and tries to notify only about persistent, statistically significant changes, be it in the system under test or in the environment. Highlights of $RELEASE_VERSION release are: +- ... +- ... $RELEASE_VERSION is available as: - Source release https://dist.apache.org/repos/dist/dev/incubator/otava/$RELEASE_VERSION-incubating/ @@ -424,3 +457,13 @@ Otava resources: <Your name> On behalf of Apache Otava (incubating) Team ``` + +### Social Media + +Tweet, post on Facebook, LinkedIn, and other platforms. Ask other contributors to do the same. + +## Improve the process + +It is important that we improve the release processes over time. Once you’ve finished the release, please take a step back and look what areas of this process and be improved. Perhaps some part of the process can be simplified. Perhaps parts of this guide can be clarified. + +If we have specific ideas, please start a discussion on the dev@ mailing list and/or propose a pull request to update this guide.
