THIS IS A TEST INSTANCE. ALL YOUR CHANGES WILL BE LOST!!!!
OpenWhisk, an open-source serverless platform, has launched its release journey under Apache as an incubator project. It has published 12 modules for as the first-time release. This instruction is the guideline for release managers to walk through the correct process to release OpenWhisk module(s) under Apache. By following it, you can make sure that the artifacts to be released are well-compliant with Apache policies.
1. Determine the new version number of the OpenWhisk module
OpenWhisk adopts semantic versioning 2.0.0 to determine the version number, so each version complies with the format of MAJOR.MINOR.PATCH.
MAJOR version when you make incompatible API changes.
MINOR version when you add functionality in a backwards-compatible manner.
PATCH version when you make backwards-compatible bug fixes.
The first version number, OpenWhisk core module selected to release, is 0.9.0-incubating, in which 0 is MAJOR, 9 is MINOR, and 0-incubating is PATCH. For all OpenWhisk modules, both MAJOR and MINOR should be digits. PATCH contains a digit and the suffix “-incubating” to indicate that OpenWhisk is still an incubator project. After the graduation as an incubator project in Apache, we can remove the suffix for PATCH. On top of the basic rule, make sure the current version number increments the previous version number.
2. Generate artifacts for certain module(s)
OpenWhisk has a tool called openwhisk-release, available at https://github.com/apache/incubator-openwhisk-release, to generate the artifacts for all the modules. It provides both manual and automated modes. What we suggest is to take the automatic approach by kicking-off the Travis jobs to streamline the process.
The process of generating artifacts is the process to change the configuration file config.json and submit pull requests. Please refer to this instruction about how to edit the configuration file to pick up the commit hashes for the modules to be released: https://github.com/apache/incubator-openwhisk-release/blob/master/docs/pick_up_source_code.md#picking-up-source-code.
When the configuration file is ready, submit a PR for the repository openwhisk-release, and ask other reviewers to review it. When this PR is merged, please record the hash number for this commit in the master branch, because we will tag it later in order to move the artifacts from the staging SVN repository to the release SVN repository in Apache. This tagging process will be implemented after we get enough votes from both the OpenWhisk community and Apache IPMC.
The Travis jobs can be triggered by push and tag in openwhisk-release. Each push commit will generate the artifacts, sign them with the PGP keys, and upload them into the staging SVN repository, which is used to pick up the release candidates for further votes. After the modules receive enough votes to release, we create a tag for the commit, used to generate the artifacts, to move the artifacts into the release SVN repository.
After the PR is merged, please verify all the artifacts are available under the staging repository of Apache at https://dist.apache.org/repos/dist/dev/incubator/openwhisk/. If there is anything incorrect, it could be either a bug with the openwhisk-release tool, or the error in the configuration file. If you have no idea how to resolve it, log an issue at https://github.com/apache/incubator-openwhisk-release/issues.
3. Go through the voting process
Based on OpenWhisk’s incubator status in Apache, we need to go through the voting process twice: one in the OpenWhisk community and the other in the Apache IPMC. The same rule applies at both parties to pass the vote, as per https://www.apache.org/foundation/voting.html:
the vote email needs to be open for at least 72 hours;
at least 3 positive votes are received from the binding members, which means PPMC members in OpenWhisk community and IPMC members in Apache;
there are more positive than negative binding votes;
- once at least 72 hours have passed, the vote is tallied in a [VOTE][RESULT] message.
It is possible that the vote email is open longer than 72 hours to collect the sufficient votes. If we do not meet the requirement in either the OpenWhisk community or the Apache IPMC. We need to retrospect to the previous step to generate new artifacts and relaunch the voting process until the requirement is met to release the artifacts.
We have to launch the vote in OpenWhisk community first. When it passes, launch the vote in Apache IPMC. We cannot start in both parties in parallel, because Apache IPMC needs to take the vote and vote result in OpenWhisk community as reference.
First, let’s see how to walk through the vote process in OpenWhisk community. After the artifacts as release candidates have been uploaded to the staging repository, the release manager needs to send a vote email to the OpenWhisk community at dev@openwhisk.apache.org. How to prepare vote email for OpenWhisk community? A vote email for the OpenWhisk community should be comprehensive enough with detailed information regarding the release, including but not limited to:
a self-descriptive title starting with [VOTE],
some introductions and rules about this vote email,
introductions to the module(s) to be release,
hash value(s) of the commit(s) picked in the Github repository for the module
download links of the source code package, SHA512 checksum, signature, etc,
download link of the public PGP key,
vote options,
checklist of the verification as reference, etc.
Samples for this vote email can be found at: https://lists.apache.org/thread.html/3d4952420a38936cbc6caeddf1979270f77469928e6092df84299ca1@%3Cdev.openwhisk.apache.org%3E and https://lists.apache.org/thread.html/443cbd5eb5f2b84c3b34b92bd8585a36cd8c1ce52ef5453a7ad33282@%3Cdev.openwhisk.apache.org%3E.
If the artifacts are proposed for the first time, please include RC1 in both the title and the content of the email. 1 indicates the candidate number. Each time we fail to pass the vote and propose new changes to the artifacts for the current release, we should increment the candidate number by one.
If the vote fails to pass, the release manager should reply to the vote email, explaining the identified issues, and work actively to propose new artifacts and repeat the vote process. If the vote passes, the release manager should send an email replying to the vote email, as a recap to close the vote email thread, and send out another email to announce the result of the vote.
Samples of the vote result email can be found at: https://lists.apache.org/thread.html/a825791284657c9860e0f63ec68f08d085da818e93cc14a6756273dc@%3Cdev.openwhisk.apache.org%3E and https://lists.apache.org/thread.html/257f62b54b1fd14e7b6e2347d0263169821f55ac4f57355e44c84194@%3Cdev.openwhisk.apache.org%3E.
Then, we dig into the vote process in Apache IPMC. Make sure the vote email to be sent to the Apache email list at general@incubator.apache.org, including but not limited to:
a self-descriptive title starting with [VOTE],
some introductions and rules about this vote email,
links to the vote email and result of the vote email,
hash value(s) of the commit(s) picked in the Github repository for the module
download links of the source code package, SHA512 checksum, signature, etc,
download link of the public PGP key,
vote options, etc.
Samples for this vote email can be found at:
https://www.mail-archive.com/general@incubator.apache.org/msg64124.html and https://www.mail-archive.com/general@incubator.apache.org/msg64382.html.
The vote process in Apache IPMC is similar to the one in OpenWhisk community. Please make sure the RC number is consistent with the latest used in OpenWhisk community. For example, if we conduct two rounds of votes in OpenWhisk community, and the RC number has reached 2, we will directly use RC2 as the candidate number to vote in Apache IPMC.
The same rule applies to the vote result. If we do not meet the minimum requirement to pass, we need to go back to generate the artifacts with the demanded changes and launch the vote process again. If we fail here in Apache IPMC, we only need to repeat the vote process in Apache. There is no need to regress to vote one more time in OpenWhisk community, but add the updates and issues resolved in the content of the new vote email. If the vote passes, the release manager should send an email replying to the vote email, as a recap to close the vote email thread, and send out another email to announce the result of the vote.
Samples of the vote result email can be found at:
https://www.mail-archive.com/general@incubator.apache.org/msg64191.html and https://www.mail-archive.com/general@incubator.apache.org/msg64443.html.
Under the circumstances, that Apache IPMC members do not reply to the vote email in a timely fashion, here are some suggestions:
Reach out to our mentors of OpenWhisk in Apache to catch their attentions;
Reach out to some IPMC members, who voted OpenWhisk mail threads before, for their votes.
In general, do not be passive, when engaging in open source community. Use your network to reach out the right persons for the right results.
To better track the status of the vote email in Apache, you can access mail archive at https://mail-archives.apache.org/mod_mbox/incubator-general/. Once click on the “Browse” link for the month, you are able to see all the emails for that certain month.
4. Tag the commit hash for a version number
After receiving enough votes from both OpenWhisk community and Apache IPMC, we needs to tag the commit, generating the artifacts for modules with this version, in openwhisk-release to move the artifacts into release SVN repository.
The tag name for openwhisk-release is flexible, but we better name it in an explicit and semantic way, so that we can refer to it later. For example, if we want to release openwhisk main module 0.9.0-incubating, we can name the tag 0.9.0-incubating-main-module. This tag can be created and pushed upstream by git commands.
Also, we need to tag the commit, which was picked for the release, for each openwhisk repository to make sure it has version number as a valid tag for future access, and to generate the binaries or docker images based on the added tag.
How to name the tag may vary from module to module:
For OpenWhisk CLI and wskdeploy, the tag name is the same as the version number.
For runtime modules, the tag conforms to the format {language version}@{version number} in order to generate the docker image for a specific kind of the language. The runtime module may consist of different kinds for a certain programming language. For example, the runtime Node.js includes both 6 and 8. Since we used to release the version number 1.12.0-incubating for We should add the tag 6@1.12.0-incubating and the tag 8@1.12.0-incubating to the same commit hash.
For OpenWhisk catalog, apigateway and client go library, the tag name can be the same as the version number, even if we do not need to generate either binaries or docker images.
For OpenWhisk core module, so far the tag name remains the same as the version number, but it may be changed in future.
The release manager can use the git command: “git tag -a <tag_name> <hash>” to add the tag. A terminal will pop-up for you to add the commit message. After entering the message and save it, you can use git command: “git push upstream <tag_name>” to update the remote upstream repository. Watch closely the status of the Travis jobs kicked-off by the tag, since the they will generate the binaries or push the docker images into dockerhub.
5. Update the download page at the official website of OpenWhisk
Please make changes to the download page of the official OpenWhisk website. The repository you need to commit the changes is accessible at https://github.com/apache/incubator-openwhisk-website. You can contribute code to it, as you contribute code any other Github project. After you submit pull requests, ask reviewers to review them.
As we know the staging repository for OpenWhisk is located at https://dist.apache.org/repos/dist/dev/incubator/openwhisk/, and the release repository is located at https://dist.apache.org/repos/dist/release/incubator/openwhisk/. However, we do not directly use the link to the release repository to download the artifacts for official releases. Apache provides many mirroring systems, which are synchronizing the release repository from time to time. Normally it takes 24 hours to become eventually consistent. Please follow the pattern for OpenWhisk main module to compose your links for all OpenWhisk modules.
Take the OpenWhisk main module 0.9.0 for instance:
SHA512 checksum: https://www.apache.org/dist/incubator/openwhisk/apache-openwhisk-0.9.0-incubating/openwhisk-0.9.0-incubating-sources.tar.gz.sha512
Normally, you only need to change the version number and the names of the artifacts for new releases. When your PRs are merged, it takes a few minutes to update the official website of OpenWhisk.
6. Send the email of announcement for the release to Apache IPMC and OpenWhisk community
When the download links of the artifacts are available on the OpenWhisk website, it is time to send the announcement email for the release to the Apache IPMC general mail list. It is suggested to CC the same email to the OpenWhisk community. The email should include:
a self-descriptive title starting with [ANNOUNCE],
some introduction to the OpenWhisk modules to be released,
link to the download page of the official OpenWhisk website,
disclaimer, etc.
A sample of the announcement can be found at: https://www.mail-archive.com/general@incubator.apache.org/msg64226.html.