Differences between revisions 63 and 64
Revision 63 as of 2013-10-02 10:14:57
Size: 12791
Editor: MarcelKinard
Comment: added instructions on moving git tags
Revision 64 as of 2013-11-07 21:46:43
Size: 12791
Editor: JoshSoref
Comment: wikify page
Deletions are marked like this. Additions are marked like this.
Line 159: Line 159:
 * Test the Makefile via "make"  * Test the Makefile via `make`

Release Process for ''Cadence Releases''

This page describes the technical steps for releasing a Cadence Release (see: VersioningAndReleaseStrategy).

For how to do a plugins release: StepsForPluginRelease

For how to do a tools release (CLI / Plugman): StepsForToolsRelease

Getting Buy-in & Assigning a Release Master

  1. Email the dev mailing-list and see if anyone has reason to postpone the release.
    • If so, agree upon a branching date / time.
  2. Ask for a volunteer to be ReleaseMaster for the release (or volunteer yourself)

Creating JIRA issues

Create the release bug for the Release Candidate:

./cordova-coho/coho create-release-bug --version=3.0.0 --username=JiraUser --password=JiraPassword

This bug contains subtasks for each top-level step involved in creating a release. For each completed step, add a comment to the relevant JIRA issue.

Branch & Tag RC1 for: cordova-js, cordova-mobile-spec and cordova-app-hello-world

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

This step involves:

  • Updating version numbers
  • Creating release branches
  • Creating git tags

Coho automates these steps:

./cordova-coho/coho prepare-release-branch --version 2.8.0-rc1 -r js -r app-hello-world -r mobile-spec
./cordova-coho/coho repo-status -r js -r app-hello-world -r mobile-spec -b master -b 2.8.x
# If changes look right:
./cordova-coho/coho repo-push -r js -r app-hello-world -r mobile-spec -b master -b 2.8.x
./cordova-coho/coho tag-release --version 2.8.0-rc1 -r js -r app-hello-world -r mobile-spec

If the JS ever needs to be re-tagged, rerun the tag-release command, and then re-run the prepare-release-branch command for the platform repos.

Branch & Tag RC1 for 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 (if there were any changes to it)
    • This usually lives within bin/templates somewhere
    • TODO: More details needed here
  3. 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

This step involves:

  • Updating cordova.js snapshots
  • Updating version numbers
  • Creating release branches
  • Creating git tags

Coho automates these steps (replace android with your platform):

./cordova-coho/coho prepare-release-branch --version 2.8.0-rc1 -r android
./cordova-coho/coho repo-status -r android -b master -b 2.8.x
# If changes look right:
./cordova-coho/coho repo-push -r android -b master -b 2.8.x
./cordova-coho/coho tag-release --version 2.8.0-rc1 -r android

Tagging RC1 of cordova-cli

cordova-cli doesn't use a release branch. Follow the instructions at StepsForToolsRelease, but in addition:

  1. Run Apache RAT to ensure copyright headers are present

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

  2. Update the tool to point to the new repo versions (within cordova-cli/platforms.js)

  3. Instead of the normal npm publish flow:

  npm view cordova@latest dist-tags.latest > /tmp/cdvtag
  npm publish .
  npm tag cordova rc
  npm tag cordova@$(</tmp/cdvtag) latest
  rm /tmp/cdvtag

Testing & Documentation

Once all the repos are branched & tagged, 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

  • Test Project Upgrades (old-style):
    1. Create a project using the previous version of cordova
      • ./cordova-coho/coho foreach "git checkout 2.9.0"

      • ./cordova-coho/coho foreach -r active-platform "./bin/create foo org.apache.foo foo"

    2. Upgrade the project via the bin/update_project script:
      • ./cordova-coho/coho foreach "git checkout 3.0.x"

      • ./cordova-coho/coho foreach -r active-platform "cd foo && ../bin/update_project"

    3. Test the result:
      • Project should run
      • cordova/version should report the new version
  • Test Project Upgrades (new-style):
    1. Create a project using the previous version of cordova
      • ./cordova-coho/coho foreach "git checkout 2.9.0"

      • ./cordova-mobile-spec/createmobilespec.sh

    2. Upgrade the project via the update command:
      • ../cordova-cli/bin/cordova platform update PLATFORM

    3. Test the result:
      • Project should run
      • cordova/version should report the new version
      • Mobile Spec should still run.

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 the previous release until now.
      •           # Changes:
                  git log --pretty=format:'* %s' --topo-order --no-merges origin/RELEASE_BRANCH..master
                  # Commit count:
                  git log --pretty=format:'* %s' --topo-order --no-merges origin/RELEASE_BRANCH..master | wc -l
                  # Author Count:
                  git log --pretty=format:'%an' --topo-order --no-merges origin/RELEASE_BRANCH..master | sort | uniq | wc -l
    2. Edit the commit descriptions - don't add the commits verbatim, usually they are meaningless to the user. Only show the ones relevant for the user (fixes, new features)
  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

Final Tagging (non-RC)

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

Use the same coho commands as for the RCs (it will update JS & VERSION):

./cordova-coho/coho prepare-release-branch --version 2.8.0 -r js -r app-hello-world -r mobile-spec
./cordova-coho/coho repo-status -r js -r app-hello-world -r mobile-spec -b master -b 2.8.x
# If changes look right:
./cordova-coho/coho repo-push -r js -r app-hello-world -r mobile-spec -b master -b 2.8.x
./cordova-coho/coho tag-release --version 2.8.0 -r js -r app-hello-world -r mobile-spec

Branching & Tagging cordova-docs

  1. Cherry pick relevant 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.

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.
    • Check out the branch cordova-labs:redirect-docs-cordova-io

    • Repository README.md explains How to update the HTTP redirect

    • Nodejitsu is limited to one deployer, so Michael Brooks is currently the point of contact.

Push CLI to npm

Refer to StepsForToolsRelease

Tell JIRA it's Released

Announce It!

  1. Announce the release to the world!

Additional Information

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

Moving Tags

If you need to move a tag before the release, here is how to do that:

$ git tag -d 3.1.0
Deleted tag '3.1.0' (was 2a9bc20)
$ git push origin :refs/tags/3.1.0
To https://git-wip-us.apache.org/repos/asf/cordova-docs.git
 - [deleted]         3.1.0
$ git tag 3.1.0 7cf9fea03d7d02a13aef97a09a459e8128bd3198
$ git push origin 3.1.0
Total 0 (delta 0), reused 0 (delta 0)
To https://git-wip-us.apache.org/repos/asf/cordova-docs.git
 * [new tag]         3.1.0 -> 3.1.0

Then send a note to the mailing list:

To verify you have the updated tag in your local clone, doing a "git rev-parse 3.1.0" in cordova-docs should reply with "7cf9fea03d7d02a13aef97a09a459e8128bd3198". If it is wrong, do "git fetch --tags".

Official Apache 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.

Pre-3.0, official source releases were how end-users downloaded Cordova. Now that we use CLI, they are more for historical purposes and are done only for major releases.

A release contains:

 /
 |- 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

Uploading a Release

  1. Create the release .zip with coho:

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

./cordova-coho/coho upload-release --new-version 3.0.0 --prev-version 2.9.0

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