THIS IS A TEST INSTANCE. ALL YOUR CHANGES WILL BE LOST!!!!
Metron Release Types
There are two types of Metron releases:
- Feature Release (FR) - this is a release that has a significant step forward in feature capability and is denoted by an upgrade of the second digit
- Maintenance Release (MR) - this is a set of patches and fixes that are issued following the FR and is denoted by an upgrade of the third digit
Release Naming Convention
Metron build naming convention is as follows: 0.[FR].[MR]. We keep the 0. notation to signify that the project is still under active development and we will hold a community vote to go to 1.x at a future time
Initiating a New Metron Release
Immediately upon the release of the previous Metron release create two branches: FR ++ and MR. Create the FR++ branch by incrementing the second digit like so 0.[FR++].0. Create the MR branch for the previous Metron release by incrementing the second digit of the previous release like so 0.[FR].[MR]. All patches to the previous Metron release will be checked in under the MR branch and where it makes sense also under the FR branch. All new features will be checked in under the FR branch.
Prerequisites
Before entering into this process you need to ensure you will be able to cryptographically sign the final result in such a way that others can validate the signature. This can be a confusing process. Here are links to several documents that should help.
http://www.apache.org/dev/openpgp.html
http://www.apache.org/dev/release-signing.html
http://httpd.apache.org/dev/verification.html
Creating a Feature Release
Step 1 - Initiate a discuss thread
A week before a new feature release initiate a discuss thread on the Metron dev board (dev@metron.incubator.apache.org) announcing the upcoming release and asking the community which still outstanding pull requests people want to include in the next build.
Step 2 - Verify JIRA
Go through the JIRA and verify that all pull requests that were merged for the upcoming build have JIRAs that are in a closed state and are appropriately labelled with the next build version.
Step 3 - Announce a code freeze
A day before the release date comment on the discuss thread and let people know that the release is ready. Go through the JIRAs for pull requests that came in during the last week and make sure they are labelled with the next build version.
Step 4 - Increment Metron version
File a JIRA to increment the Metron version to 0.[FR++].0. Either do it yourself or have a community member increment the build version for you. You can look at a pull request for a previous build to see how this is done
Step 5 - Increment build version
File a JIRA to increment the Metron version to 0.[FR++].0-RC(n), where RC(n) is the number of the release candidate. Sometimes mistakes occur (builds may get voted down) so it will take multiple RCs to get a build through the vote. The RC(n) will be removed after the successful vote.
Step 6 - Verify the build
Go through the build verification checklist to verify that everything works. These instructions can be found here: Verifying Builds
Step 7 - Verify licensing
Make sure the release compiles with the following Apache licensing guidelines: http://www.apache.org/foundation/license-faq.html
Step 8 - Generate the changes file
Go through the JIRA to generate the changes file, which contains a list of all JIRAs included in the upcoming release. An example of a changes file can be found here: https://dist.apache.org/repos/dist/dev/incubator/metron/0.3.0-RC1-incubating/CHANGES
Step 9 - Tag the RC release
Tag the release for the RC in case we need to roll back at some point. An example of a valid tag can be seen here:
git tag --annotate 0.[FR++].0-RC(n) --message "0.[FR++].0-RC(n)"git push origin --tags
Step 10 - Stage the release
The next thing to do is to sign and stage the release including the DISCLAIMER and LICENSE files. A properly signed and staged release can be found here:
https://dist.apache.org/repos/dist/dev/incubator/metron/0.3.0-RC1-incubating/
* Make sure you have your correct profile and keys uploaded to https://id.apache.org/ to properly sign the release and to get access to dist.apache.org
If the KEYS file doesn't exist, you should also stage it. It is best practice to have a single KEYS file in a well known place outside of the rc. This decoupling is supposed to make it more difficult for an artifact to be tampered with and another KEYS file provided. So put the keys at the top level of the ASF mirror area for the project such as at https://dist.apache.org/repos/dist/*release*/incubator/metron/
For more information on the KEYS file please refer to the Apache Keys File Guidance
Step 11 - Call for a community release vote
Next initiate a [VOTE] threat on the dev list to announce the build vote. The vote email template can be found here: Build Vote Template. Allow at least 72 hours for the community to vote on the release. When you get enough votes close the vote by replying [RESULT][VOTE] to the email thread with the tally of all the votes
Step 12 - Call for a incubator release vote
Upon successful completion of step 11, repeat, but now send the email to the incubator general boards. The email should be identical. Again, wait for at least 72 hours and then close the vote.
Step 13 - Stage the finished release
If the vote fails at any stage then incorporate feedback, create another RC, and repeat. If both votes pass then stage the resulting artifacts here: https://dist.apache.org/repos/dist/release/incubator/metron/
Step 14 - Announce build
Send a discuss thread to the Metron dev boards announcing the new Metron build
Creating a Maintenance Release
Creation of the Maintenance Release should follow exactly the same set of steps as creating the Feature Release as outlined above, but with two exception. First, the version incremented on the maintenance release should be the MR++ so that the release is named 0.[FR].[MR++]. Second, if a critical JIRA comes in that requires an immediate patch we may forego steps 2-5 and immediately cut the MR release. A critical JIRA is something that is either a security vulnerability or a functional show stopper .
Ensuring Consistency between Feature and Maintenance releases
Being able to maintain the previous release train, with only critical or important bug fixes and security fixes (generally not new features) for users who are averse to frequent large changes is very important for production use. They get stability, while the feature code proceeds as fast as the community wishes. It is important to assure that all commits to the maintenance release also get made in the feature branch (if relevant), to avoid the appearance of regressions in the maintenance branch. The formal process for assuring this is as follows:
- Every maintenance release JIRA should have a corresponding feature JIRA to make sure that the patch is applied consistently to both branches. The maintenance JIRA should be cloned and appropriate fix version for the feature release should be applied. If the fix is not relevant to the feature or maintenance branch then the submitter must explicitly state this. In general reviewers should refuse a patch PR unless both feature and maintenance JIRAs have been created.
- The release manager has a responsibility to review all commits to the maintenance line since last release, and make sure they were duplicated to the feature branch (unless not relevant, which must also be determined).