This guide, and other linked pages, attempt to supply all of the detailed information needed to produce an official ASF release.

For releases pre-1.2.0 see Release Managers Guide Pre-1.2.0

Go to start of metadata

 

Prerequisites

  • You have to be an Apache Edgent committer, as the Release Manager (RM) needs to have write access to the Git repos.
  • An RM MUST have his public key appended to the KEYS file checked in to Git, the key published on one of the public key servers (e.g. http://pgpkeys.mit.edu), the key in their public people.apache.org home directory and their key in https://people.apache.org/keys/committer. More info can be found at http://www.apache.org/dev/release-signing.html. Also PGP Cheat Sheet
  • Make sure you have installed the required versions of Java.  More info can be found in the DEVELOPMENT.md.
  • You will need subversion installed in order to stage the release candidate and promote it to a release.
  • Review src/site/asciidoc/releasing.adoc.  Unfortunately, at this time the process is split between these two documents.

Pre-release

The JIRA includes subtasks to track the status of:

 

The rest of this document describes the actions the RM must take for the various release steps:

Preparing Sources

  • Ensure the top level LICENSE and NOTICE files are current. Check that the years in the copyright statement in the NOTICE.  The analogous files in the generated jars are auto generated by the maven build and need not be checked (see DEVELOPMENT.md)
  • Check licenses with RAT - see Apache Release Audit Tool.  The maven build automatically runs RAT and fails if there are issues. The RAT report is in target/rat.txt.
  • Update the README. Make sure the list of dependencies and their licenses is still accurate. Update the version number.
  • Update RELEASE_NOTES. Include list of bugs that were fixed in this release.
  • Update the CONTRIBUTORS - see Updating CONTRIBUTORS
  • If it hasn't been done already, make sure the version information has been updated in gradle.properties. Updating gradle.properties will update the name of the bundles to apache-edgent-${build_version}-incubating-src and -bin.  The buildTools scripts also consult this file to learn the X.Y.Z version value.
  • It is highly recommended that you do the above and a full build and test for all platforms on the develop branch and fix any problems before branching for the release.  Any additional stabilization/fix changes that are added to the release branch will need to be cherry-pick-merged back to the develop branch.  If the Jenkins builds for the develop branch are showing success, that's also a good indicator all is fine (the Jenkins builds test all platforms) - see DEVELOPMENT.md for Jenkins info.  To do your own build&test:
    • git checkout develop
    • mvn clean install -Pplatform-java7,platform-android
  •  If you haven't already done so, create the "[LAST CALL]" thread - see the Sample process emails.
     

Creating a Release Management Clone

  • Clone the ASF git repository (not the mirror on github)
  • Use the clone for performing the release management activities.  The directions and scripts below work when all of the activities are performed in such a clone.  You can dispose of it when done with the release.
  • The name of the clone should begin with "mgmt-edgent".
  • If you or others end up adding commits to the release branch from other clones/forks, you will want to ensure this mgmt clone has a refreshed release branch before performing activities like tagging and building release candidates. You can use buildTools/refresh_release_branch.sh for that.
git clone https://git-wip-us.apache.org/repos/asf/incubator-edgent.git  mgmt-edgent-<version>
cd mgmt-edgent-<version>

Begin the release process

  • Record the release's X.Y.Z version for use by other scripts
  • The scripts prompt before performing any modifying actions and echos any git commands performed
  • The scripts print usage with a "-?" or "–help" arg
  • Ensure your local master branch is up to date if needed - git pull origin master
buildTools/begin_release.sh  X.Y.Z   # the release version, e.g., 1.2.0
output
Proceed using this clone? [y/n] y
The release property file has been created for release version X.Y.Z

Create the Release Branch, Prepare it, Build and Stage the Release Candidate binary artifacts in Nexus

  • It is highly recommended that you do the above "Preparing Sources" before proceeding
  • If you haven't already done so,  create the "[DISCUSS]" thread on the dev mailing list see the Sample process emails.
  • Follow the directions and workflow in src/site/asciidoc/releasing.adoc
    • it will redirect you back to this document for various parts of the workflow

 

Staging the Source Release Candidate

  • Note: staging of the release candidate's binary artifacts in Nexus is the domain of src/site/asciidoc/releasing.adoc and should have already been performed

  • Make the release candidate artifacts available by adding them to the X.Y.Z-incubating/rc<n> ASF subversion repository directory under https://dist.apache.org/repos/dist/dev/incubator/edgent  See http://www.apache.org/dev/release.html#upload-ci

  • The script should do everything needed.  You may still find subversion cheatsheet helpful.

  • The script expects / creates a svn checkout area under <HOME>/svn/dist.apache.org/repos/dist/dev/incubator/edgent, stages the artifacts under it and tells the user how to commit the changes when they're ready.

  • Once everything is staged, update the "[DISCUSS]" thread with the branch, tag, and RC location info - see the Sample process emails.
  • The edgent directory structure in the dev distribution area is:
    • KEYS
    • X.Y.Z-incubating/
      • rc<n>/
        • README
        • RELEASE_NOTES
        • source bundles and signatures
buildTools/stage_release_candidate.sh <the-rc-number>
output
Base svn Edgent dev directory to stage to: /Users/dlaboss/svn/dist.apache.org/repos/dist/dev/incubator/edgent
Proceed with staging for 1.0.0-incubating-RC2? [y/n] y
Generating checksums for ...
...
SUCCESS: all checksum files generated
/Users/dlaboss/svn/dist.apache.org/repos/dist/dev/incubator/edgent/.svn: No such file or directory
Setup that svn checkout now? [y/n] y
Be patient while downloading...
+ mkdir -p /Users/dlaboss/svn/dist.apache.org/repos/dist/dev/incubator
+ cd /Users/dlaboss/svn/dist.apache.org/repos/dist/dev/incubator
+ svn co https://dist.apache.org/repos/dist/dev/incubator/edgent --depth empty
+ svn update /Users/dlaboss/svn/dist.apache.org/repos/dist/dev/incubator/edgent/KEYS
A /Users/dlaboss/svn/dist.apache.org/repos/dist/dev/incubator/edgent/KEYS
Updated to revision 17411.
Checking the svn status of /Users/dlaboss/svn/dist.apache.org/repos/dist/dev/incubator/edgent:
Is the svn status ok to continue (blank / nothing pending) ? [y/n] y
Copying artifacts to /Users/dlaboss/svn/dist.apache.org/repos/dist/dev/incubator/edgent...
+ svn add /Users/dlaboss/svn/dist.apache.org/repos/dist/dev/incubator/edgent/1.0.0-incubating/rc2
A /Users/dlaboss/svn/dist.apache.org/repos/dist/dev/incubator/edgent/1.0.0-incubating/rc2
...

+ svn status /Users/dlaboss/svn/dist.apache.org/repos/dist/dev/incubator/edgent
A /Users/dlaboss/svn/dist.apache.org/repos/dist/dev/incubator/edgent/1.0.0-incubating/rc2
A /Users/dlaboss/svn/dist.apache.org/repos/dist/dev/incubator/edgent/1.0.0-incubating/rc2/LICENSE
...
If you choose not to proceed, you can later run the following to commit the changes:
 (cd /Users/dlaboss/svn/dist.apache.org/repos/dist/dev/incubator/edgent; svn commit -m "Add Apache Edgent 1.0.0-incubating/rc2")
Proceed to commit the changes? [y/n] y
+ cd /Users/dlaboss/svn/dist.apache.org/repos/dist/dev/incubator/edgent
+ svn commit -m "Add Apache Edgent 1.0.0-incubating/rc2"
...
The KEYS and 1.0.0-incubating-RC2 have been staged to https://dist.apache.org/repos/dist/dev/incubator/edgent

 

 

Pre-Check the Staged RC

The RM should perform their Staged RC Validation steps BEFORE starting the RC vote, in order to spare the community from wasting time if the RC seems to have a problem. 

Verify / ensure the release branch's Jenkins build is green https://builds.apache.org/view/E-G/view/Edgent/

Note: if not creating / following a collection of JIRA tasks for the release process, this is a reminder that the Kafka connector tests are manual-only at this time and need to be run.  See DEVELOPMENT.md for directions on setting up and running the tests (its not too much work).

If there are any problems, raise them in the "[DISCUSS]" thread.  If the decision is that the RC can proceed as is, then continue the workflow.  Otherwise treat this as a failed vote and follow the actions under "Cancelling the Release" below.

The dev@ RC Vote

Start the vote on the dev mailing list see the Sample process emails.

Per http://www.apache.org/dev/release.html#approving-a-release "Before voting +1 PMC members are required to download the signed source code package, compile it as provided, and test the resulting executable on their own platform, along with also verifying that the package meets the requirements of the ASF policy on releases."

More broadly items that need to be verified (will/may be checked by higher level groups like the IPMC):

  • bundle names have "incubating" in them
  • incubating disclaimer exists (DISCLAIMER file and/or copies of the notice in README)
  • LICENSE and NOTICE files are good
  • README and RELEASE_NOTE files are present and accurate
  • signature and hashes are present and correct
  • the signing PGP key is associated with an "apache.org" email address and is published
  • no unexpected/disallowed binary files in the source package (via RAT)
  • all source files have ASF headers (via RAT)
  • can compile the source from directions in README
  • compiled source tests pass
  • staged convenience binary artifacts in Nexus are healthy

See Staged RC Validation for detailed steps.

The RM may call the result of the vote no sooner than 72 hrs. after it was started. Since a release vote is 'Majority Approval', a release is approved if it gets at least 3 binding +1 votes and more binding +1 than -1 votes. Binding votes are cast by PPMC members. For a complete list of PPMC members, see http://people.apache.org/committers-by-project.html#edgent.

If the vote is successful, post the result to the dev@ list (Sample process emails) and continue the process with IPMC Approval Vote.

If the vote is unsuccessful, fix the issues and restart the process. See Canceling the Release.

Canceling the Release Candidate

If the vote fails, or you decide to redo the release:

IPMC Approval Vote

Once the Edgent dev@ community has approved the release candidate, an IPMC release approval VOTE is initiated on the general@incubator.apache.org.

  • See Sample process emails for the required content for the vote and the result.
  • Once 72 hours have passed and you have 3 binding +1 votes, and more +1 than -1, the vote passes the you can release the artifacts to the release distribution area and send an announce email out (below).  Send out a result email with the results.
  • Binding votes are cast by IPMC members. For a complete list of IPMC members, see http://people.apache.org/committers-by-project.html#incubator-pmc
  • If the vote fails, follow the Canceling the Release step
  • If the vote passed, continue with the next step below

Publishing the Source Release

Following the IPMC release approval for a release candidate, the release needs to be published.

  • The KEYS need to be updated in the ASF subversion repository directory under https://dist.apache.org/repos/dist/release/incubator/edgent
  • The release candidate artifacts need to be moved to the X.Y.Z-incubating directory in that svn repository
  • The publish script uses the stage_release_candidate.sh created local svn checkout area. It will be refreshed to be up to date.
  • The script uses/creates the local release area svn checkout under <HOME>/svn/dist.apache.org/repos/dist/release/incubator/edgent
  • The script prompts along the way and commits the changes.
  • A superseded release will be removed from the release distribution area after the downloads page is updated as part of the Update the Edgent website task below.

 

publish
buildTools/publish_release.sh <the-rc-number>
output
Proceed to publish release 1.0.0-incubating from candidate 1.0.0-incubating-RC2? [y/n] y
 
Proceed to update the KEYS? [y/n] y
+ svn update /Users/dlaboss/svn/dist.apache.org/repos/dist/dev/incubator/edgent/KEYS
Updating '/Users/dlaboss/svn/dist.apache.org/repos/dist/dev/incubator/edgent/KEYS':
At revision 17411.
+ mkdir -p /Users/dlaboss/svn/dist.apache.org/repos/dist/release/incubator
+ cd /Users/dlaboss/svn/dist.apache.org/repos/dist/release/incubator
+ svn co https://dist.apache.org/repos/dist/release/incubator/edgent --depth empty
Checked out revision 17411.
+ svn update /Users/dlaboss/svn/dist.apache.org/repos/dist/release/incubator/edgent/KEYS
Updating '/Users/dlaboss/svn/dist.apache.org/repos/dist/release/incubator/edgent/KEYS':
A    /Users/dlaboss/svn/dist.apache.org/repos/dist/release/incubator/edgent/KEYS
Updated to revision 17411.
+ cp /Users/dlaboss/svn/dist.apache.org/repos/dist/dev/incubator/edgent/KEYS /Users/dlaboss/svn/dist.apache.org/repos/dist/release/incubator/edgent/KEYS
+ svn commit /Users/dlaboss/svn/dist.apache.org/repos/dist/release/incubator/edgent/KEYS -m 'Release Apache Edgent 1.0.0-incubating from 1.0.0-incubating-RC2'

Proceed to move the 1.0.0-incubating-RC2 artifacts? [y/n] y
+ svn move https://dist.apache.org/repos/dist/dev/incubator/edgent/1.0.0-incubating/rc2 https://dist.apache.org/repos/dist/release/incubator/edgent/1.0.0-incubating

The ASF dev and release repositories have been updated:
    https://dist.apache.org/repos/dist/dev/incubator/edgent
    https://dist.apache.org/repos/dist/release/incubator/edgent
    https://www.apache.org/dist/incubator/edgent
    https://www.apache.org/dyn/closer.cgi/incubator/edgent

 

Publishing the Binary Release in Nexus

Following the IPMC release approval for a release candidate, the staged release in Nexus needs to be published.

  • Follow the Actions if the RC vote passed step in src/site/asciidoc/releasing.adoc

Merging to master

The release code/branch need to be merged to the master branch. 

There are two possible scenarios:

  • There are commits on the release branch and they can be merged without any conflicts

  • There are commits on the release branch and conflicts must get resolved

buildTools/merge_release.sh
output - no conflicts
+ git checkout -q master
+ git status
On branch master
Your branch is up-to-date with 'origin/master'.
Proceed to refresh the local master branch prior to merging? [y/n] y
+ git pull origin master
...

If you proceed to merge and there are conflicts you will need to
fix the conflicts and then commit the merge and push:
    git status  # see the conflicts
    ... fix the conflicts
    git commit -m "merged edgent-1.2.0"
    git push origin master
If you choose not to proceed you may run this script again later.
Proceed to (no-commit) merge branch edgent-1.2.0 to master? [y/n] y
+ git merge --no-commit --no-ff edgent-1.2.0
Automatic merge went well; stopped before committing as requested

If you choose not to proceed you will need to manually complete the
merge and push:
    git commit -m "merged edgent-1.2.0"
    git push origin master
Proceed to commit the merge and push? [y/n] y
+ git commit -m 'merged edgent-1.2.0'
...
+ git push origin master
...
output - conflict
+ git checkout -q master
+ git status
...
Proceed to refresh the local master branch prior to merging? [y/n] y
+ git pull origin master
...

If you proceed to merge and there are conflicts you will need to
fix the conflicts and then commit the merge and push:
    git status  # see the conflicts
    ... fix the conflicts
    git commit -m "merged edgent-1.2.0"
    git push origin master
If you choose not to proceed you may run this script again later.
Proceed to (no-commit) merge branch edgent-1.2.0 to master? [y/n] y
+ git merge --no-commit --no-ff edgent-1.2.0
Auto-merging file1
CONFLICT (content): Merge conflict in file1
Automatic merge failed; fix conflicts and then commit the result.

Merging to develop

As noted in src/site/asciidoc/releasing.adoc, if any stabilization/fix commits were added to the release branch, they must be cherry-pick-merged to the develop branch.  The release branch is NOT merged to the develop branch.

The release branch isn't merged is due to the way the maven release plugin operates.  The develop branch poms have already been set to the next SNAPSHOT development version.  Merging the release branch would try to put the release's poms on develop branch and that would break things.

Generally speaking, any non-maven-release-plugin commits on the release branch need to be cherry-pick-merged to develop. 

To identify if there are such commits for the release that was just created:

Look at the mirror repo on github, select the commits tab, then select the release branch in the pulldown

Identify the oldest "maven-release-plugin prepare release edgent-<VER>" commit for the release (there will only be one in the no-mods/problems case).

The newest commit on the release branch should be "maven-plugin-release prepare for the next development iteration".

If there are any non-maven-release-plugin commits between those, they must be cherry-pick-merged to develop.

TODO cherry-pick-merge pointers, example...

Update the Edgent website

The website https://edgent.apache.org/ (https://github.com/apache/incubator-edgent-website) needs to be updated with information about the release.  

NOTE: Wait 24 hours after publishing the release bundles before updating the live website content.  The download links direct the user to utilize an ASF mirror and it can take that long for the release bundles to propagate to the mirrors.

  • update site/_config.yml - update the documentation website's sidebar_version variable
  • update downloads.html
  • add Javadoc for the new version and update the "latest" link to reference it - see the update Javadoc wiki page
  • TODO add an announcements.html page or add an announcement on the homepage?
  • see website README.md for how to update the site content

Announce the release

VERIFY THE  WEBSITE UPDATE HAS OCCURRED BEFORE ANNOUNCING THE RELEASE.  It normally updates right away but there can be delays.

Announce the release after the release has been published and https://edgent.apache.org/ has been updated with information about the release.

  • See Sample process emails for the announcement email for announce@apache.org, cc'ing the Edgent dev and users lists.
  • The mail should be sent by your @apache.org address.
  • Preferably sign the email with the same KEY you used to sign the release. Note: Thunderbird with Enigmail for OpenPGP seems to be the easiest to configure on the Mac. AppleMail with GPGMail is another alternative. If you are not subscribed to a list with your apache address the email has to be accepted by the moderator of the list before it will get posted. Make sure the email is plain text and not HTML or it may be marked as spam and rejected.
  • Update the Apache Edgent home page and the Apache Edgent blog with the news. Encourage people to tweet about the release.
  • Announce the release with a tweet on  https://twitter.com/ApacheEdgent   If you ask nicely queeniema@apache.org will be happy to post one.  If you're a PPMC member the acct info was posted on the private@ list.
  • Ask one of the Edgent mentors (via the @dev list) to update http://incubator.apache.org/projects/edgent.html with a news item for the release

Wrap Up

  • Once you have published the release and merged the release branch back to master you can remove the local git clone that you created for managing the release.
  • Update JIRA. Go to the Admin section on the Edgent JIRA and mark Edgent X.Y.Z as released. You may need the help of a JIRA administrator to do this.
  • Remove the superseded release from the release distribution area.  They are always available under https://archive.apache.org/dist/incubator/edgent
  • Update the edgent-version that the samples are configured to use
    • follow the directions in incubator-edgent-samples/README.md and
      1. clone
      2. check / adjust the pom for this new Edgent version
        1. update-samples-version.sh --edgent-version X.Y.Z
      3. run some samples just to be sure all is fine
      4. commit the changes

Reference

Acknowledgement: this content was initially cloned from the analogous Apache Flex project page

  • No labels