Mailing-List: contact commits-help@cordova.apache.org; run by ezmlm
Precedence: bulk
Reply-To: dev@cordova.apache.org
MIME-Version: 1.0
Content-Type: text/plain; charset="utf-8"
Content-Transfer-Encoding: quoted-printable
From: Apache Wiki <wikidiffs@apache.org>
To: Apache Wiki <wikidiffs@apache.org>
Date: Fri, 30 Aug 2013 20:50:18 -0000
Message-ID: <20130830205018.64683.35456@eos.apache.org>
Subject: 
 =?utf-8?q?=5BCordova_Wiki=5D_Update_of_=22CuttingReleases=22_by_AndrewGri?=
 =?utf-8?q?eve?=
Auto-Submitted: auto-generated

Dear Wiki user,

You have subscribed to a wiki page or wiki category on "Cordova Wiki" for c=
hange notification.

The "CuttingReleases" page has been changed by AndrewGrieve:
https://wiki.apache.org/cordova/CuttingReleases?action=3Ddiff&rev1=3D50&rev=
2=3D51

  =3D Apache Cordova Releases =3D
  =

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

+ This page describes the technical steps for releasing. For the versioning=
 & frequency of releases, see: VersioningAndReleaseStrategy.
  =

- {{{
- =

-  /
-  |- KEYS .................................. signing keys
-  |- cordova-VERSION-src.zip ............... zip file that contains the sr=
c of all platform repos
-  |- .md5 .................................. md5 file containing the MD5 C=
hecksum of the src zip
-  |- .sha .................................. sha file containing the SHA H=
ash of the src zip
-  |- .asc .................................. asc file that contains the AS=
CII 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 con=
cerning licences, notices, disclaimer, and as well the readme for the Apach=
e 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
- =

- =

- }}}
- =

- =3D=3D Release Philosophy =3D=3D
- =

- 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) philosoph=
y, 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. Eac=
h 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 resu=
lt our community worked off the edge, making issue tracking very difficult,=
 cascading into a host of predicability and reliability issues, jeopardizin=
g the community. In 2009, when IBM joined the effort with Nitobi, we starte=
d releasing once a month, rolling issues over to the next minor.
- =

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

- =

- =3D Release Process =3D
+ =3D Cadence Release Process =3D
  =

  =3D=3D Getting Buy-in =3D=3D
  =

+  1. Email the dev mailing-list and see if anyone has reason to postpone t=
he release.
-  1. Email the dev mailing-list and see if anyone else is interested in cu=
tting a release. =

-  1. See if there are any changes people are waiting to get in for the rel=
ease. =

-  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.
+    * If so, agree upon a branching date / time.
  =

  =3D=3D Creating JIRA issues =3D=3D
  =

- TODO: Enhance coho tool to take care of JIRA tasks. There is sample code =
under the cordova-labs/jira repo/branch.
+ Create the release bug for the Release Candidate:
  =

- For now, create the release bugs by cloning [[https://issues.apache.org/j=
ira/browse/CB-3464|CB-3464]].
+ {{{#!bash
+ ./cordova-coho/coho create-release-bug --version=3D3.0.0-rc1 --username=
=3DJiraUser --password=3DJiraPassword
+ }}}
  =

- =3D=3D Branching & Tagging cordova-js, cordova-mobile-spec and cordova-ap=
p-hello-world =3D=3D
+ =3D=3D Branch & Tag cordova-js, cordova-mobile-spec and cordova-app-hello=
-world =3D=3D
  =

- This should be done *before* creating branches on other repos
+ 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:
+ =

  {{{#!bash
- ./cordova-coho/coho prepare-release-branch --version 2.8.0rc1 -r js -r ap=
p-hello-world -r mobile-spec
+ ./cordova-coho/coho prepare-release-branch --version 2.8.0-rc1 -r js -r a=
pp-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.0rc1 -r js -r app-hello-wor=
ld -r mobile-spec
+ ./cordova-coho/coho tag-release --version 2.8.0-rc1 -r js -r app-hello-wo=
rld -r mobile-spec
  }}}
  =

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

- =3D=3D Branching Platform Repositories =3D=3D
+ =3D=3D Branching & Tagging Platform Repositories =3D=3D
  =

  =3D=3D=3D Before creating the release branch: =3D=3D=3D
  =

   1. Run [[http://creadur.apache.org/rat/ | Apache RAT]] to ensure copyrig=
ht headers are present
     * `./cordova-coho/coho audit-license-headers -r android | less`
-  1. Update the copy of app-hello-world
+  1. 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
-  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/mast=
er/CordovaLib/Classes/CDVAvailability.h |CordovaLib/Classes/CDVAvailability=
.h]]
          i. add a new macro for the new version, e.g.
@@ -101, +64 @@

  =

  =3D=3D=3D Creating the release branch =3D=3D=3D
  =

- The coho tool creates the release branches, update VERSION files, and upd=
ate the cordova.js snapshot:
+ 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):
+ =

  {{{#!bash
- ./cordova-coho/coho prepare-release-branch --version 2.8.0rc1 -r active
+ ./cordova-coho/coho prepare-release-branch --version 2.8.0-rc1 -r android
- ./cordova-coho/coho repo-status -r active -b master -b 2.8.x
+ ./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
+ }}}
+ =

+ =3D=3D Branching & Tagging cordova-cli =3D=3D
+ =

+ =3D=3D=3D Before creating the release branch: =3D=3D=3D
+ =

+  1. Run [[http://creadur.apache.org/rat/ | Apache RAT]] to ensure copyrig=
ht headers are present
+    * `./cordova-coho/coho audit-license-headers -r android | less`
+  1. Update the tool to look for new version (TODO how?)
+ =

+ =3D=3D=3D Creating the release branch =3D=3D=3D
+ =

+ This step involves:
+  * Updating version numbers
+  * Creating release branches
+  * Creating git tags
+ =

+ Coho automates these steps:
+ =

+ {{{#!bash
+ ./cordova-coho/coho prepare-release-branch --version 2.8.0-0.5.4-rc1 -r c=
li
+ ./cordova-coho/coho repo-status -r cli -b master -b 2.8.x
+ # If changes look right:
- ./cordova-coho/coho repo-push -r active -b master -b 2.8.x
+ ./cordova-coho/coho repo-push -r cli -b master -b 2.8.x
  }}}
  =

  =3D=3D Testing & Documentation =3D=3D
  =

- Once all the repos are branched, we focus on testing & fixing all of the =
regressions we find.
+ Once all the repos are branched & tagged, we focus on testing & fixing al=
l of the regressions we find.
  =

  When a regression is found:
  =

@@ -137, +132 @@

     * 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 throu=
gh 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
+  * 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 upgrade-project`
+    3. Test the result:
+      * Project should run
+      * cordova/version should report the new version
+      * Mobile Spec should still run.
  =

  =3D=3D=3D=3D Android Extras =3D=3D=3D=3D
  =

@@ -173, +182 @@

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

  {{{#!bash
- ./cordova-coho/coho tag-release --version 2.8.0rc1 -r $REPO_NAME
+ ./cordova-coho/coho tag-release --version 2.8.0-rc1 -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 thro=
ugh all of the release steps above again). $REPO_NAME is usually the repo n=
ame without the "cordova-" prefix, to list the available repo names, run:
- =

- {{{#!bash
- ./cordova-coho/coho list-repos
  }}}
  =

  =

@@ -192, +195 @@

  =

   =

  =

- See [[https://git-wip-us.apache.org/repos/asf?p=3Dcordova-docs.git;a=3Dbl=
ob;f=3DREADME.md;h=3D7ff1ece1fc363cbed0e5120f3141f7094f92cfd5;hb=3DHEAD#l12=
7|Generating a Version Release]] for more details.
+ See [[https://git-wip-us.apache.org/repos/asf?p=3Dcordova-docs.git;a=3Dbl=
ob;f=3DREADME.md#l127|Generating a Version Release]] for more details.
  =

- =

- =3D=3D Uploading a Release Candidate =3D=3D
- =

-  1. Create the release .zip with coho:
- {{{#!bash
- ./cordova-coho/coho create-release-snapshot --prev-version 2.7.0 --new-ve=
rsion 2.8.0rc1
- }}}
-  1. Upload it to: https://dist.apache.org/repos/dist/release/cordova/
- TODO: COHO tool should do this step.
  =

  =3D=3D Final Details =3D=3D
  =

@@ -226, +220 @@

   * Fill in the Release Date field and mark it as released.
  =

  =3D=3D=3D Announce It! =3D=3D=3D
-  1. Be sure to wait 24 hours after uploading the release before announcin=
g in order to let the Apache mirrors pick up the file. Be aware that our li=
nks to the src zip is only to the mirrors, so this waiting step is not opti=
onal.
   1. Announce the release to the world!
-    * post to announce@apache.org
+    * Create a blog post for it (instructions on [[https://svn.apache.org/=
repos/asf/cordova/site/README.md|sites page README]])
     * Tweet it on https://twitter.com/apachecordova
-    * TODO: Through what additional channels?
+    * Announce to [[G+ Page|https://plus.google.com/u/0/113178331525415522=
084/posts]]
  =

  =

  =3D Additional Information =3D
- =

-  * Make sure the CLI tools (cordova-cli) work with the release. If a plat=
form has modified structure or contents of platform-specific files, especia=
lly 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]]
  =

  More information for release engineers can be found at [[http://www.apach=
e.org/dev/release]].
  =

+ =3D Official Apache Releases =3D
+ =

+ An official source release contains the source code for the repositories =
of the Apache Cordova platform, the signing keys and various checks to prov=
e 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 onl=
y for major releases.
+ =

+ A release contains:
+ =

+ {{{
+ =

+  /
+  |- KEYS .................................. signing keys
+  |- cordova-VERSION-src.zip ............... zip file that contains the sr=
c of all platform repos
+  |- .md5 .................................. md5 file containing the MD5 C=
hecksum of the src zip
+  |- .sha .................................. sha file containing the SHA H=
ash of the src zip
+  |- .asc .................................. asc file that contains the AS=
CII 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 con=
cerning licences, notices, disclaimer, and as well the readme for the Apach=
e 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
+ =

+ =

+ }}}
+ =

+ =

+ =3D=3D Uploading a Release =3D=3D
+ =

+  1. Create the release .zip with coho:
+ {{{#!bash
+ ./cordova-coho/coho create-release-snapshot --prev-version 2.7.0 --new-ve=
rsion 2.8.0-rc1
+ }}}
+  1. Upload it to: https://dist.apache.org/repos/dist/release/cordova/
+ {{{#!bash
+ ./cordova-coho/coho upload-release --new-version 3.0.0 --prev-version 2.9=
.0
+ }}}
+=20