damccorm commented on code in PR #28287: URL: https://github.com/apache/beam/pull/28287#discussion_r1316014075
########## website/www/site/content/en/contribute/release-guide.md: ########## @@ -70,34 +71,86 @@ That said, if you are a committer interested in serving the community in this wa ### Checklist to proceed to the next step 1. Community agrees to release -1. Community selects a Release Manager +1. Community selects a committer as Release Manager ********** -## 2. Prepare for the release +## 2. Prepare for the release (~1 week before branch cut) 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. +This will set up your security keys for signing the release and access to various release repositories. To prepare for each release, you should audit the project status in the GitHub issue tracker, and do necessary bookkeeping. -Finally, you should create a release branch from which individual release candidates will be built. +Finally, create a release branch from which individual release candidates will be built. __NOTE__: If you are using [GitHub two-factor authentication](https://help.github.com/articles/securing-your-account-with-two-factor-authentication-2fa/) and haven't configure HTTPS access, please follow [the guide](https://help.github.com/articles/creating-a-personal-access-token-for-the-command-line/) to configure command line access. +### Create a new milestone in GitHub for the next release + +When contributors resolve an issue in GitHub, they are tagging it with a release that will contain their changes. +With the release currently underway, new issues should be resolved against a subsequent future release. +Therefore, you should create a release item for this subsequent release, as follows: + +1. In GitHub, navigate to [`Issues > Milestones > New Milestone`](https://github.com/apache/beam/milestones). +1. Add a new release. Choose the next minor version number after the version currently underway, select the next release due date (generally 6 weeks from today’s date) as the `Start Date`, and choose `Create Milestone`. +1. At the end of the release, go to the same page and mark the recently released version as closed. ### Accounts Please have these credentials ready at hand, you will likely need to enter them multiple times: -* GPG pass phrase (see the next section); * Apache ID and Password; -* GitHub ID and Password. -* DockerHub ID and Password. (You should be a member of maintainer team; email at dev@ if you are not.) -* Account to access to apache-beam-testing Google Cloud Platform project. The account must have permissions to start Cloud Build triggers. Required for Playground environment update. (E-mail to [email protected] to request access) +* GitHub ID, Password, and Personal Access Token. +* PyPi account and apitoken +* DockerHub ID and Password and beam mainainter access Review Comment: ```suggestion * DockerHub ID and Password with beam maintainer access ``` ########## website/www/site/content/en/contribute/release-guide.md: ########## @@ -70,34 +71,86 @@ That said, if you are a committer interested in serving the community in this wa ### Checklist to proceed to the next step 1. Community agrees to release -1. Community selects a Release Manager +1. Community selects a committer as Release Manager ********** -## 2. Prepare for the release +## 2. Prepare for the release (~1 week before branch cut) 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. +This will set up your security keys for signing the release and access to various release repositories. To prepare for each release, you should audit the project status in the GitHub issue tracker, and do necessary bookkeeping. -Finally, you should create a release branch from which individual release candidates will be built. +Finally, create a release branch from which individual release candidates will be built. __NOTE__: If you are using [GitHub two-factor authentication](https://help.github.com/articles/securing-your-account-with-two-factor-authentication-2fa/) and haven't configure HTTPS access, please follow [the guide](https://help.github.com/articles/creating-a-personal-access-token-for-the-command-line/) to configure command line access. +### Create a new milestone in GitHub for the next release + +When contributors resolve an issue in GitHub, they are tagging it with a release that will contain their changes. +With the release currently underway, new issues should be resolved against a subsequent future release. +Therefore, you should create a release item for this subsequent release, as follows: + +1. In GitHub, navigate to [`Issues > Milestones > New Milestone`](https://github.com/apache/beam/milestones). +1. Add a new release. Choose the next minor version number after the version currently underway, select the next release due date (generally 6 weeks from today’s date) as the `Start Date`, and choose `Create Milestone`. +1. At the end of the release, go to the same page and mark the recently released version as closed. ### Accounts Please have these credentials ready at hand, you will likely need to enter them multiple times: -* GPG pass phrase (see the next section); * Apache ID and Password; -* GitHub ID and Password. -* DockerHub ID and Password. (You should be a member of maintainer team; email at dev@ if you are not.) -* Account to access to apache-beam-testing Google Cloud Platform project. The account must have permissions to start Cloud Build triggers. Required for Playground environment update. (E-mail to [email protected] to request access) +* GitHub ID, Password, and Personal Access Token. +* PyPi account and apitoken +* DockerHub ID and Password and beam mainainter access +* GPG pass phrase & 16-digit key ID +* Access to Beam's Apache Nexus repository +* Account to access to apache-beam-testing Google Cloud Platform project. The account must have permissions to start Cloud Build triggers. Required for Playground environment update. (E-mail at dev@ mailing list to request access) + +If you don't have a given credential, follow the 'one-time' instructions below. + +********** ### One-time setup instructions +#### Apache ID and Password + +This is your Apache committer user name and password. You selected these when you became an Apache Beam Committer. + +#### Github ID, Password, and Personal Access Token + +For some scripts, you need a Personal Access Token with `repo` and `workflow` permissions. +They can be generated from this page: https://github.com/settings/tokens. +See https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens for details. + +#### Register to PyPI + +Release manager needs to have an account with PyPI. +If you need one, [register at PyPI](https://pypi.python.org/account/register/). +You also need to be a maintainer (or an owner) of the [apache-beam](https://pypi.python.org/pypi/apache-beam) package in order to push a new release. +Ask on the mailing list for assistance. + +Generate a [PyPI APIToken](https://pypi.org/help/#apitoken) for use during the release. + +#### Login to DockerHub +If you are a member of the [`beam` DockerHub team](https://hub.docker.com/orgs/apache/teams/beam), run following command manually. Review Comment: ```suggestion If you are a member of the [`beam` DockerHub team](https://hub.docker.com/orgs/apache/teams/beam), run the following command manually. ``` ########## website/www/site/content/en/contribute/release-guide.md: ########## @@ -629,7 +644,7 @@ A committer can manually trigger the [beam_PostCommit_Website_Publish](https://c **PR 1: apache/beam-site** This pull request is against the `apache/beam-site` repo, on the `release-docs` branch ([example](https://github.com/apache/beam-site/pull/603)). -It is created by `build_release_candidate.sh` (see above). +It is created by the `build_release_candidate.` workflow (see above). Review Comment: ```suggestion It is created by the `build_release_candidate` workflow (see above). ``` ########## website/www/site/content/en/contribute/release-guide.md: ########## @@ -386,55 +447,18 @@ For each of the failing tests create a GitHub Issue with the following propertie #### Inform the mailing list -The [email protected] mailing list should be informed about the release branch being cut. +The dev@ mailing list should be informed about the release branch being cut. Alongside with this note, a list of pending issues and to-be-triaged issues should be included. Afterwards, this list can be refined and updated by the release manager and the Beam community. -********** - - -## 7. Triage release-blocking issues in GitHub - -There could be outstanding release-blocking issues, which should be triaged before proceeding to build a release candidate. -We track them by assigning the blocked release to the issue's milestone before the issue is resolved. - - -The release manager should triage what does and does not block a release. -The list of release-blocking issues is available at the [milestone status page](https://github.com/apache/beam/milestones). -Triage each unresolved issue with one of the following resolutions: - -* An issue should not block the release if the problem exists in the current released version or is a bug in new functionality that does not exist in the current released version. -* An issue should be a blocker if the problem is a regression between the currently released version and the release in progress and has no easy workaround. - -For all GitHub issues: - -* If the issue has been resolved and the GitHub issue was not updated, resolve it accordingly. - -For issues with type "Bug" or labeled "flaky": - -* If the issue is a known continuously failing test, it is not acceptable to defer this until the next release. - Please work with the Beam community to resolve the issue. -* If the issue is a known flaky test, make an attempt to delegate a fix. - However, if the issue may take too long to fix (to the discretion of the release manager): - * Delegate manual testing of the flaky issue to ensure no release blocking issues. - * Update the milestone to the version of the next release. - Please consider discussing this with stakeholders and the dev@ mailing list, as appropriate. - -For all other GitHub issues: - -* If the issue has not been resolved and it is acceptable to defer this until the next release, update the milestone to the new version you just created. - Please consider discussing this with stakeholders and the dev@ mailing list, as appropriate. -* If the issue has not been resolved and it is not acceptable to release until it is fixed, the release cannot proceed. - Instead, work with the Beam community to resolve the issue. - -If there is a bug found in the RC creation process/tools, those issues should be considered high priority and fixed in 7 days. - ### Review cherry-picks +The release manager is empowered to triage issues, and accept or regject cherry-picks to the release branch. Review Comment: ```suggestion The release manager is empowered to triage issues, and accept or reject cherry-picks to the release branch. ``` ########## website/www/site/content/en/contribute/release-guide.md: ########## @@ -386,55 +447,18 @@ For each of the failing tests create a GitHub Issue with the following propertie #### Inform the mailing list -The [email protected] mailing list should be informed about the release branch being cut. +The dev@ mailing list should be informed about the release branch being cut. Alongside with this note, a list of pending issues and to-be-triaged issues should be included. Afterwards, this list can be refined and updated by the release manager and the Beam community. -********** - - -## 7. Triage release-blocking issues in GitHub - -There could be outstanding release-blocking issues, which should be triaged before proceeding to build a release candidate. -We track them by assigning the blocked release to the issue's milestone before the issue is resolved. - - -The release manager should triage what does and does not block a release. -The list of release-blocking issues is available at the [milestone status page](https://github.com/apache/beam/milestones). -Triage each unresolved issue with one of the following resolutions: - -* An issue should not block the release if the problem exists in the current released version or is a bug in new functionality that does not exist in the current released version. -* An issue should be a blocker if the problem is a regression between the currently released version and the release in progress and has no easy workaround. - -For all GitHub issues: - -* If the issue has been resolved and the GitHub issue was not updated, resolve it accordingly. - -For issues with type "Bug" or labeled "flaky": - -* If the issue is a known continuously failing test, it is not acceptable to defer this until the next release. - Please work with the Beam community to resolve the issue. -* If the issue is a known flaky test, make an attempt to delegate a fix. - However, if the issue may take too long to fix (to the discretion of the release manager): - * Delegate manual testing of the flaky issue to ensure no release blocking issues. - * Update the milestone to the version of the next release. - Please consider discussing this with stakeholders and the dev@ mailing list, as appropriate. - -For all other GitHub issues: - -* If the issue has not been resolved and it is acceptable to defer this until the next release, update the milestone to the new version you just created. - Please consider discussing this with stakeholders and the dev@ mailing list, as appropriate. -* If the issue has not been resolved and it is not acceptable to release until it is fixed, the release cannot proceed. - Instead, work with the Beam community to resolve the issue. - -If there is a bug found in the RC creation process/tools, those issues should be considered high priority and fixed in 7 days. - ### Review cherry-picks +The release manager is empowered to triage issues, and accept or regject cherry-picks to the release branch. +Cherry picks are necessary if there are outstanding issues at time of the release branche cut, or issues were found in verification. Review Comment: ```suggestion Cherry picks are necessary if there are outstanding issues at time of the release branch cut, or issues were found in verification. ``` ########## website/www/site/content/en/contribute/release-guide.md: ########## @@ -167,101 +228,103 @@ Configure access to the [Apache Nexus repository](https://repository.apache.org/ </servers> </settings> -#### Submit your GPG public key into Ubuntu OpenPGP Key Server -In order to make yourself have right permission to stage java artifacts in Apache Nexus staging repository, -please submit your GPG public key into the [Ubuntu OpenPGP Key Server](https://keyserver.ubuntu.com/). +********** -You will need to use an ascii-armored version of your key. -This can be obtained by running `gpg --export --armor` and copying the whole block -(including `-----<START/END> PGP PUBLIC KEY BLOCK-----`). +### Handle Per Release tasks -#### Website development setup +#### Update base image dependencies for Python container images -Updating the Beam website requires submitting PRs to both the main `apache/beam` repo and the `apache/beam-site` repo. -The first contains reference manuals generated from SDK code, while the second updates the current release version number. +Tracked in Github issue https://github.com/apache/beam/issues/27944 -You should already have setup a local clone of `apache/beam`. -Setting up a clone of `apache/beam-site` is similar: +See instructions at: https://s.apache.org/beam-python-requirements-generate - $ git clone -b release-docs https://github.com/apache/beam-site.git - $ cd beam-site - $ git remote add <GitHub_user> [email protected]:<GitHub_user>/beam-site.git - $ git fetch --all - $ git checkout -b <my-branch> origin/release-docs +Ideally, do the update at least a week before the release cut, so that any issues +related to the update have time to surface. -Further instructions on website development on `apache/beam` is [here](https://github.com/apache/beam/blob/master/website). -Background information about how the website is updated can be found in [Beam-Site Automation Reliability](https://s.apache.org/beam-site-automation). +#### Update Go version used for container builds -#### Register to PyPI +Tracked in Github issue https://github.com/apache/beam/issues/27897 -Release manager needs to have an account with PyPI. -If you need one, [register at PyPI](https://pypi.python.org/account/register/). -You also need to be a maintainer (or an owner) of the [apache-beam](https://pypi.python.org/pypi/apache-beam) package in order to push a new release. -Ask on the mailing list for assistance. +Ideally, do the update at least a week before the release cut, so that any issues +related to the update have time to surface. -#### Login to DockerHub -If you are a member of the [`beam` DockerHub team](https://hub.docker.com/orgs/apache/teams/beam), run following command manually. -It will ask you to input your DockerHub ID and password if authorization info cannot be found from ~/.docker/config.json file. +#### Update the Java BOM -``` -docker login docker.io -``` +TODO(lostluck): Find instructions or associated issue/PRs (go/beam-issue/#####) Review Comment: We should probably at least have something here before merging -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
