Dear Wiki user, You have subscribed to a wiki page or wiki category on "Cordova Wiki" for change notification.
The "CuttingReleases" page has been changed by AndrewGrieve: http://wiki.apache.org/cordova/CuttingReleases?action=diff&rev1=28&rev2=29 / |-changelog |-DISCLAIMER - |-cordova-android.zip + |-cordova-$PLATFORM.zip (per platform) |-cordova-app-hello-world.zip - |-cordova-bada.zip - |-cordova-bada-wac.zip - |-cordova-blackberry-webworks.zip |-cordova-docs.zip |-cordova-js.zip - |-cordova-ios.zip - |-cordova-mac.zip |-cordova-mobile-spec.zip - |-cordova-qt.zip - |-cordova-tizen.zip - |-cordova-webos.zip - |-cordova-windows.zip - |-cordova-wp7.zip - |-cordova-wp8.zip |-LICENSE |-NOTICE |-README.MD @@ -45, +34 @@ }}} - == Steps to Cut a Apache Cordova Release == + == 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. + 1. See if there are any changes people are waiting to get in for the release. + 1. Review JIRA issues that are marked as "Fix For" this release. + * Any issues that don't need fixes, bump to the next release. + 1. Agree upon a branching date / time. + + == Creating JIRA issues == + - 0. To keep track of tagging progress and create JIRA issues for each component of a Cordova release, use the [[https://git-wip-us.apache.org/repos/asf?p=cordova-labs.git;a=shortlog;h=refs/heads/jira|JIRA node.js scripts]] (under cordova-labs / jira branch). + To keep track of tagging progress and create JIRA issues for each component of a Cordova release, use the [[https://git-wip-us.apache.org/repos/asf?p=cordova-labs.git;a=shortlog;h=refs/heads/jira|JIRA node.js scripts]] (under cordova-labs / jira branch). - 1. Fix all of the created issues (starting with branching & tagging Cordova-JS - see below) - 1. Prepare the release candidate using coho. Put online for others to access and download. + + == Branching & Tagging cordova-js and cordova-app-hello-world == + + This should be done *before* creating branches on other repos + + === Steps for cordova-js === + + 1. Create a branch: + {{{#!bash + git checkout master + git fetch --tags + git pull + git checkout -b 2.7.x + }}} + 1. Update VERSION: + {{{#!bash + echo "2.7.0rc1" > VERSION + jake + git commit -am 'Set VERSION to 2.7.0rc1' + }}} + 1. Tag & Push + {{{#!bash + git tag 2.7.0rc1 + git push --tags origin 2.7.x + }}} + + === Steps for cordova-app-hello-world === + + 1. Create a branch: + {{{#!bash + git checkout master + git fetch --tags + git pull + git checkout -b 2.7.x + }}} + 1. Update VERSION: + {{{#!bash + 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' + }}} + 1. Tag & Push + {{{#!bash + git tag 2.7.0rc1 + git push --tags origin 2.7.x + }}} + + == Branching Platform Repositories == + + === Before creating the release branch: === + + 1. Update the cordova.js snapshot: + * Android: + {{{#!bash + cp ../cordova-js/pkg/cordova.android.js framework/assets/js/cordova.android.js + }}} + * iOS: + {{{#!bash + cp ../cordova-js/pkg/cordova.ios.js CordovaLib/cordova.ios.js + }}} + 1. Update the copy of app-hello-world + * This usually lives within bin/templates somewhere + * TODO: More details needed here + 1. Remove things that were deprecated and slated for removal + * These are mostly tracked in the DeprecationPolicy page. + 1. For iOS only: + a. Update [[https://github.com/apache/incubator-cordova-ios/blob/master/CordovaLib/Classes/CDVAvailability.h |CordovaLib/Classes/CDVAvailability.h]] + i. add a new macro for the new version, e.g. + {{{#!c + #define __CORDOVA_2_1_0 20100 + }}} + i. update CORDOVA_VERSION_MIN_REQUIRED with the latest version macro, e.g. + {{{#!c + #ifndef CORDOVA_VERSION_MIN_REQUIRED + #define CORDOVA_VERSION_MIN_REQUIRED __CORDOVA_2_1_0 + #endif + }}} + + === Creating the release branch === + + {{{#!bash + 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: + {{{#!bash + echo "2.7.0rc1" > VERSION + sed -i '' -e 's:VERSION.*=.*;:VERSION="2.7.0rc1":' cordova.js + }}} + + ==== Steps for cordova-android ==== + + 1. On release branch: + {{{#!bash + 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: + + * Create a JIRA issue for it, and mark it as a blocker. + + To submit a fix: + + {{{#!bash + git checkout master + git commit -am 'Your commit message' + git push origin master + git checkout 2.7.x + git cherry-pick -x master + git push origin 2.7.x + }}} + + === What to Test === + + * Run [[http://git-wip-us.apache.org/repos/asf/incubator-cordova-mobile-spec.git | 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 + * Run each platform's ./bin/create script + * Ensure generated project builds & runs both through an IDE and through the cordova/* scripts + + ==== Android Extras ==== + + * Unit tests in: [[https://github.com/apache/incubator-cordova-android/tree/master/test | test]] directory + + ==== iOS Extras ==== + + * Unit tests in: [[https://git-wip-us.apache.org/repos/asf?p=cordova-ios.git;a=tree;f=CordovaLibTests;h=88ba8e3c286159151b378efb1b0c39ef26dac550;hb=HEAD|CordovaLibTests/CordovaTests.xcodeproj]] + * Test the Makefile via "make" + + === Documentation To Update === + + For each repository: + 1. Update RELEASENOTES.md (if the file is missing, use the iOS one as a reference: [[https://github.com/apache/cordova-ios/blob/master/RELEASENOTES.md | RELEASENOTES.md]]) + a. 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): + {{{#!bash + git shortlog --no-merges Foo..HEAD + }}} + a. 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) + a. Put the edited logs into a new section for the new version with a date (YYYYMMDD) in parentheses, and follow the previous formats + 1. Update README.md (if necessary) + 1. Ensure the [[http://docs.phonegap.com/en/edge/guide_upgrading_index.md.html | Upgrade Guide]] for your platform is up-to-date + 1. 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. + + {{{#!bash + git tag 2.7.0rc1 + git push --tags origin 2.7.x + }}} + + If for some reason a tag must be altered: + + {{{#!bash + 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. + 1. Branch & tag it in the same was as the other repos. + + See [[https://git-wip-us.apache.org/repos/asf?p=cordova-docs.git;a=blob;f=README.md;h=7ff1ece1fc363cbed0e5120f3141f7094f92cfd5;hb=HEAD#l127|Generating a Version Release]] for more details. + + + == Uploading a Release Candidate == + + 1. Use the [[https://git-wip-us.apache.org/repos/asf?p=cordova-coho.git|coho]] script to create the .zip file for the release candidate. + 1. 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/%[email protected]%3e for good examples. 1. 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. 1. A majority of at least three +1 votes from the (P)PMC is needed for the vote to pass. - 1. Make the approved release available at http://www.apache.org/dist/incubator/cordova/ ( also see https://dist.apache.org/repos/dist/release/cordova/ ) and update the project website cordova.apache.org to point to the new release. + 1. Make the approved release available at http://www.apache.org/dist/incubator/cordova/ ( also see https://dist.apache.org/repos/dist/release/cordova/ ) - 1. Upload the new docs to http://cordova.apache.org/docs, and update the project website (cordova.apache.org) to link to this latest version of the docs. + * TODO: How to do this? + 1. Upload the new docs to http://cordova.apache.org/docs + * Website README.md explains [[https://svn.apache.org/repos/asf/cordova/site/README.md|How to update the docs]] + 1. Update the project website cordova.apache.org to point to the new release & new docs + * Via UpdatingTheWebsite 1. 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. - * Website README.md explains [[https://svn.apache.org/repos/asf/cordova/site/README.md|How to update the docs]] - * Website README.md explains [[https://svn.apache.org/repos/asf/cordova/site/README.md|How to compile the site]] 1. Announce the release to the world! + * TODO: Through what channels? - == Release Philosophy == + = Additional Information = - 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.) - - - === Branching & Tagging Cordova-JS === - {{{ - git checkout master - git fetch --tags - git pull - git checkout -b 2.7.x - echo "2.7.0" > VERSION - jake - git commit -am 'Set VERSION to 2.7.0' - git tag 2.7.0rc1 - git push --tags apache 2.7.x - }}} - - === Tagging === - - When going through the tagging process, sometimes bugs are found and fixed before the release candidate is even created. In this case, it's fine to change the tags via: - {{{ - git tag --force 2.7.0rc1 - git push apache --tag - }}} - - Once a release is created though (meaning a .zip file has been uploaded), tags should not be changed. - - Tagging subsequent release-candidates: - {{{ - git checkout 2.7.x - git pull apache 2.7.x - git tag 2.7.0rc2 - git push apache --tag - }}} - - - - ==== Tagging cordova-docs ==== - - See the {{{README}}} section [[https://git-wip-us.apache.org/repos/asf?p=cordova-docs.git;a=blob;f=README.md;h=7ff1ece1fc363cbed0e5120f3141f7094f92cfd5;hb=HEAD#l127|Generating a Version Release]]. - - === Release Checklists === * 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. * [[IOSReleaseChecklist | iOS Release Checklist]] * [[AndroidReleaseChecklist | Android Release Checklist]] - == Additional Information == - More information for release engineers can be found at [[http://www.apache.org/dev/release]].
