Differences between revisions 43 and 44
Revision 43 as of 2013-06-07 21:20:01
Size: 10120
Editor: Steven Gill
Revision 44 as of 2013-06-08 00:33:51
Size: 10172
Editor: Steven Gill
Deletions are marked like this. Additions are marked like this.
Line 214: Line 214:
   * Tweet it on https://twitter.com/apachecordova

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.

|-cordova-$PLATFORM.zip  (per platform)

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

TODO: Enhance coho tool to take care of JIRA tasks. There is sample code under the cordova-labs/jira repo/branch.

For now, create the release bugs by cloning CB-3464.

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

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

./cordova-coho/coho create-release-branch --version 2.8.0rc1 -r js -r app-hello-world
./cordova-coho/coho tag-release --version 2.8.0rc1 -r js -r app-hello-world

Branching Platform Repositories

Before creating the release branch:

  1. Run Apache RAT to ensure copyright headers are present

    • ./cordova-coho/coho audit-license-headers -r android | less

  2. Update the copy of app-hello-world
    • This usually lives within bin/templates somewhere
    • TODO: More details needed here
  3. Remove things that were deprecated and slated for removal
  4. 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

Creating the release branch

The coho tool creates the release branches, update VERSION files, and update the cordova.js snapshot:

./cordova-coho/coho create-release-branch --version 2.8.0rc1 -r active

Testing & Documentation

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

When a regression is found:

  • Create a JIRA issue for it, and mark it as a blocker.

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

  • Run mobile-spec

    • Don't forget to set up your white-list
    • Don't forget to run through the manual tests in addition to the automatic tests
    • Test loading the app over HTTP (via "cordova serve" and setting the config.xml start page)
  • Run each platform's ./bin/create script
    • Ensure generated project builds & runs both through an IDE and through the cordova/* scripts

  • Ensure that a project created by the previous release's create script is easily updatable.
    • Usually this involves writing a script to perform necessary updates.
      • Script should be called bin/update_project.

    • Common things that change:
      • Changes to project file
      • Changes bundled helper scripts

Android Extras

  • Unit tests in: test directory

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.

./cordova-coho/coho tag-release --version 2.8.0rc1 -r $REPO_NAME

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). $REPO_NAME is usually the repo name without the "cordova-" prefix, to list the available repo names, run:

./cordova-coho/coho list-repos

Branching & Tagging cordova-docs

  1. Cherry pick relevent commits from master to 2.8.x branch
  2. Generate the docs for the release on the 2.8.x branch.
  3. Commit & tag on the 2.8.x branch.

  4. Cherry pick commit into master.

See Generating a Version Release for more details.

Uploading a Release Candidate

  1. Create the release .zip with coho:

./cordova-coho/coho create-release-snapshot --prev-version 2.7.0 --new-version 2.8.0rc1
  1. Upload it to: https://dist.apache.org/repos/dist/release/cordova/

TODO: COHO tool should do this step.

Final Details

Update cordova.apache.org

Update the Docs

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

  2. Ask Michael Brooks to update the docs.cordova.io redirect.

Announce It!

  1. Be sure to wait 24 hours after uploading the release before announcing in order to let the Apache mirrors pick up the file.
  2. Announce the release to the world!

Additional Information

  • Make sure the CLI tools (cordova-cli) work with the release. If a platform has modified structure or contents of platform-specific files, especially the config.xml file, cordova-cli will probably not work. Take a look at cordova-cli's project parser source files (src/metadata/<platform>_parser.js) for details on how it manipulates platform projects.

  • iOS Release Checklist

  • Android Release Checklist

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

CuttingReleases (last edited 2014-03-05 21:02:45 by AndrewGrieve)