Note | ||
---|---|---|
| ||
We are updating this very excellent Apache JOSHUA/Apache Brooklyn release guide for use with Apache SENSSOFT |
Table of Contents | ||||||||
---|---|---|---|---|---|---|---|---|
|
...
Release Prerequisites
- Create a new release in JIRA. If you do not already have privileges enabling you to do so, ask the SENSSOFT FLAGON PMC.
- Push off all open issues to the next release; any critical or blocker issues should be resolved on mailing list. Discuss any issues that you are unsure of on the mailing list.
...
We have two directories here:
- https://dist.apache.org/repos/dist/release/useralejsincubator/flagon - This is where PMC approved releases go. DO NOT UPLOAD here until we have a vote passed on dev@senssoftdev@flagon... . Check out this foler folder and name it
apache-dist-release-senssoftflagon
. https://dist.apache.org/repos/dist/dev/incubator/useralejsflagon - this is where releases to be voted on go. Make the release artifact, post it here, and then post to the [VOTE] thread internally with the SensSoft flagon community and over the general @incubator community. Check out this folder and name it
apache-dist-dev-senssoftflagon
.
Example:
Code Block |
---|
svn co https://dist.apache.org/repos/dist/release/incubator/senssoftflagon apache-dist-release-senssoftflagon svn co https://dist.apache.org/repos/dist/dev/incubator/senssoftflagon apache-dist-dev-senssoftflagon |
Warning |
---|
When working with these folders, make sure you are working with the correct one. Otherwise, you may be publishing pre-release software to the global release mirror network. |
Software packages
The following software packages are required during the build. Make sure you have them installed.
- npm
- git
- zip and unzip
- md5sum and sha1sum
- gpg2
GPG Keys
The release manager must have a GPG key to be used to sign the release. See below to install gpg2
(with a gpg
alias). The steps here also assume you have the following set (not using whoami
if that’s not appropriate):
Code Block |
---|
ASF_USERNAME=`whoami` GPG_KEY=$ASF_USERNAME@apache.org SVN_USERNAME=$ASF_USERNAME |
Release Branch and Set Version
As mentioned above, in UserALE.js we use NPM as a release management tool. This includes preparing and RC for a community VOTE.
Make a clean checkout of the UserALE.js repository (ensuring that there are no local modifications):
Code Block $ git clone https://git-wip-us.apache.org/repos/asf/incubator-senssoft-useralejs.git
- Make sure all unit and integration tests are passing.
- All tests much pass... if they do not then they need to be fixed before further progress can be made.
- Update the CHANGELOG.md to reflect the current release, this may also be required for other essential files such as NOTICE, README etc. Ensure all of these files are accurate and up-to-date. It is also advised to include the JIRA release report in CHANGES.md. This makes it very easy for people to see the relevant changes for this release bundle.
If you have never made a SENSSOFT UserALE.js release, you are required to append your gpg key to the SENSSOFT KEYS file. This will then be used to sign all release artifacts. Much more about this can be found here http://apache.org/dev/release-signing.html
Note This is an extremely important part of the release procedure. It is essential to get it right and that all subsequent release managers' KEYS are associated with this file.
- If any changes based on the above have been made, then commit them to master branch. If you do not do this the next stage will not work.
Making the release artifacts
If you are happy with the proposed release artifacts then we can now move on to dropping the dryRun profile like so:
mvn release:clean release:prepare -DautoVersionSubmodules=true
This will allow you to view the actual release artifacts.
mvn release:perform
This does the following
pushes the maven artifacts to an apache staging repository at http://repository.apache.orgcreates a release tag in https://git-wip-us.apache.org/repos/asf?p=incubator-SENSSOFT.git;a=tags which you can view.finally, it commits the update of all module artifacts within the SENSSOFT pom.xml files and pushes these to Git master branch so we can continue with development e.g. bumps to the next development SNAPSHOT.
Once this has completed,
navigate to http://repository.apache.org and log in.click on Staging Repositories on the left hand side, you should see the SENSSOFT RC staging profile.Select the profile and close the staging profile. This makes the artifacts available for people to tests and VOTE upon.
Push the source release artifacts and signatures to dist.apache.org as described below.
Check out SENSSOFT release staging area. The artifacts we push to this area are the ones we make available on official
Apache mirrors. These are therefore the sources artifacts we link to from the SENSSOFT site. e.g.
In your local copy of SENSSOFT (master), navigate to $SENSSOFT/target directory and copy the src.zip and src-tar.gz artifacts along with relevant signatures to the above release staging directory.You should aim to include all relevant signatures along with these src artifacts. This would entailMD5, SHA and ASC signatures for each artifact. More information on this can be found here - http://apache.org/dev/release-signing.htmlcopy the CHANGES.md to this directory as wellfinally, svn add all of the above artifacts and commit them to the SENSSOFT dev release staging area
Next, progress to the creation of the VOTE thread as below...
Verify the release artifacts
TBD
Prepare the VOTE thread based on the artifacts
Send something like the following to the user@ and dev@SENSSOFT lists
Code Block | ||
---|---|---|
| ||
To: "Apache SENSSOFT Developers List" <dev@SENSSOFT.incubator.apache.org>, "Apache SENSSOFT User List" <user@SENSSOFT.incubator.apache.org>
Subject: VOTE Release Apache SENSSOFT (Incubating) X.Y
Hi Folks,
Please VOTE on the Apache SENSSOFT X.Y Release Candidate #Z.
We solved 44 issues: http://url/of/jira/release/report
Git source tag (c2d58dd1440b4e2c66c1f40a4b6d4169d79bb6d3): http://s.apache.org/Eyv
Staging repo: https://repository.apache.org/content/repositories/orgapacheSENSSOFT-1001
Source Release Artifacts: https://dist.apache.org/repos/dist/dev/SENSSOFT/X.Y/
PGP release keys (signed using 48BAEBF6): http://SENSSOFT.incubator.apache.org/dist/KEYS
Vote will be open for 72 hours.
Thank you to everyone that is able to VOTE as well as everyone that contributed to Apache SENSSOFT X.Y.
[ ] +1, let's get it released!!!
[ ] +/-0, fine, but consider to fix few issues before...
[ ] -1, nope, because... (and please explain why) |
The above email includes the following
- A link to the JIRA Release Report... this is critical for making it explicit what was addressed in this particular
development drive. - The SVN tag created by the mvn release plugin
- A link to the (closed) staging repository on repository.apache.org
- Link to the official release artifacts
- The KEYS file used containing developer signatures. This should be used to check signatures of release artifacts.
Double check the accuracy of this email and ship it to the masses!!!
N.B. DO NOT DELETE YOUR LOCAL COPY OF THE SENSSOFT RELEASE YOU"VE JUST PUSHED
IT IS ABSOLUTELY ESSENTIAL THAT YOU KEEP THE LOCAL RELEASE COPY !!!!
Preparing for new development
Send out the RESULT thread
After the 72 hours waiting time, it is down to the release manager to close the VOTE thread. This is usually
done by replying to the VOTE thread but changing the title to the following
Code Block | ||
---|---|---|
| ||
Subject: [RELEASE] WAS:VOTE Release Apache SENSSOFT X.Y
The RESULT thread should basically tally up the VOTE's something like the following would do nicely
Hi Everyone,
As the 72 hours period has come and gone I would like to bring this thread to a close.
The VOTE's have been counted and RESULT's are as follows
[7] +1, let's get it released!!!
Tom
Dick
Harry
Lewis John McGibbney *
[0] +/-0, fine, but consider to fix few issues before...
[0] -1, nope, because... (and please explain why)
*SENSSOFT PMC Binding VOTE
I'll progress with the remainder of the release procedure. |
If the release passes, progress to the next step, if not then head over to dev@SENSSOFT and discuss
how to revert the release. Assuming it passes however, progress to the next section.
Close the staging repos
Navigate to https://repository.apache.org and find the (closed) staging repos. Release this repository into
Apache Nexus. This will be pulled into Maven Central and in 12 or do hours the release artifacts should
be available at the following link - http://search.maven.org/#search%7Cga%7C1%7CSENSSOFT
Release the Source Artifacts
svn mkdir https://dist.apache.org/repos/dist/release/incubator/SENSSOFT/svn cp https://dist.apache.org/repos/dist/dev/gora/ to https://dist.apache.org/repos/dist/release/gora/X.Y/
Make sure that the up-to-date KEYS file exists in https://dist.apache.org/repos/dist/release/gora
Once all artifacts and signatures have been copied over, delete the dev area
The release artifacts will be copied over to apache.org/dist in due course and available for public download.
Update the Website to reflect the release
This can be done easily by editing the apache-senssoft page and committing the changes to master branch.
It is important that all links on downloads.html are accurate including the signatures links. Also the PGP
key reference to the signed artifacts should be updated to reflect the release managers KEY.
Announce the Release
Create a new GPG key giving your Apache email address, using gpg2 --gen-key
then gpg2 --armor --export $GPG_KEY > my-apache.key
and gpg2 --export-secret-key --armor $GPG_KEY > my-apache.private.key
in the right directory (~/.ssh
is a good one)
Look up your key fingerprint with gpg2 --fingerprint $GPG_KEY
- it’s the long sequence of hex numbers separated by spaces. Log in to https://id.apache.org/ then copy-and-paste the fingerprint into “OpenPGP Public Key Primary Fingerprint”. Submit.
Now add your key to the apache-dist-release-flagon/KEYS
file:
Code Block |
---|
$ cd apache-dist-release-flagon
$ (gpg2 --list-sigs $ASF_USERNAME@apache.org && gpg2 --armor --export $ASF_USERNAME@apache.org) >> KEYS
$ svn --username $SVN_USERNAME --no-auth-cache commit -m "Update flagon/KEYS for $GPG_KEY" |
Release Branch and Set Version
This will allow development to continue on master without affecting the release; it also allows quick-fixes to the release branch to address last-minute problems (which must of course be merged/cherry-picked back into master later). Do not use -rc1, -rc2 etc. in version strings. Use the version that will be the actual published version. (The artifacts that get uploaded to the dist.apache.org/dev will include “-rc1” etc. in the folder name, but the contents will be as final. Therefore, turning the rc into the final is simply a case of taking the rc file and publishing it to the release folder with the correct name.)
Create the release branch and set the release version number
As mentioned above, in UserALE.js we use NPM as a release management tool. This includes preparing and RC for a community VOTE.
Make a clean checkout of the UserALE.js repository (ensuring that there are no local modifications):
Code Block $ git clone https://gitbox.apache.org/repos/asf/incubator-flagon-useralejs.git $ git pull --rebase # assumes that the Apache canonical repository is the default upstream for your master - amend if necessary $ git checkout -b $VERSION_NAME
- Make sure all unit and integration tests are passing.
- All tests must pass... if they do not then they need to be fixed before further progress can be made. Each flagon subproject you are attempting to release should contain a README with details on how to run the tests. If it does not, submit a pull request before progressing.
- Update the CHANGELOG.md to reflect the current release, this may also be required for other essential files such as NOTICE, README etc. Ensure all of these files are accurate and up-to-date. It is also advised to include the JIRA release report in CHANGELOG.md. This makes it very easy for people to see the relevant for this release bundle.
- Now change the version numbers in this branch in package.json.
If you have never made a flagon UserALE.js release, you are required to append your gpg key to the flagon KEYS file. This will then be used to sign all release artifacts. Much more about this can be found here http://apache.org/dev/release-signing.html
Note This is an extremely important part of the release procedure. It is essential to get it right and that all subsequent release managers' KEYS are associated with this file.
- If any changes based on the above have been made, then commit them to the VERSION branch.
Update master to reflect future version
The master
branch will now need updating to refer to the next planned version. (This step is not required if making a “milestone” release or similar.) The release notes should be cleared out and the version history augmented with the new version. Also ensure that package.json and the example index.html reflect the new version.
Code Block |
---|
$ git add . && git commit -m "Change version to $NEW_MASTER_VERSION" |
Switch back to the current release branch
Move back to the release version.
Code Block |
---|
$ git checkout $VERSION_NAME |
Making the release artifacts
Checkout the release scripts
Code Block |
---|
$ git clone https://github.com/apache/incubator-flagon |
The release utility scripts reside within the release subdirectory.
The release scripts will:
- Prepare a staging directory for the source code release
- Create .tar.gz and .zip artifacts of the source code
- Invoke npm to build the source code (including running unit tests)
- Save the .tar.gz and .zip artifacts produced by the build of
incubator-flagon/release/make-release-artifacts.sh
- For each of the produced files, produce SHA512 and GnuPG signatures
At the end of the script, it will show you the files it has produced and their location.
Please note that the script will thoroughly clean the Git workspace of all uncommitted and unadded files even in dry run mode. Therefore you really want to run this against a secondary checkout. It will wipe .project
files and other IDE metadata, and bad things can happen if an IDE tries to write while the script is running. Consider using the docker configuration provided.
The script has a single required parameter -r
which is given the release candidate number - so -r1
will create release candidate 1 and will name the artifacts appropriately.
The script takes a -n
parameter to work in dry run mode; in this mode, the script will ONLY create a local copy of release artifacts in the /release folder. It will NOT stage release artifacts to be checked into the staging area.
Code Block |
---|
# A dry run to test everything is OK
$ ./incubator-flagon/release/make-release-artifacts.sh -r $RC_NUMBER -n
# The real build, which will publish artifacts
$ ./incubator-flagon/release/make-release-artifacts.sh -r $RC_NUMBER |
Once this has completed, you will need to check-in the release artifacts into the staging environement.
Push the source release artifacts and signatures to dist.apache.org as described below.
Check out flagon release staging area. The artifacts we push to this area are the ones we make available on official
Apache mirrors. These are therefore the sources artifacts we link to from the flagon site. e.g.
- In your local copy of flagon (master), navigate to $flagon/target directory and copy the src.zip and src-tar.gz artifacts along with relevant signatures to the above release staging directory.
- You should aim to include all relevant signatures along with these src artifacts. This would entail
SHA and ASC signatures for each artifact. More information on this can be found here - http://apache.org/dev/release-signing.html - copy the CHANGELOG.md to this directory as well
- finally, svn add all of the above artifacts and commit them to the flagon dev release staging area
Next, progress to the creation of the VOTE thread as below...
Verify the release artifacts
At minimum you should do a few things to test code that will be available at release:
- Check the signatures generated by release artifacts: GPG and GPG Keychain provide tools to test .asc signatures and verify that your signing key matches your private key.
- Check the src builds: Create copies of src.tar and/or src.zip files, and initiate the NPM build and test scripts. Make sure they pass.
- Check the bin artifacts: Use the UserALE.js example server and point our index.html test page at the minified UserALE.js scripts to ensure that you're generating logs.
Publish to the staging area
Make a signed tag for this release candidate:
Code Block |
---|
$ git tag -a $(VERSION NUMBER) -s -m "Tag release ${VERSION_NAME} release candidate ${RC_NUMBER}" rel/apache-flagon-useralejs-incubating-${VERSION_NAME}-rc${RC_NUMBER}
$ git show tag $(VERSION NUMBER) |
Now push the release candidate tag:
Prepare the VOTE thread based on the artifacts
Send something like the following to the user@ and dev@flagon lists
Code Block | ||
---|---|---|
| ||
To: "Apache flagon Developers List" <dev@flagon.incubator.apache.org>, "Apache flagon User List" <user@flagon.incubator.apache.org>
Subject: VOTE Release Apache flagon (Incubating) X.Y
Hi Folks,
Please VOTE on the Apache flagon X.Y Release Candidate #Z.
We solved 44 issues: http://url/of/jira/release/report
Git source tag (c2d58dd1440b4e2c66c1f40a4b6d4169d79bb6d3): http://s.apache.org/Eyv
Staging repo: https://repository.apache.org/content/repositories/orgapacheflagon-1001
Source Release Artifacts: https://dist.apache.org/repos/dist/dev/flagon/X.Y/
PGP release keys (signed using 48BAEBF6): http://flagon.incubator.apache.org/dist/KEYS
Vote will be open for 72 hours.
Thank you to everyone that is able to VOTE as well as everyone that contributed to Apache flagon X.Y.
[ ] +1, let's get it released!!!
[ ] +/-0, fine, but consider to fix few issues before...
[ ] -1, nope, because... (and please explain why) |
The above email includes the following
- A link to the JIRA Release Report... this is critical for making it explicit what was addressed in this particular
development drive. - The SVN tag created by the mvn release plugin
- A link to the (closed) staging repository on repository.apache.org
- Link to the official release artifacts
- The KEYS file used containing developer signatures. This should be used to check signatures of release artifacts.
Double check the accuracy of this email and ship it to the masses!!!
N.B. DO NOT DELETE YOUR LOCAL COPY OF THE flagon RELEASE YOU"VE JUST PUSHED
IT IS ABSOLUTELY ESSENTIAL THAT YOU KEEP THE LOCAL RELEASE COPY !!!!
Send out the RESULT thread
After the 72 hours waiting time, it is down to the release manager to close the VOTE thread. This is usually
done by replying to the VOTE thread but changing the title to the following
Code Block | ||
---|---|---|
| ||
Subject: [RELEASE] WAS:VOTE Release Apache flagon X.Y
The RESULT thread should basically tally up the VOTE's something like the following would do nicely
Hi Everyone,
As the 72 hours period has come and gone I would like to bring this thread to a close.
The VOTE's have been counted and RESULT's are as follows
[7] +1, let's get it released!!!
Tom
Dick
Harry
Lewis John McGibbney *
[0] +/-0, fine, but consider to fix few issues before...
[0] -1, nope, because... (and please explain why)
*flagon PMC Binding VOTE
I'll progress with the remainder of the release procedure. |
If the release passes, progress to the next step, if not then head over to dev@flagon and discuss
how to revert the release. Assuming it passes however, progress to the next section.
Release the Source Artifacts
- svn cp https://dist.apache.org/repos/dist/dev/incubator/flagon/ to https://dist.apache.org/repos/dist/release/incubator/flagon//X.Y/
Make sure that the up-to-date KEYS file exists in https://dist.apache.org/repos/dist/release/incubator/flagon/
Once all artifacts and signatures have been copied over, delete the dev area
The release artifacts will be copied over to apache.org/dist in due course and available for public download.
Release UserALE.js to NPM.
Publish UserALE.js to NPM
Follow instructions on https://docs.npmjs.com/getting-started/publishing-npm-packages. Detailed below.
Use
npm publish
to publish the package. Note that everything in the directory will be included unless it is ignored by a local.gitignore
or.npmignore
file as described innpm-developers
. Also make sure there isn't already a package with the same name, owned by somebody else.To Test: Go to
https://npmjs.com/package/useralejs
. The published contents are now available in NPM registry.
Update the Website to reflect the release
This can be done easily by editing the apache-flagon page in the ASF project website. Details are provided in the README. Then commit the changes to the master branch. Jenkins will rebuild the site within about half an hour, and you can observe your changes here: http://flagon.incubator.apache.org/releases/.
It is important that all links on downloads.html are accurate including the signatures links. Also the PGP key reference to the signed artifacts should be updated to reflect the release managers KEY.
Code Block | ||
---|---|---|
| ||
Apache UserALE.js 0.1.0 is now available:
- Source Code: [0]
- Downloads: [1]
- NPM package: [2]
******* PGP key reference to signed artifacts needed ?? *******
UserALE.js uses the Apache Software License v2.0.
----
For future releases, stay tuned and sign up for our mailing lists to keep up to date!
You can always find current flagon code in our git repositories [3], or on github [4].
[0] http://git-wip-us.apache.org/repos/asf/incubator-flagon-user-ale [1] http://apache.org/dist/ [2] https://www.npmjs.com/package/useralejs
[3] http://incubator.apache.org/projects/flagon.html [4] https://github.com/apache?q=flagon |
Announce the Release
Code Block | ||
---|---|---|
| ||
Hi, The Apache flagon | ||
Code Block | ||
| ||
Hi Folks, The Apache SensSoft team are pleased to announce the immediate availability of Apache UserAle.js 0.1. The Apache UserALE.js is an open source tool to quickly and efficiently instrument a javascript frontend application. UserALE.js uses the Apache Software License v2.0. UserALE.js is released as both source code, downloads for which can be found at our releases page [0] as well as npm package which can be found on NPM [1]. This release addresses a modest XXXXX issues with ... blah blah blah. The full Jira release report can be found here [2]. Thank you Lewis (on behalf of SensSoftflagon PMC) [0] http://senssoftflagon.incubator.apache.org/releases/ [1] https://www.npmjs.com/package/useralejs [2] URL for Release Report in Jira |
...
- Send an ANNOUNCEMENT to the following lists
- Internal Apache Announcement list - announce@apache.org
...