Introduction 

This documents the Apache UserALE.js release procedure. It is a living document; successive release managers will maintain it ensuring that all software packages are kept reasonably up-to-date and that good practice is followed and maintained with regards to the release procedure and resulting release artifacts. If there is something missing, feel free to comment or edit. Thank you, and let's get started.

Things you should read first:

Before we go any further, there is some good (potentially essential and a huge time saving practice) documentation on this topic. Please see the below links before going any further.

• http://apache.org/dev/#releases
• http://apache.org/dev/release-signing.html
• http://apache.org/dev/release-publishing.html

Release Prerequisites

• Create a new release in JIRA. If you do not already have privileges enabling you to do so, ask the 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.

Apache releases are posted to dist.apache.org, which is a Subversion repository.

We have two directories here:

• https://dist.apache.org/repos/dist/release/incubator/flagon - This is where PMC approved releases go. DO NOT UPLOAD here until we have a vote passed on dev@Flagon. Check out this folder and name it apache-dist-release-Flagon.

• https://dist.apache.org/repos/dist/dev/incubator/flagon - 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 Flagon community and over the general @incubator community. Check out this folder and name it apache-dist-dev-flagon.

Example:

svn co https://dist.apache.org/repos/dist/release/incubator/Flagon apache-dist-release-flagon
svn co https://dist.apache.org/repos/dist/dev/incubator/Flagon apache-dist-dev-flagon

GPG Keys

The release manager must have a GPG key to be used to sign the release. See below to install gpg2 (with a gpgalias). The steps here also assume you have the following set (not using whoami if that’s not appropriate):

ASF_USERNAME=`whoami`
GPG_KEY=$ASF_USERNAME@apache.org
SVN_USERNAME=$ASF_USERNAME

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:

$ 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 https://dist.apache.org/repos/dist/dev/incubator/flagon 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): 

  $ 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 locally: 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.
  • All tests must pass via Jenkins: Apache UserALE.js has a CI build via Jenkins, which executes linting (pre-test), builds, and tests on an Linux/Ubuntu server. If these tests do not pass (e.g., builds fail), the release cannot proceed. This ensures that there is a common testing framework that reduces the risk that release artifacts will only build successfully on developer platforms (e.g., Windows, Mac).
• 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 changes 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

  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.

Prepare for Next Development

• In the JIRA Administration Interface, go to
  • Versions
  • for the release tag you've just released, add a release date and then release it

Update the version on master

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.). 

$ git checkout master

Merge any changes to Release branch(es) during the process of testing and verifying release candidates.

$ git merge $VERSION_NAME
$ git push origin master

Then update versioned files in the repo to reflect the next planned version (number):

1. README.md's
2. Definition of a Project (DOAP)
3. package.json
4. regenerate build artifacts and package-lock.json
5. index.html (UserALE.js test page)
6. Update copyright dates, if needed

Switch back to the release branch

Move back to the release version.

$ git checkout $VERSION_NAME 

Making the release artifacts

Checkout the release scripts

$ git clone https://github.com/apache/incubator-flagon

The release utility scripts reside within the release subdirectory in the incubator-flagon repository.

You'll need to run it in the same directory as your cloned incubator-flagon-userale release candidate.

The release script(s) will:

1. Prepare a staging directory for the source code release (svn checkout of distribution repositories)
2. Export a distribution path for files through .bash_profile
3. Create .tar.gz and .zip artifacts of the source code
4. Invoke npm to build the source code (including running unit tests), and deploy artifacts to a NPM remote repository
5. Save the .tar.gz and .zip artifacts produced by the build of incubator-flagon/release/make-release-artifacts.sh
6. For each of the produced files, produce SHA512 and GnuPG signatures
7. Stage release artifacts for commit to /dev distribution repository 

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 create release artifacts in a local folder within your incubator-flagon/release directory (rather than pushing them to your checked-out copy of the /dev/ repo. This speeds up the process (the NPM deploy in particular slows down the build) and will catch any problems such as PGP or mocha problems much sooner.

# A dry run to test everything is OK
$ ./incubator-flagon/release/make-release-artifacts.sh -r $RC_NUMBER -n

# The real build, which will stage artifacts for commit in /
$ ./incubator-flagon/release/make-release-artifacts.sh -r $RC_NUMBER

Once release artifacts have been generated: 

Push the source release artifacts and signatures to https://dist.apache.org/repos/dist/dev/incubator/flagon as described below:

Check out Flagon release staging area (your local copy of /dev/ established by release scripts). The artifacts we push to this area are the ones we VOTE on. Once that VOTE passes, the same artifacts will be copied to https://dist.apache.org/repos/dist/release/incubator/flagon for official release on Apache mirrors, and link to from the Flagon site.

• svn co https://dist.apache.org/repos/dist/dev/incubator/flagon/

• 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
• ensure that the KEYs file is updated to include your public signing PGP keys, if they are not already
• 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

Release artifacts are verified by:

1. YOU, prior to staging. It's always best to verify your own signature and run last minute unit and integration tests on copied versions of the release artifacts. 
   1. Refer to our Testing Framework for guidance in testing
2. PPMC (e.g., Mentors). They will verify Checksums and signature prior to VOTING on releases. This is done to verify signatures of release manager/committers and verify that nothing was lost in the release artifact build.

Publish to the staging area

Make a signed tag for this release candidate. This is very important as this also verifies who is staging the release:

$ git tag -a ${VERSION_NAME}-rc${RC_NUMBER} -s -m "Tag release ${VERSION_NAME} release candidate ${RC_NUMBER}"
$ git push origin --tags

$ git push userale-js $VERSION_NAME && git push apache-git rel/apache-flagon-userale-js-${VERSION_NAME}-rc${RC_NUMBER}

$ git push origin :refs/tags/<tag>

$ mkdir apache-flagon-useralejs-${VERSION_NAME}-rc${RC_NUMBER}

$ svn add apache-flagon-useralejs-${VERSION_NAME}-rc${RC_NUMBER}
$ svn commit --username $SVN_USERNAME --no-auth-cache --message "Add apache-flagon-useralejs-${VERSION_NAME}-rc${RC_NUMBER} to dist/dev/flagon"

Prepare the VOTE thread based on the artifacts

Send something like the following to the user@ and dev@Flagon lists

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.z}

Hi Folks,

Please VOTE on the Apache Flagon {x.y.z} Release Candidate # {n}.

About Flagon: http://flagon.incubator.apache.org/

This {Major/Minor/Patch} release includes :

1. ...
2. ...
3. ...

We solved {n} issues: {link to JIRA release}

Git source tag ({tagID}): https://github.com/apache/incubator-flagon-useralejs/releases/tag/{tag link}

Staging repo: https://dist.apache.org/repos/dist/dev/incubator/flagon/

Source Release Artifacts: https://dist.apache.org/repos/dist/dev/incubator/flagon/apache-flagon-useralejs-incubating-{x.y.z}-RC#/

PGP release keys (signed using {8/16 char sigID}): https://dist.apache.org/repos/dist/release/incubator/flagon/KEYS

Link to Successful Jenkins Build: https://builds.apache.org/job/useralejs-ci/{##}

Reference the {product} testing framework to assist in your unit and integration tests: https://cwiki.apache.org/confluence/display/FLAGON/UserALE.js+Testing+Framework

Vote will be open for 72 hours. Please VOTE as follows:

[ ] +1, let's get it released!!!
[ ] +/-0, fine, but consider to fix few issues before...
[ ] -1, nope, because... (and please explain why)

Along with your VOTE, please indicate testing and checks you've made against build artifacts, src, and documentation:

[ ] Build and Unit Tests Pass
[ ] Integration Tests Pass
[ ] "Incubating" in References to Project and Distribution File Names
[ ] Signatures and Hashes Match Keys
[ ] DISCLAIMER, LICENSE, and NOTICE Files in Source and Binary Release Packages 
[ ] DISCLAIMER, LICENSE, and NOTICE are consistent with ASF and Incubator Policy
[ ] CHANGELOG included with release distribution
[ ] All Source Files Have Correct ASF Headers
[ ] No Binary Files in Source Release Packages

Thank you to everyone that is able to VOTE as well as everyone that contributed to Apache Flagon {x.y.z}

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 Git tag referring to the last commit for the Release Candidate
• 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

Subject: [RESULT] 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!!! 
Clay
Dave
Jana 
Lewis*
Dave*
Chris*
..., e.g. 
[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

PPMC and MENTORS do this, or authorize committers to do this:

• 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, remove old release candidates from the staging 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 (if necessary to update after VOTING)

1. Follow instructions on https://docs.npmjs.com/getting-started/publishing-npm-packages. Detailed below.

   # npm publish workflow
   $ cd {release branch local dir}
   $ npm login # add in your credentials (talk to committers, PPMC for access)
   $ npm publish # publish to npm public registry

2. Use the workflow described above to publish. Note that everything in the directory will be included unless it is ignored by a local .gitignore or .npmignore file as described in npm-developers. Also make sure there isn't already a package with the same name, owned by somebody else. 

3. To Test: Go to https://www.npmjs.com/package/flagon-userale. The final published contents of the release are now available in NPM registry. Any future publications will be differently versioned.

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.

Apache UserALE.js X.Y.Z is now available:
- Source Code: [0] {link to github release}
- Downloads:  [1] http://flagon.incubator.apache.org/releases/
- NPM package: [2] https://www.npmjs.com/package/flagon-userale
 
******* 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] https://gitbox.apache.org/repos/asf/incubator-flagon-useralejs.git
[1] http://flagon.incubator.apache.org/releases/ (links to mirrors)
[2] https:https://www.npmjs.com/package/flagon-userale
[3] http://incubator.apache.org/projects/flagon.html 
[4] https://github.com/apache?q=flagon

Apache Flagon is an effort undergoing incubation at The Apache Software Foundation (ASF),
sponsored by the Apache Incubator project. Incubation is required of all newly accepted
projects until a further review indicates that the infrastructure, communications, and
decision making process have stabilized in a manner consistent with other successful
ASF projects. While incubation status is not necessarily a reflection of the
completeness or stability of the code, it does indicate that the project has yet to be
fully endorsed by the ASF.

Announce the Release

Before releases can be announced through any other outlet (e.g., mass email, Twitter, Researchgate, etc., etc.), an official announcement must be made by the ASF. 

Relevant policies can be found here:

• https://www.apache.org/dev/release-distribution#download-links
• http://www.apache.org/legal/release-policy.html#release-announcements
• https://www.apache.org/dev/release-download-pages.html#download-page

An email must be sent to announce@apache.org with the text below, copy (cc) user@incubator.flagon.apache.org, dev@incubator.flagon.apache.org. Note that only an email from a committer email account from an apache.org email address can post to announce@. Best practice is to send a PGP verifiable, signed email with the announcement.

SUBJECT: [ANNOUNCE] Release of Apache Flagon UserALE.js (Incubating) vX.Y.Z

The Flagon team is pleased to announce the immediate availability of Apache Flagon UserALE.js (Incubating) version x.y.z
 
Apache Flagon UserALE.js (Incubating) is a free, open-source application for thin-client behavioral logging. Apache UserALE.js is suited for business analytics and enterprise application monitoring, but built for precision workflow analysis, UI/UX research and user-testing. Apache UserALE.js (Incubating) uses the Apache Software License v2.0. 

The version x.y.z release addresses/adds [issues/functionality]:
...
...
...

The full CHANGELOG can be found linked on Apache Flagon's Releases page: http://flagon.incubator.apache.org/releases/

Apache UserALE.js (Incubating) vX.Y.Z release artifacts are available through the Apache Software Foundation's official download mirrors, which can be accessed conveniently through the Apache Flagon website download page: http://flagon.incubator.apache.org/releases/. This release is also available as an npm package for node.js applications, found on the npm registry https://www.npmjs.com/package/flagon-userale.


Thank You,

{Release Manager's Name} (on behalf of Apache Flagon PPMC) 


Apache Flagon is an effort undergoing incubation at The Apache Software Foundation (ASF),
sponsored by the Apache Incubator project. Incubation is required of all newly accepted
projects until a further review indicates that the infrastructure, communications, and
decision making process have stabilized in a manner consistent with other successful
ASF projects. While incubation status is not necessarily a reflection of the
completeness or stability of the code, it does indicate that the project has yet to be
fully endorsed by the ASF.

Archive Old Releases

... forthcoming