This page describes the technical steps for doing a Platforms Release
.
It describes the following steps:
dist/dev
(Yes this list is long and scary, but represents the content below)
Android
with the platform you are releasing in the instructions below.You should have your platform repository checked out in a folder where you also have checked out all/most/some of the other Cordova repositories. If you followed the Cloning/Updating Cordova repositories instructions of cordova-coho
, this should already be the case.
Read through the Apache Releases Policy as stated above.
Email the dev mailing-list at dev@cordova.apache.org and see if anyone has reason to postpone the release.
E.g.:
Subject: [DISCUSS] Cordova-Android Release Does anyone have any reason to delay a cordova-_android_ platform release? Any outstanding patches to land? If not, I will start the release tomorrow.
Double check you replace “Android” in the subject and mail body - there is no undo for emails.
Note that it would be possible to continue with some of the Before Release items while waiting for a possible response.
Ensure that the latest version of npm is installed (using a command such as npm i npm@latest
), package-lock.json
is present (do npm i --package-lock-only
if needed), and then check:
(cd cordova-android && npm audit)
Ensure your checkout of the repository is up-to-date:
coho repo-update -r android
See if any dependencies are outdated
(cd cordova-android && npm outdated --depth=0)
(The --depth=0
prevents from listing dependencies of dependencies.)
Alternative 1:
dependencies
section of package.json
.Alternative 2:
Within a new JIRA issue: update any outdated dependencies in the project's package.json
file. Be sure to run through the test section below for compatibility issues.
Ensure license headers are present everywhere. For reference, see this background. Expect some noise in the output, for example some files from test fixtures will show up.
coho audit-license-headers -r android | less
Ensure all dependencies and subdependencies have Apache-compatible licenses.
coho check-license -r android
After waiting for any possible objections from the email sent according to the Request buy-in section above:
JIRA="CB-????" # Set this to the release bug.
Preparation of the release includes a) handling version numbers, b) creating nice release notes and c) creating the release branch.
package.json
This should be automatically done by the coho prepare-platform-release-branch
command as described in Create Release Branch section below.
-dev
suffix from versionThis command removes -dev
from the version
entry in package.json
:
for l in cordova-android; 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
Note: This command doesn't actually work. You can also replace -dev
in package.json
manually of course.
If the changes merit it, also manually bump the major / minor/ patch version in package.json
.
To decide if this release merits it, view the changes via:
( cd cordova-android && git log --pretty=format:'* %s' --topo-order --no-merges $(git describe --tags $(git rev-list --tags --max-count=1))..master )
Note: This command doesn't work on Windows command line. But you can look at the changes since the last tag manually (or via the next step).
Update the repos RELEASENOTES.md
file with changes since the last release.
coho update-release-notes -r android
(--from-tag
and/or --to-tag
may be needed in case of non-master branch)
Then curate:
vim cordova-android/RELEASENOTES.md
or use your favorite text editor manually.
Commit these changes together in a single commit (one commit).
(cd cordova-android && v="$(grep '"version"' package.json | cut -d'"' -f4)" && git commit -am "$JIRA Update RELEASENOTES & version for release $v")
(Should be “$JIRA Update RELEASENOTES.md for release $v” in case version
is not yet updated in package.json
.)
If you have prepared the release notes in your release branch for a patch release, you will have to cherry-pick the RELEASENOTES only into your master branch as well (stage only the appropriate chunk).
git checkout master git checkout -p RELEASENOTES_COMMIT_SHA_HASH
For iOS, you may have to cherry-pick the commit for Added X.Y.Z to CDVAvailability.h (via coho)
into the master branch as well.
If you are releasing new commits from an already-existing release branch, remember to merge in or cherry-pick relevant commits from master into the release branch!
Create and prepare your release branch by using coho prepare-platform-release-branch
command, which handles the following steps:
5.0.x
(if it doesn't already exist)cordova.js
snapshot on both 5.0.x
and master
--version
argument (or from package.json
if there is no --version
argument) to all other files (VERSION
and similar [e.g. build.gradle
for Android]) on the release branch 5.0.x
master
for future development already: It gives version (package.json
, VERSION
and similar) a minor bump and adds -dev
(=> 5.1.0-dev
) againRun the following command (make sure to replace the version below with what is listed inside package.json
).
coho prepare-platform-release-branch --version 5.0.0 -r android
Then ensure commits look okay on both branches
coho repo-status -r android -b master -b 5.0.x
Once all the repos are branched, we focus on testing & fixing all of the regressions we find.
Ensure that npm test
succeeds locally.
Ensure that the continuous build, which checks the status of npm test
, is green on GitHub.
cordova-mobile-spec
projectCreate and run a mobile-spec project:
./cordova-mobile-spec/createmobilespec/createmobilespec.js --android --forceplugins (cd mobilespec && cordova run android --device) (cd mobilespec && cordova run android --emulator)
This should start a black-ish app with a “Plugin tests” button. When clicking it you end up in a screen with “Auto Tests” and “Manual Tests” buttons. You should run both and see if all/most/the expected ones succeed.
cordova
CLICreate a hello world app using the cordova
CLI:
cordova create ./androidTest org.apache.cordova.test androidTest (cd androidTest && cordova platform add ../cordova-android) (cd androidTest && cordova run android --device) (cd androidTest && cordova run android --emulator)
This should create an app showing the Cordova logo, “Apache Cordova” and a green “Device is ready” box.
/bin
scriptsRun your platform's ./bin/create
script and run the resulting project:
./cordova-android/bin/create ./androidTest2 org.apache.cordova.test2 androidTest2 (cd androidTest2 && ./cordova/build) (cd androidTest2 && ./cordova/run --device) (cd androidTest2 && ./cordova/run --emulator)
This should create an app showing a white screen. Ensure the generated project files also build through an IDE.
The output from ./cordova/version
should show the new version you defined above.
cordova-lib
testsRun cordova-lib tests.
(cd cordova-lib/cordova-lib && npm test)
Clean up the project(s) you just created.
rm -rf androidTest*
Create a JIRA issue for it, and mark it as a blocker.
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 5.0.x git cherry-pick -x commit_hash # git push origin 5.0.x
Attention: This is the moment of truth: The following actions will push your work to the remote repository. Until now you only worked locally and could just delete everything if something went wrong. From here on this will get more difficult.
All good? Have another look at the changes:
coho repo-status -r android -b master -b 5.0.x
If changes look right:
coho repo-push -r android -b master -b 5.0.x
This pushes the commits in both master
and 5.0.x
(the release branch) to the remote.
Before you tag, run this command:
coho tag-platform-release --version 5.0.0 -r android --pretend
Seems okay? Then execute it by running:
coho tag-platform-release --version 5.0.0 -r android
This command also tags cordova-js
with android-5.0.0
and pushes it.
dist/dev
Attention: The following steps need SVN installed and unfortunately don't give an error if it is not, failing silently. You also need do have a secret key set up for signing the release.
Ensure you have the svn repos checked out:
coho repo-clone -r dist -r dist/dev
Create archives from your tags:
coho create-archive -r android --dest cordova-dist-dev/$JIRA --tag 5.0.0
Sanity Check:
coho verify-archive cordova-dist-dev/$JIRA/*.tgz
Upload:
(cd cordova-dist-dev && svn add $JIRA && svn commit -m "$JIRA Uploading release candidates for android release")
If everything went well the Release Candidate will show up here: https://dist.apache.org/repos/dist/dev/cordova/
For your platform:
RELEASENOTES.md
into a Release Announcement blog postcordova-docs
repocordova-docs
and asking someone on dev list to +1 it.Send an email to dev ML with: (replace android
with your platform)
Subject:
[VOTE] Cordova-Android 5.0.0 Release
Body:
Please review and vote on this 5.0.0 Android Release by replying to this email (and keep discussion on the DISCUSS thread) Release issue: https://issues.apache.org/jira/browse/CB-XXXX The archive has been published to dist/dev: https://dist.apache.org/repos/dist/dev/cordova/CB-XXXX The package was published from its corresponding git tag: ### PASTE OUTPUT OF: coho print-tags -r android --tag 5.0.0 ### Note that you can test it out via: cordova platform add https://github.com/apache/cordova-android#5.0.0 Upon a successful vote I will upload the archive to dist/, publish it to npm, and post the blog post. Voting guidelines: https://github.com/apache/cordova-coho/blob/master/docs/release-voting.md Voting will go on for a minimum of 48 hours. I vote +1: * Ran coho audit-license-headers over the relevant repos * Ran coho check-license to ensure all dependencies and subdependencies have Apache-compatible licenses * Ensured continuous build was green when repo was tagged * ### Add all the other things you did to confirm the working of the release ###
Respond to the vote thread with:
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 there were any votes from non-pmc, include them in an additional Non-Binding
section.
Positive Non-Binding Votes: (# that +1'ed) .. names of all +1 non-PMC members .. Negative Non-Binding Votes: (# that -1'ed) .. names of all -1 non-PMC members ..
Note: list of PMC members: http://people.apache.org/phonebook.html?pmc=cordova
-dev
git tag -f
-dev
dist/
& npmFirst move the release package files to dist/
:
(replace android
with your platform)
cd cordova-dist svn up svn rm platforms/cordova-android* cp ../cordova-dist-dev/$JIRA/cordova-android* platforms/ svn add platforms/cordova-android* svn commit -m "$JIRA Published android release to dist"
Now you can find your release here: https://dist.apache.org/repos/dist/release/cordova/
Then you can also remove the release candidate from dist-dev/
:
cd ../cordova-dist-dev svn up svn rm $JIRA svn commit -m "$JIRA Removing release candidates from dist/dev" cd ..
And finally you can publish your package to npm
:
cd cordova-dist npm publish platforms/cordova-android-5.0.0.tgz
Note: On Windows you have to replace /
with \
for this command to work.
Check online if everything worked: https://www.npmjs.com/package/cordova-windows
You should now also be able to add your platform via the version number using the CLI:
cordova create platformTest cd platformTest cordova platform add android@5.0.0
BINTRAY_USER
should be the username “cordova”. The API key is available on the bintray cordova “edit profile” page - the last option in the menu on the left is “API Key”. Find it there. Credentials to log into the bintray site are on the PMC private SVN. If you have trouble, ask the Project Management Committee (pmc) for the credentials. Confirm that your key and user name are set:echo $BINTRAY_USER echo $BINTRAY_KEY
(cd cordova-android/framework && git checkout 6.2.2 && gradle bintrayUpload)
Make a copy of your released tag with a prefix of rel/YOURTAG
:
(cd cordova-android; git checkout 5.1.0; git tag rel/5.1.0; git push origin --tags; git checkout master)
These are permanent release tags for Apache.
cordova-$PLATFORM@x.x.x
as “Full version name”Subject: [ANNOUNCEMENT] Cordova Android 5.0.0 Release Cordova-windows@VERSION has been released!
Announce the release to the world!
Follow the README at https://github.com/apache/cordova-docs, and specifically the deploy section: https://github.com/apache/cordova-docs#deploying
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 && git push origin refs/tags/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 git commit --allow-empty -m "empty commit to update tag on github mirror" git push origin
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".