Apache Cordova Releases

An official source release contains the source code for the repositories of the Apache Cordova platform, the signing keys and various checks to prove the validity of the release. 

 /
 |- KEYS .................................. signing keys
 |- cordova-VERSION-src.zip ............... zip file that contains the src of all platform repos
 |- .md5 .................................. md5 file containing the MD5 Checksum of the src zip
 |- .sha .................................. sha file containing the SHA Hash of the src zip
 |- .asc .................................. asc file that contains the ASCII Armoring of the zip

The /cordova-VERSION-src.zip/ is the official release artifact and contains the source code for all the platforms, the top level documents concerning licences, notices, disclaimer, and as well the readme for the Apache Cordova project. 

/
|-changelog
|-DISCLAIMER
|-cordova-$PLATFORM.zip  (per platform)
|-cordova-app-hello-world.zip
|-cordova-docs.zip
|-cordova-js.zip
|-cordova-mobile-spec.zip
|-LICENSE
|-NOTICE
|-README.MD

Release Philosophy

The Apache Cordova community aims to prepare releases monthly. Discussion for a release always happens on the mailing list.

We follow a rolling releases (sometimes called the Train Model) philosophy, which is to say, we value consistent release cadence as a priority over aiming to cram a particular issue, bug or feature to a particular date. Each minor release tends to be loosely themed on a generally agreed upon goal for the project. Bugs always take priority over new shiny.

Early in the project we stalled on 0.8.0 for almost a year, and as a result our community worked off the edge, making issue tracking very difficult, cascading into a host of predicability and reliability issues, jeopardizing the community. In 2009, when IBM joined the effort with Nitobi, we started releasing once a month, rolling issues over to the next minor.

We have recently, in the past year or so, started tagging Release Candidates about a week before the expected ship for minor release (such as 1.5.0rc1) which tends to tease out more bugs and avoid the embarrassing patch release. (1.4.1 comes to mind.)

Release Process

Getting Buy-in

  1. Email the dev mailing-list and see if anyone else is interested in cutting a release.
  2. See if there are any changes people are waiting to get in for the release.
  3. Review JIRA issues that are marked as "Fix For" this release.
    • Any issues that don't need fixes, bump to the next release.
  4. Agree upon a branching date / time.

Creating JIRA issues

To keep track of tagging progress and create JIRA issues for each component of a Cordova release, use the JIRA node.js scripts (under cordova-labs / jira branch).

Branching & Tagging cordova-js and cordova-app-hello-world

This should be done *before* creating branches on other repos

Steps for cordova-js

  1. Run Apache RAT to ensure copyright headers are present

  2. Create a branch: 
    •     git checkout master
    git fetch --tags
    git pull
    git checkout -b 2.7.x
  3. Update VERSION: 
    •     echo "2.7.0rc1" > VERSION
    jake
    git commit -am 'Set VERSION to 2.7.0rc1'

  4. Tag & Push 

    •     git tag 2.7.0rc1
    git push --tags origin 2.7.x

Steps for cordova-app-hello-world

  1. Run Apache RAT to ensure copyright headers are present

  2. Create a branch: 
    •     git checkout master
    git fetch --tags
    git pull
    git checkout -b 2.7.x
  3. Update VERSION: 
    •     echo "2.7.0rc1" > VERSION
    sed -i '' -e 's:"cordova-.*js":"cordova-2.7.0rc1.js":' www/index.html
    git commit -am 'Set VERSION to 2.7.0rc1'

  4. Tag & Push 

    •     git tag 2.7.0rc1
    git push --tags origin 2.7.x

Branching Platform Repositories

Before creating the release branch:

  1. Run Apache RAT to ensure copyright headers are present

  2. Update the cordova.js snapshot:
    • Android: 
      •      cp ../cordova-js/pkg/cordova.android.js framework/assets/js/cordova.android.js
    • iOS: 
      •      cp ../cordova-js/pkg/cordova.ios.js CordovaLib/cordova.ios.js
  3. Update the copy of app-hello-world
    • This usually lives within bin/templates somewhere
    • TODO: More details needed here
  4. Remove things that were deprecated and slated for removal
  5. For iOS only:

    1. Update CordovaLib/Classes/CDVAvailability.h

      1. add a new macro for the new version, e.g. 
        •            #define __CORDOVA_2_1_0  20100
      2. update CORDOVA_VERSION_MIN_REQUIRED with the latest version macro, e.g. 
        •            #ifndef CORDOVA_VERSION_MIN_REQUIRED
               #define CORDOVA_VERSION_MIN_REQUIRED __CORDOVA_2_1_0
           #endif

Creating the release branch

git checkout master
git pull
git checkout -b 2.7.x
git push origin 2.7.x

After creating the release branch

Steps for cordova-mobile-spec

  1. On release branch: 
    •     echo "2.7.0rc1" > VERSION
    sed -i '' -e 's:VERSION.*=.*;:VERSION="2.7.0rc1":' cordova.js

Steps for cordova-android

  1. On release branch: 
    •     echo "2.7.0rc1" > VERSION
    sed -i '' -e 's:"cordova-.*js":"cordova-2.7.0rc1.js":' bin/templates/project/assets/www/index.html
    sed -i '' -e 's:"cordova-.*js":"cordova-2.7.0rc1.js":' framework/assets/www/index.html
    sed -i '' -e 's:cordovaVersion.*=.*;:cordovaVersion = "2.7.0rc1";:' framework/src/org/apache/cordova/Device.java

Steps for cordova-ios

  1. On release branch: 
    •     echo "2.7.0rc1" > CordovaLib/VERSION

Testing & Documentation

Once all the repos are branched, we focus on testing & fixing all of the regressions we find.

When a regression is found:

To submit a fix: 

git checkout master
git commit -am 'Your commit message'
git push origin master
git log     # note the first five or six digits of the commit hash
git checkout 2.7.x
git cherry-pick -x commit_hash
git push origin 2.7.x

What to Test

Android Extras

iOS Extras

Documentation To Update

For each repository:

  1. Update RELEASENOTES.md (if the file is missing, use the iOS one as a reference: RELEASENOTES.md)

    1. Grab changes from a previous tag to HEAD i.e if the previous tag was "Foo" (if ambiguous, add a "refs/tags/" prefix to the tag): 
      •             git shortlog --no-merges Foo..HEAD
    2. Edit the commit logs - don't add the commits verbatim, usually they are meaningless to the user. Only show the ones relevant for the user (fixes, new features)
    3. Put the edited logs into a new section for the new version with a date (YYYYMMDD) in parentheses, and follow the previous formats
  2. Update README.md (if necessary)

  3. Ensure the Upgrade Guide for your platform is up-to-date

  4. Ensure the other guides listed in the sidebar are up-to-date for your platform

Tagging Platform Repositories

This is done once testing is complete, and documentation is up-to-date. 

git tag 2.7.0rc1
git push --tags origin 2.7.x

If for some reason a tag must be altered: 

git tag 2.7.0rc1 --force
git push --tags origin 2.7.x

Do *not* change the tag once the release .zip has been uploaded to apache servers and announced. Instead, create a new release candidate (going through all of the release steps above again).

Branching & Tagging cordova-docs

  1. Generate the docs for the release on the master branch.

  2. Branch & tag it in the same was as the other repos.

See Generating a Version Release for more details.

Uploading a Release Candidate

  1. Use the coho script to create the .zip file for the release candidate.

  2. Upload it to: TODO: Is there a place on Apache to host this?

Vote & Ship It!

  1. Start a VOTE thread on the Cordova mailing list. See http://markmail.org/message/fzmlzbvt3dgdpfrc and http://mail-archives.apache.org/mod_mbox/stdcxx-dev/200601.mbox/%3c43C1C0A0.7040401@roguewave.com%3e for good examples.

  2. People review the release candidate and cast their votes accordingly. See http://www.apache.org/dev/release.html#approving-a-release and http://www.apache.org/dev/release.html#what-must-every-release-contain for things to consider.

  3. A majority of at least three +1 votes from the (P)PMC is needed for the vote to pass.

  4. Make the approved release available at http://www.apache.org/dist/incubator/cordova/ ( also see https://dist.apache.org/repos/dist/release/cordova/ )

    • TODO: How to do this?

  5. Upload the new docs to http://cordova.apache.org/docs

  6. Update the project website cordova.apache.org to point to the new release & new docs

  7. Update the DOAP file at http://svn.apache.org/repos/asf/cordova/site/infra/doap_Cordova.rdf to update the pointer to the latest release.

  8. Announce the release to the world!
    • TODO: Through what channels?

Additional Information

More information for release engineers can be found at http://www.apache.org/dev/release.

CuttingReleases (last edited 2013-05-09 15:07:38 by Braden Shepherdson)