You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@cordova.apache.org by ag...@apache.org on 2014/03/05 22:01:32 UTC
git commit: Moved release process docs into COHO
Repository: cordova-coho
Updated Branches:
refs/heads/master f0612f21f -> 5279851ab
Moved release process docs into COHO
Project: http://git-wip-us.apache.org/repos/asf/cordova-coho/repo
Commit: http://git-wip-us.apache.org/repos/asf/cordova-coho/commit/5279851a
Tree: http://git-wip-us.apache.org/repos/asf/cordova-coho/tree/5279851a
Diff: http://git-wip-us.apache.org/repos/asf/cordova-coho/diff/5279851a
Branch: refs/heads/master
Commit: 5279851ab842438d6df3c72a0e48173c1a66a40b
Parents: f0612f2
Author: Andrew Grieve <ag...@chromium.org>
Authored: Wed Mar 5 16:01:02 2014 -0500
Committer: Andrew Grieve <ag...@chromium.org>
Committed: Wed Mar 5 16:01:02 2014 -0500
----------------------------------------------------------------------
docs/cadence-release-process.md | 290 +++++++++++++++++++++++++++
docs/plugins-release-process.md | 222 ++++++++++++++++++++
docs/storing-repo-versions-design.md | 95 +++++++++
docs/tools-release-process.md | 232 +++++++++++++++++++++
docs/versioning-and-release-strategy.md | 44 ++++
5 files changed, 883 insertions(+)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/cordova-coho/blob/5279851a/docs/cadence-release-process.md
----------------------------------------------------------------------
diff --git a/docs/cadence-release-process.md b/docs/cadence-release-process.md
new file mode 100644
index 0000000..a96573d
--- /dev/null
+++ b/docs/cadence-release-process.md
@@ -0,0 +1,290 @@
+# Release Process for ''Cadence Releases''
+
+Before cutting any releases, read the Apache's [Releases Policy](http://www.apache.org/dev/release)
+
+This page describes the technical steps for releasing a `Cadence Release` (see: [versioning-and-release-strategy.md](versioning-and-release-strategy.md)).
+
+## Getting Buy-in & Assigning a Release Manager
+
+ 1. Email the dev mailing-list and see if anyone has reason to postpone the release.
+ * If so, agree upon a branching date / time.
+ 1. Ask for a volunteer to be Release Manager 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](http://creadur.apache.org/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:
+ * Update [CordovaLib/Classes/CDVAvailability.h](https://github.com/apache/incubator-cordova-ios/blob/master/CordovaLib/Classes/CDVAvailability.h)
+ * Add a new macro for the new version, e.g.
+
+
+ #define __CORDOVA_2_1_0 20100
+
+
+* * * 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 [tools-release-process.md](tools-release-process.md), but in addition:
+
+Update the tool to point to the new repo versions (within `cordova-cli/platforms.js`)
+
+Instead of the normal `npm publish` flow:
+
+ npm publish --tag rc
+
+** WATCH OUT! You may have to run `npm tag cordova@x.x.x latest` due to a bug in npm: https://github.com/npm/npm/issues/4837
+
+## 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](http://git-wip-us.apache.org/repos/asf/cordova-mobile-spec.git)
+ * 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](https://github.com/apache/incubator-cordova-android/tree/master/test) directory
+
+#### iOS Extras
+
+ * Unit tests in: [CordovaLibTests/CordovaTests.xcodeproj](https://git-wip-us.apache.org/repos/asf?p=cordova-ios.git;a=tree;f=CordovaLibTests;h=88ba8e3c286159151b378efb1b0c39ef26dac550;hb=HEAD)
+ * Test the Makefile via `make`
+ * Run `bin/diagnose_project` on a newly created project and ensure it reports no errors.
+
+### 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]])
+ * Grab changes from the previous release until now.
+
+
+ # Changes:
+ git log --pretty=format:'* %s' --topo-order --no-merges origin/3.2.x..origin/3.3.x
+ # Commit count:
+ git log --pretty=format:'* %s' --topo-order --no-merges origin/3.2.x..origin/3.3.x | wc -l
+ # Author Count:
+ git log --pretty=format:'%an' --topo-order --no-merges origin/3.2.x..origin/3.3.x | sort | uniq | wc -l
+
+ * 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](http://docs.phonegap.com/en/edge/guide_upgrading_index.md.html) 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](https://git-wip-us.apache.org/repos/asf?p=cordova-docs.git;a=blob;f=README.md#l127) for more details.
+
+
+## Final Details
+
+### Update cordova.apache.org
+
+ * Refer to [this commit](http://svn.apache.org/viewvc?view=revision&revision=r1478146) (also includes updating the DOAP file)
+ * And the instructions at https://svn.apache.org/repos/asf/cordova/site/README.md
+
+### Update the Docs
+ 1. Upload the new docs to http://cordova.apache.org/docs
+ * Website README.md explains [How to update the docs](https://svn.apache.org/repos/asf/cordova/site/README.md)
+ * Commit should look like [this one](http://svn.apache.org/viewvc?view=revision&revision=r1478171)
+ 1. 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](https://github.com/apache/cordova-labs/tree/redirect-docs-cordova-io#usage)
+ * Nodejitsu is limited to one deployer, so Michael Brooks is currently the point of contact.
+
+### Push CLI to npm
+
+Refer to [tools-release-process.md](tools-release-process.md)
+
+### Tell JIRA it's Released
+
+ * Visit https://issues.apache.org/jira/plugins/servlet/project-config/CB/versions
+ * Fill in the Release Date field and mark it as released.
+
+### Announce It!
+ 1. Announce the release to the world!
+ * Create a blog post for it (instructions on [sites page README](https://svn.apache.org/repos/asf/cordova/site/README.md)
+ * Tweet it on https://twitter.com/apachecordova
+ * Announce to [G+ Page](https://plus.google.com/u/0/113178331525415522084/posts)
+
+
+# Additional Information
+ * [IOSReleaseChecklist](https://wiki.apache.org/cordova/IOSReleaseChecklist)
+ * [AndroidReleaseChecklist](https://wiki.apache.org/cordova/AndroidReleaseChecklist)
+
+## 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 --tags
+ 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
+
+Create the release .zip with coho:
+
+ ./cordova-coho/coho create-release-snapshot --prev-version 2.7.0 --new-version 2.8.0-rc1 -r release-repos
+
+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
+
+[Update the versions](https://wiki.apache.org/cordova/UpdatingVersionsOnTheCordovaWebsite) on the Cordova website
+
+
http://git-wip-us.apache.org/repos/asf/cordova-coho/blob/5279851a/docs/plugins-release-process.md
----------------------------------------------------------------------
diff --git a/docs/plugins-release-process.md b/docs/plugins-release-process.md
new file mode 100644
index 0000000..e09c92f
--- /dev/null
+++ b/docs/plugins-release-process.md
@@ -0,0 +1,222 @@
+# Release Process for ''Core Plugins''
+
+Before cutting any releases, read the Apache's [Releases Policy](http://www.apache.org/dev/release)
+
+Core Plugins are released at most weekly (see: [versioning-and-release-strategy.md](versioning-and-release-strategy.md)).
+
+A plugins release is performed by a single person each week. We call this person the "Release Manager". How to select the Release Manager is still TDB.
+
+TODO: add in RAT instruction (via coho) for next release
+
+TODO: Use perl instead of sed in these commands so they work on Linux.
+
+## Get Buy-in
+
+ 1. Email the dev mailing-list and see if anyone has reason to postpone the release.
+ * If so, agree upon a branching date / time.
+
+## Create JIRA issues
+
+ * Create a JIRA issue to track the status of the release.
+ * Make it of type "Task"
+ * Title should be "Plugins Release _Feb 2, 2014_"
+ * Description should be: "Following steps at https://github.com/apache/cordova-coho/blob/master/docs/plugins-release-process.md"
+ * Comments should be added to this bug after each top-level step below is taken
+ * Set a variable for use later on:
+
+
+ JIRA="CB-????" # Set this to the release bug.
+
+
+## Make sure you're up-to-date
+
+ # Update your repos
+ ./cordova-coho/coho repo-status -r plugins -b dev -b master
+ ./cordova-coho/coho repo-update -r plugins
+ ./cordova-coho/coho foreach -r plugins "git checkout dev"
+
+ # Merge any commits mistakenly made to master into dev:
+ (for l in cordova-plugin-*; do ( cd $l; git merge master ); done
+
+ # Sanity check and push if needed:
+ ./cordova-coho/coho repo-status -r plugins -b dev
+ ./cordova-coho/coho repo-push -r plugins -b dev
+
+## Identify which plugins have changes
+
+ ./cordova-coho/coho repo-update -r plugins
+ ./cordova-coho/coho foreach -r plugins "git checkout dev"
+ ACTIVE=$(for l in cordova-plugin-*; do ( cd $l; git log --pretty=format:'* %s' --topo-order --no-merges master..dev | grep -v "Incremented plugin version" > /dev/null && echo $l); done | xargs echo)
+
+## Ensure license headers are present everywhere:
+
+ ./cordova-coho/coho audit-license-headers -r plugins | less
+
+## Update RELEASENOTES.md & Version
+Remove the ''-dev'' suffix on the version in plugin.xml.
+
+ for l in $ACTIVE; do ( cd $l; v="$(grep version= plugin.xml | grep -v xml | head -n1 | cut -d'"' -f2)"; if [ $v = *-dev ); then v2="${v%-dev}"; echo "$l: Setting version to $v2"; sed -i '' -E s:"version=\"$v\":version=\"$v2\":" plugin.xml; fi) ; done
+
+If the changes merit it, manually bump the major / minor version instead of the micro. Manual process, but list the changes via:
+
+ for l in $ACTIVE; do ( cd $l; echo $l; git log --pretty=format:'* %s' --topo-order --no-merges master..dev | grep -v "Incremented plugin version" ); done
+
+Update its RELEASENOTES.md file with changes
+
+ # Add new heading to release notes with version and date
+ DATE=$(date "+%h %d, %Y")
+ for l in $ACTIVE; do ( cd $l; v="$(grep version= plugin.xml | grep -v xml | head -n1 | cut -d'"' -f2)"; echo -e "\n### $v ($DATE)" >> RELEASENOTES.md; git log --pretty=format:'* %s' --topo-order --no-merges master..dev | grep -v "Incremented plugin version" >> RELEASENOTES.md); done
+ # Then curate:
+ vim ${ACTIVE// //RELEASENOTES.md }/RELEASENOTES.md
+
+Add a comment to the JIRA issue with the output from:
+
+ for l in $ACTIVE; do ( cd $l; id="$(grep id= plugin.xml | grep -v xml | grep -v engine | grep -v param | head -1 | cut -d'"' -f2)"; v="$(grep version= plugin.xml | grep -v xml | head -n1 | cut -d'"' -f2)"; echo $id@$v; awk "{ if (p) print } /$DATE/ { p = 1 } " < RELEASENOTES.md; echo); done
+
+Commit these two changes together to the `dev` branch
+
+ for l in $ACTIVE; do ( cd $l; v="$(grep version= plugin.xml | grep -v xml | head -n1 | cut -d'"' -f2)"; git commit -am "$JIRA Updated version and RELEASENOTES.md for release $v"); done
+
+## Tag on Dev Branch
+
+ for l in $ACTIVE; do ( cd $l; v="r$(grep version= plugin.xml | grep -v xml | head -n1 | cut -d'"' -f2)"; echo "Tagging $l to $v"; git tag "$v" ); done
+
+## Update dev branch's version
+
+ for l in $ACTIVE; do ( cd $l; v="$(grep version= plugin.xml | grep -v xml | head -n1 | cut -d'"' -f2)"; if [ $v != *-dev ); then v2="$(echo $v|awk -F"." '{$NF+=1}{print $0RT}' OFS="." ORS="")-dev"; echo "$l: Setting version to $v2"; sed -i '' -E s:"version=\"$v\":version=\"$v2\":" plugin.xml; fi) ; done
+ for l in $ACTIVE; do (cd $l; git commit -am "$JIRA Incremented plugin version on dev branch." ); done
+
+## Test
+ * Create mobilespec using the old versions of plugins (by checking them out to the previous tag)
+ * Run through mobilespec, ensuring to do manual tests that relate to changes in the RELEASENOTES.md
+
+## Push Dev Branch
+ # Sanity check:
+ ./cordova-coho/coho repo-status -r plugins -b dev
+ # Push:
+ for l in $ACTIVE; do ( cd $l; git push --tags https://git-wip-us.apache.org/repos/asf/$l.git dev); done
+
+## Publish to dist/dev
+Ensure you have the svn repos checked out:
+
+ ./cordova-coho/coho repo-clone -r dist -r dist/dev
+
+Create archives from your tags:
+
+ ./cordova-coho/coho create-archive -r ${ACTIVE// / -r } --dest cordova-dist-dev/$JIRA
+
+Sanity Check:
+
+ # Manually double check version numbers are correct on the file names
+ # Then run:
+ ./cordova-coho/coho verify-archive cordova-dist-dev/$JIRA/*.zip
+
+Upload:
+
+ cd cordova-dist-dev && svn up && svn add $JIRA && svn commit -m "$JIRA Uploading release candidates for plugins release"
+
+* Find your release here: https://dist.apache.org/repos/dist/dev/cordova/
+
+## Prepare Blog Post
+ * Combine highlights from RELEASENOTES.md into a Release Announcement blog post
+ * Instructions on [sites page README](https://svn.apache.org/repos/asf/cordova/site/README.md)
+ * Get blog post proof-read.
+
+## Start VOTE Thread
+Send an email to dev ML with:
+
+__Subject:__
+
+ [Vote] Plugins Release
+
+__Body:__
+
+ Please review and vote on the release of this plugins release.
+
+ Release issue: https://issues.apache.org/jira/browse/CB-XXXX
+
+ The plugins have been published to dist/dev:
+ https://dist.apache.org/repos/dist/dev/cordova/CB-XXXX/
+
+ The packages were published from their corresponding git tags:
+ PASTE OUTPUT OF: ./cordova-coho/coho print-tags -r ${ACTIVE// / -r }
+
+ Upon a successful vote I will upload the archives to dist/, upload them to the Plugins Registry, and post the corresponding blog post.
+
+ Voting will go on for a minimum of 48 hours.
+
+ I vote +1.
+
+
+## Email the result of the vote
+Respond to the vote thread with:
+ * Note: list of PMC members: http://people.apache.org/committers-by-project.html#cordova-pmc
+
+
+ The vote has now closed. The results are:
+
+ Positive Binding Votes: (# of PMC members that +1'ed)
+
+ .. names of all +1 PMC members ..
+
+ Negative Binding Votes: (# of PMC members that -1'ed)
+
+ .. names of all -1 PMC members ..
+
+ The vote has passed.
+
+## If the Vote does *not* Pass
+* Revert adding of `-dev` on dev branch
+* Address the concerns (on dev branch)
+* Merge changes into master
+* Re-tag release using `git tag -f`
+* Add back `-dev`
+* Start a new vote
+
+## Otherwise: Merge & Push Master Branch
+
+ for l in $ACTIVE; do ( cd $l; git checkout master ); done
+ for l in $ACTIVE; do ( cd $l; v=$(git describe --tags --abbrev=0 dev); git merge $v ); done
+
+ # Sanity check:
+ ./cordova-coho/coho repo-status -r plugins -b master
+ # Push:
+ for l in $ACTIVE; do ( cd $l; git push --tags https://git-wip-us.apache.org/repos/asf/$l.git master); done
+
+
+## Publish to dist/
+
+ cd cordova-dist
+ svn up
+ for l in $ACTIVE; do ( svn rm plugins/$l* ); done
+ cp ../cordova-dist-dev/$JIRA/* plugins/
+ svn add plugins/*
+ svn commit -m "$JIRA Published plugins release to dist"
+
+ cd ../cordova-dist-dev
+ svn up
+ svn rm $JIRA
+ svn commit -m "$JIRA Removing release candidates from dist/dev"
+
+Find your release here: https://dist.apache.org/repos/dist/release/cordova/plugins/
+
+## Publish to Plugins Registry
+
+ for l in $ACTIVE; do ( cd $l; git checkout master ); done
+ for l in $ACTIVE; do ( cd $l; echo -n "$l: "; plugman publish . ); done
+
+## Post blog Post
+
+ rake build
+ svn st
+ svn add NEW_FILES_HERE
+ svn commit
+
+## Close JIRA Issue
+ * Double check that the issue has comments that record the steps you took
+ * Mark it as fixed
+
+## Finally:
+
+ * Update *these instructions* if they were missing anything.
+
http://git-wip-us.apache.org/repos/asf/cordova-coho/blob/5279851a/docs/storing-repo-versions-design.md
----------------------------------------------------------------------
diff --git a/docs/storing-repo-versions-design.md b/docs/storing-repo-versions-design.md
new file mode 100644
index 0000000..1dde279
--- /dev/null
+++ b/docs/storing-repo-versions-design.md
@@ -0,0 +1,95 @@
+# Storing Versions
+This section describes how we _store_ version numbers on our various repositories.
+
+## Cordova Platform Repositories
+There are two aspects of this:
+ 1. Storing the version for the repository
+ 2. Storing the version of the platform of a created project (as created by the `bin/create` script)
+
+For #1:
+ * We will continue to use a `VERSION` file at the root of the repository.
+
+For #2:
+ * There is already a way to report the version - through the `cordova/version` script of a created project.
+ * The logic of this script used to be different across platforms
+ * The new logic here is to have it echo a hard-coded string, which is the contents of the `VERSION` file at the time of creation.
+
+## Cordova JS
+There are two aspects of this:
+ 1. Storing the version for the repository
+ 2. Storing the version for within generated cordova.js files.
+
+For #1:
+ * We will continue to use a `VERSION` file at the root of the repository.
+
+For #2:
+ 1. Use build-time logic to stamp cordova.js files with a version through a variable at the top of the file.
+ 2. When built in the context of a git repo, and not at a tagged commit, append the git hash.
+ 3. When not in a git repo or at a tagged commit, don't try and append a hash.
+
+## Cordova Plugins
+Plugins store their version within their plugin.xml file. No `VERSION` files exist.
+
+## Plugman & CLI
+These tools are built as npm modules, and so use package.json. No `VERSION` files exist.
+
+
+# Choosing Version Numbers Based on Dev vs Release
+This section describes how we __choose version numbers for each branch within our various repositories.
+
+## Cordova Platform Repositories
+The version number should correspond closely to the git branch. When a release branch is made, both the branch and the master branch should be updated. The master branch should **always** have a version number ending in "-dev", which indicates the version currently being developed. A fresh release branch should change the version to an "-rc1" version, and then change to the unqualified version number when it is released.
+
+(This constant version number can be updated manually, but *should* eventually be updated via coho as release branches are made.)
+
+This should give a rough idea how the version number should advance:
+
+ 3.3.0-dev
+ 3.2.0-dev|
+ | |
+ --A---B---C---D (master)
+ \
+ \--E---F---G---H (3.2.x)
+ | | |
+ 3.2.0-rc1| 3.2.1-rc1
+ 3.2.0
+
+ * A: This is on the master branch, after 3.1.x has been branched, as 3.2 is being developed.
+ * B: This is the branch point for 3.2.x
+ * C: The first commit after 3.2.x is branched should identify the master branch as 3.3 is being developed on master now.
+ * E: The first commit on the 3.2.x branch should identify the branch as 3.2.0-rc1
+ * G: At some point, 3.2.0 is released, and should be identified as such
+ * H: After 3.2.0 is released, any further development can be called 3.2.1-rc1
+
+Current support:
+
+ ||'''Platform'''||'''Support'''||
+ ||Android || {*} ||
+ ||BB10 || {o} ||
+ ||iOS || {o} ||
+ ||OSX || {o} ||
+ ||QT || {o} ||
+ ||Tizen || {o} ||
+ ||WebOS || {o} ||
+ ||Win || {o} ||
+ ||WP7 || {o} ||
+ ||WP8 || {o} ||
+ ||www || {o} ||
+
+## Cordova JS
+cordova-js follows the same scheme as platforms.
+
+
+## Cordova Plugins
+Current state is that we have master & dev branches. This is because plugman pulls from master by default, so it must remain stable.
+
+ 1. Versions should stay be suffixed with "-dev" on the dev branch.
+ 2. This means a releases involves:
+ 1. Update plugin.xml's version to "3.1.0" on dev branch
+ 2. Merge dev -> master
+ 3. Update plugin.xml's version to "3.2.0-dev" on dev branch
+
+## Plugman & CLI
+cordova-plugman and cordova-cli follow the same scheme as platforms.
+
+
http://git-wip-us.apache.org/repos/asf/cordova-coho/blob/5279851a/docs/tools-release-process.md
----------------------------------------------------------------------
diff --git a/docs/tools-release-process.md b/docs/tools-release-process.md
new file mode 100644
index 0000000..c12bdc2
--- /dev/null
+++ b/docs/tools-release-process.md
@@ -0,0 +1,232 @@
+# Release Process for ''Plugman and CLI''
+
+Before cutting any releases, read the Apache's [Releases Policy](http://www.apache.org/dev/release)
+
+Plugman and CLI are released at most weekly (see: [versioning-and-release-strategy.md](versioning-and-release-strategy.md)).
+
+A tools release is performed by a single person each week. We call this person the "Release Manager". How to select the Release Manager is still TDB.
+
+TODO: add in RAT instruction (via coho) for next release
+
+TODO: use npm pack instead of git archive.
+
+TODO: Use perl instead of sed in these commands so they work on Linux.
+
+## Get Buy-in
+
+Email the dev mailing-list and see if anyone has reason to postpone the release.
+ * If so, agree upon a branching date / time.
+
+## Create JIRA issues
+
+ * Create a JIRA issue to track the status of the release.
+ * Make it of type "Task"
+ * Title should be "Tools Release _Feb 2, 2014_"
+ * Description should be: "Following steps at https://github.com/apache/cordova-coho/blob/master/docs/tools-release-process.md"
+ * Comments should be added to this bug after each top-level step below is taken
+ * Set a variable for use later on:
+
+
+ JIRA="CB-????" # Set this to the release bug.
+
+## Test
+Ensure license headers are present everywhere:
+
+ ./cordova-coho/coho audit-license-headers -r cli | less
+ ./cordova-coho/coho audit-license-headers -r plugman | less
+
+Ensure you're up-to-date:
+
+ ./cordova-coho/coho repo-update -r cli -r plugman
+ (cd cordova-plugman && npm install)
+ (cd cordova-cli && npm install)
+ (cd cordova-cli && npm install ../cordova-plugman)
+
+Ensure that mobilespec creates okay via CLI:
+
+ cordova-mobile-spec/createmobilespec.sh
+ (cd mobilespec && cordova run android)
+
+Ensure uninstall doesn't cause errors:
+
+ cordova plugin remove org.cordova.mobile-spec-dependencies
+
+Ensure that mobilespec creates okay via plugman:
+
+ cordova-mobile-spec/createmobilespecandroid-usingplugman.sh
+ (cd mobilespec-android && cordova/run)
+
+Ensure unit tests pass:
+
+ (cd cordova-plugman; npm test)
+ (cd cordova-cli; npm test)
+
+Add a comment to the JIRA issue stating what you tested, and what the results were.
+
+## Update Release Notes & Version
+
+Increase the version within package.json using SemVer, and remove the ''-dev'' suffix
+
+ for l in cordova-plugman cordova-cli; do ( cd $l; v="$(grep '"version"' package.json | cut -d'"' -f4)"; if [[ $v = *-dev ]]; then v2="${v%-dev}"; echo "$l: Setting version to $v2"; sed -i '' -E 's/version":.*/version": "'$v2'",/' package.json; fi) ; done
+
+If the changes merit it, manually bump the major / minor version instead of the micro. List the changes via:
+
+ ( cd cordova-plugman; git log --pretty=format:'* %s' --topo-order --no-merges $(git describe --tags --abbrev=0)..master | grep -v "Incremented plugin version" )
+
+
+ ( cd cordova-cli; git log --pretty=format:'* %s' --topo-order --no-merges $(git describe --tags --abbrev=0)..master | grep -v "Incremented plugin version" )
+
+
+Update each repo's RELEASENOTES.md file with changes
+
+ # Add new heading to release notes with version and date
+ DATE=$(date "+%h %d, %Y")
+ for l in cordova-plugman cordova-cli; do ( cd $l; v="$(grep '"version"' package.json | cut -d'"' -f4)"; echo -e "\n### $v ($DATE)" >> RELEASENOTES.md; git log --pretty=format:'* %s' --topo-order --no-merges $(git describe --tags --abbrev=0)..master | grep -v "Incremented plugin version" >> RELEASENOTES.md); done
+ # Then curate:
+ vim cordova-cli/RELEASENOTES.md cordova-plugman/RELEASENOTES.md
+
+Update the version of plugman that CLI depends on:
+
+ v="$(grep '"version"' cordova-plugman/package.json | cut -d'"' -f4)"
+ sed -i '' -E 's/"plugman":.*/"plugman": "'$v'",/' cordova-cli/package.json
+
+Commit these two changes together into one commit
+
+ for l in cordova-plugman cordova-cli; do ( cd $l; v="$(grep '"version"' package.json | cut -d'"' -f4)"; git commit -am "$JIRA Updated version and RELEASENOTES.md for release $v" ); done
+
+## Tag
+
+ # Review commits:
+ for l in cordova-plugman cordova-cli; do ( cd $l; git log -p origin/master..master ); done
+ # Tag
+ for l in cordova-plugman cordova-cli; do ( cd $l; v="$(grep '"version"' package.json | cut -d'"' -f4)"; git tag $v ); done
+
+## Re-introduce -dev suffix to versions
+
+ for l in cordova-plugman cordova-cli; do ( cd $l; v="$(grep '"version"' package.json | cut -d'"' -f4)"; if [[ $v != *-dev ]]; then v2="$(echo $v|awk -F"." '{$NF+=1}{print $0RT}' OFS="." ORS="")-dev"; echo "$l: Setting version to $v2"; sed -i '' -E 's/version":.*/version": "'$v2'",/' package.json; fi); done
+ for l in cordova-plugman cordova-cli; do (cd $l; git commit -am "$JIRA Incremented package version to -dev"; git show ); done
+
+
+## Push
+
+ # Push
+ for l in cordova-plugman cordova-cli; do ( cd $l; git push && git push --tags ); done
+
+If the push fails due to not being fully up-to-date, either:
+1. Pull in new changes via `git pull --rebase`, and include them in the release notes / re-tag
+2. Pull in new changes via `git pull`, and do *not* include them in the release.
+
+## Publish to dist/dev
+Ensure you have the svn repos checked out:
+
+ ./cordova-coho/coho repo-clone -r dist -r dist/dev
+
+Create archives from your tags:
+
+ ./cordova-coho/coho create-archive -r plugman -r cli --dest cordova-dist-dev/$JIRA
+
+Sanity Check:
+
+ ./cordova-coho/coho verify-archive cordova-dist-dev/$JIRA/*.zip
+
+Upload:
+
+ (cd cordova-dist-dev && svn add $JIRA && svn commit -m "$JIRA Uploading release candidates for tools release")
+
+Find your release here: https://dist.apache.org/repos/dist/dev/cordova/
+
+
+## Prepare Blog Post
+ * Combine highlights from RELEASENOTES.md into a Release Announcement blog post
+ * Instructions on [sites page README](https://svn.apache.org/repos/asf/cordova/site/README.md)
+ * Get blog post proofread.
+
+## Start VOTE Thread
+Send an email to dev ML with:
+
+__Subject:__
+
+ [Vote] Tools Release
+
+__Body:__
+
+ Please review and vote on this Tools Release.
+
+ Release issue: https://issues.apache.org/jira/browse/CB-XXXX
+
+ Both tools have been published to dist/dev:
+ https://dist.apache.org/repos/dist/dev/cordova/CB-XXXX/
+
+ The packages were published from their corresponding git tags:
+ PASTE OUTPUT OF: ./cordova-coho/coho print-tags -r plugman -r cli
+
+ Upon a successful vote I will upload the archives to dist/, publish them to NPM, and post the corresponding blog post.
+
+ Voting will go on for a minimum of 48 hours.
+
+ I vote +1.
+
+
+## Email the result of the vote
+Respond to the vote thread with:
+ * Note: list of PMC members: http://people.apache.org/committers-by-project.html#cordova-pmc
+
+
+ The vote has now closed. The results are:
+
+ Positive Binding Votes: (# of PMC members that +1'ed)
+
+ .. names of all +1 PMC members ..
+
+ Negative Binding Votes: (# of PMC members that -1'ed)
+
+ .. names of all -1 PMC members ..
+
+ The vote has passed.
+
+
+## If the Vote does *not* Pass
+* Revert adding of `-dev`
+* Address the concerns
+* Re-tag release using `git tag -f`
+* Add back `-dev`
+* Start a new vote
+
+## Otherwise: Publish to dist/
+
+ cd cordova-dist
+ svn up
+ svn rm tools/*
+ cp ../cordova-dist-dev/$JIRA/* tools/
+ svn add tools/*
+ svn commit -m "$JIRA Published tools release to dist"
+
+ cd ../cordova-dist-dev
+ svn up
+ svn rm $JIRA
+ svn commit -m "$JIRA Removing release candidates from dist/dev"
+
+
+Find your release here: https://dist.apache.org/repos/dist/release/cordova/tools
+
+## Publish to NPM
+
+ npm publish cordova-cli
+ npm publish plugman
+
+
+## Post Blog Post
+
+ cd cordova-website
+ rake build
+ svn commit -m "$JIRA Published blog post for tools release."
+
+
+## Close JIRA Issue
+ * Double check that the issue has comments that record the steps you took
+ * Mark it as fixed
+
+## Finally:
+
+ * Update *these instructions* if they were missing anything.
+
http://git-wip-us.apache.org/repos/asf/cordova-coho/blob/5279851a/docs/versioning-and-release-strategy.md
----------------------------------------------------------------------
diff --git a/docs/versioning-and-release-strategy.md b/docs/versioning-and-release-strategy.md
new file mode 100644
index 0000000..e1ce1c9
--- /dev/null
+++ b/docs/versioning-and-release-strategy.md
@@ -0,0 +1,44 @@
+# Versioning and Release Strategy
+
+## Versioning Strategies
+ 1. `SemVer` ([Semantic Version](http://www.semver.org))
+ * Used by platforms, plugman, CLI, core plugins
+ * Is important when describing dependencies in a sane way (e.g. within plugin.xml files)
+ * Referenced sparingly by docs / blogs (e.g. only by release notes)
+ 2. `CadVer` (Cadence Version)
+ * Used by CLI, mobile-spec, cordova-js
+ * Also referred to as the "Cordova Version"
+ * Referenced by our website, blogs & docs
+ * Used by JIRA for the "Fix Version" field
+ * Each `CadVer` maps to a set of repo `SemVer`s
+ * E.g. 3.0.0 uses `cordova-blackberry@3.0.0, cordova-ios@3.0.0, cordova-android@3.0.0`
+ * E.g. 3.1.0 uses `cordova-blackberry@3.1.0, cordova-ios@3.0.1, cordova-android@4.0.0`
+ * E.g. 3.2.0 uses `cordova-blackberry@3.1.1, cordova-ios@3.1.0, cordova-android@4.0.1`
+ * E.g. 3.2.1 uses `cordova-blackberry@3.1.2, cordova-ios@3.1.0, cordova-android@4.0.1`
+
+CLI exists in both lists because its version has the format: `CadVer-SemVer`
+ * E.g.: `3.0.0-0.5.1`
+
+
+## Release Strategies
+ 1. __On-Demand Releases__
+ * Any repository can do an on-demand release at any time.
+ * These happen only when the team decides that a release cannot wait for the next regular release to happen.
+ * These releases contain critical bug fixes that can't wait for the next scheduled release.
+ 2. __Weekly Releases__
+ * These occur at most once a week (if there are no commits worth releasing, then skip the release).
+ * Rationale: Reduces the number of releases to at most one per week so that users are not annoyed by having to update too frequently.
+ * Rationale: Reduces the number of blog posts and release notes to write.
+ * These releases apply to: `CLI`, `Plugman`, and `Core Plugins`.
+ * These releases contain non-critical bug fixes as well as new features.
+ * Releases generally happen on Thursdays, but can be done on any day so long as it's been a week since the previous release.
+ 3. __Cadence Releases__
+ * These follow the 10 releases per year, as enumerated on RoadmapProjects.
+ * The `CadVer` is increased (either MAJOR or MINOR) on each release.
+ * The `SemVer` is increased only if there are changes since the previous release.
+
+Related docs:
+* [storing-repo-versions-design.md](storing-repo-versions-design.md)
+* [cadence-release-process.md](cadence-release-process.md)
+* [CommitterWorkflow](https://wiki.apache.org/cordova/CommitterWorkflow)
+