Hi All, Based on Davor's and JB's feedback I would like to start the discussion on our release procedure.
I suggest starting with a minimal process and add controls if and when needed, based on that I suggest the following minimal procedure, based on @Davor's Beam example below. Please note the following major differences: 1. The prepare to release section was minimized to managing versions in JIRA, we aim to automate the entire release process to have the release manager creating a *version branch* which will launch an automated *release build *that will sign the version etc. 2. As far as I can figure out, after voting on the incubator dev@ list we need to initiate a vote on the incubator general@ list, I have left an empty section for that, *can any of the mentors help fill that out*? 3. Additional question for our mentors, I have stated that the release requires the approval of 3 IPMC members, is that correct? 4. In JIRA, I have minimized the process and currently, no workflow to Triage release-blocking issues is proposed. I propose to differ this discussion to the first occasion when we will encounter such an issue. 5. I also propose to differ the discussion on the process for release of documentation and releases to online repos such as Maven/PyPi etc to the first occasion when we do release those. == Introduction == The Apache Amaterasu (Incubating) project periodically declares and publishes releases. A release is one or more packages of the project artifact(s) that are approved for general public distribution and use. They may come with various degrees of caveat regarding their perceived quality and potential for change, such as “alpha”, “beta”, “incubating”, “stable”, etc. The Amaterasu 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 Amaterasu community in a public vote. Each release is executed by a *Release Manager*, who is selected among the Amaterasu Committers <http://incubator.apache.org/projects/amaterasu.html>. 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 dev@ mailing list. Please remember that publishing software has legal consequences. This guide complements the foundation-wide Product Release Policy <http://www.apache.org/dev/release.html> and Release Distribution Policy <http://www.apache.org/dev/release-distribution>. == Overview == 1. Decide to release 2. Managing the new version in JIRA 3. Build a release candidate 4. Vote on the release candidate 5. If necessary, fix any issues and go back to step 3. 6. Finalize the release 7. Promote the release === Decide to release === Deciding to release and selecting a *Release Manager* is the first step of the release process. This is a consensus-based decision of the entire community. Anybody can propose a release on the dev@ mailing list, giving a solid argument and nominating a committer as the Release Manager (including themselves). There’s no formal process, no vote requirements, and no timing requirements. Any objections should be resolved by consensus before starting the release. Checklist to proceed to the next step: 1. Community agrees to release 2. Community selects a Release Manager === Managing the new version in JIRA === When contributors resolve an issue in JIRA, they are tagging it with a release that will contain their changes. With a planned release currently underway, new issues should be resolved against a subsequent future release. Therefore, Release manager should create a release item for this subsequent release, as follows: 1. In JIRA, navigate to *Amaterasu -> Administration -> versions * 2. Add a new release: choose the next minor version number compared to the one currently underway, select today’s date as the *Start Date* and click *Add*. With unplanned releases such as hot-fixes, a new version should be created representing that release. Issues that will be included in that release, should be updated to reflect that. === Review Release Notes in JIRA === JIRA automatically generates Release Notes based on the *Fix Version* field applied to issues. Release Notes are intended for Amaterasu Users (not Amaterasu committers/contributors). You should ensure that Release Notes are informative and useful. Open the release notes from the version status page <https://issues.apache.org/jira/projects/AMATERASU?selectedItem=com.atlassian.jira.jira-projects-plugin%3Arelease-page&status=unreleased> by choosing the release underway and clicking Release Notes. You should verify that the issues listed automatically by JIRA are appropriate to appear in the Release Notes. Specifically, issues should: - Be appropriately classified as *Bug*, *New Feature*, *Improvement*, etc. - Represent noteworthy user-facing changes, such as new functionality, backward-incompatible API changes, or performance improvements. - Have occurred since the previous release; an issue that was introduced and fixed between releases should not appear in the Release Notes. - Have an issue title that makes sense when read on its own. Adjust any of the above properties to improve clarity and presentation of the Release Notes. === Create an RC branch === Creating an RC release branch will initiate the release build process which, if successful will create the released version. Check out the version of the codebase from which you start the release. For a new minor or major release, this may be *HEAD* of the *master* branch. To build a hotfix/incremental release, instead of the *master* branch, use the release tag of the release being patched. (Please make sure your cloned repository is up-to-date before starting.) $ *git checkout **<master branch OR release tag>* Next, create a release branch with the version_ prefix followed by the version number and followed by the _rc suffix: $ *git checkout -b version_[version number]_rc* For example, the release branch for version 0.2.0-incubating should be created as follows" $ *git checkout -b version_0.2.0-incubating* Next, you will need to push the new branch to the remote as follows: $ *git push origin version_**[version number]* === 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 <http://www.apache.org/foundation/voting.html> for more information. Start the review-and-vote thread on the dev@ mailing list. Here’s an email template; please adjust as you see fit. -------------------------------------------------------------------------------------- From: Release Manager To: d...@amaterasu.incubator.apache.org Subject: [VOTE] Release 1.2.3, release candidate #3 Hi everyone, Please review and vote on the release candidate #3 for the version 1.2.3, as follows: [ ] +1, Approve the release [ ] -1, Do not approve the release (please provide specific comments) The complete staging area is available for your review, which includes: * JIRA release notes [1], * the official Apache source release to be deployed to dist.apache.org [2], which is signed with the key with fingerprint FFFFFFFF [3], * all artifacts to be deployed to the Maven Central Repository [4], * source code tag "v1.2.3-RC3" [5], * website pull request listing the release and publishing the API reference manual [6]. * Java artifacts were built with Maven MAVEN_VERSION and OpenJDK/Oracle JDK JDK_VERSION. * Python artifacts are deployed along with the source release to the dist.apache.org [2]. The vote will be open for at least 72 hours. It is adopted by majority approval, with at least 3 PMC affirmative votes. Thanks, Release Manager [1] link [2] link [3] https://dist.apache.org/repos/dist/release/incubator-amaterasu/KEYS [4] link [5] link [6] link -------------------------------------------------------------------------------------- === Mentors help needed Mentors, please elaborate on how the voting process should work for an incubating project. ====================================== 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. If there are no issues, replay 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. -------------------------------------------------------------------------------------- From: Release Manager To: d...@amaterasu.incubator.apache.org Subject: [RESULT] [VOTE] Release 1.2.3, release candidate #3 I'm happy to announce that we have unanimously approved this release. There are XXX approving votes, XXX of which are binding: * approver 1 * approver 2 * approver 3 * approver 4 There are no disapproving votes. Thanks everyone -------------------------------------------------------------------------------------- Checklist to proceed to the finalization step: 1. Community votes to release the proposed candidate, with at least three approving IPMC votes === Fix any issues === Any issues identified during the community review and vote should be fixed in this step. Code changes should be proposed as standard pull requests to the *master* branch and reviewed using the normal contributing process. For standard releases, this should be enough because during the release process, committers should avoid merging non-related PRs to master. and a new version branch should be created from the *master* branch. However, if non-related PRs ware merged or the release is from a release branch, relevant changes should be cherry-picked into the release branch. The cherry-pick commits should then be proposed as the pull requests against the release branch, again reviewed and merged using the normal contributing process. Once all issues have been resolved, you should go back and build a new release candidate containing these changes. Checklist to proceed to the finalization step: 1. Issues identified during vote have been resolved, with fixes committed to the release branch. === Finalize the release === Once the release candidate has been reviewed and approved by the community, the release should be finalized. This involves creating a release branch which is the same procedure as building an RC branch with the sole difference of not having the _rc suffix. === 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. ==== Apache Mailing Lists === Announce on the dev@ mailing list that the release has been finished. Announce on the release on the gene...@incubator.apache.org mailing list, listing major improvements and contributions. Announce the release on the annou...@apache.org mailing list. ==== Amaterasu Blog ==== Major or otherwise important releases should have a blog post. Write one if needed for this particular release. Minor releases that don’t introduce new major functionality don’t necessarily need to be blogged. ==== Social Media ==== Tweet, post on Facebook, LinkedIn, and other platforms. Ask other contributors to do the same. Checklist to proceed to the finalization step: 1. Release announced on the dev@ mailing list. 2. A blog post published, if applicable. 3. Release recorded in reporter.apache.org. 4. Release announced on social media. 5. Completion declared on the gene...@incubator.apache.org mailing list. -- Yaniv Rodenski
