This page describes the technical steps for doing a Platforms Release.
- General instructions
- Before you start
- Before Release
- Prepare Release
- Testing
- Push Changes
- Publish Release Candidate to
dist/dev - Documentation and Communication
- Voting and Release
- Follow up steps
- Other stuff that should be reviewed and moved up to the appropriate places
- See: versioning-and-release-strategy.md for general versioning information
- Before cutting any releases, read the Apache's Releases Policy
- Replace
Androidwith 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.
Releases are identified by a "Release Identifier" that is used in commit messages and for temporary folders.
Good choices are unique and have a direct relation to the release you are about to perform. Examples for valid identifiers would be android20190506 or android@503. You can also create a release issue and use that (including the repository name): cordova-android#123.
Then set it as an environment variable:
RELEASE=android20190506
echo $RELEASE
Email the dev mailing-list at [email protected] 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 your checkout of the repository is up-to-date:
coho repo-update -r android # updates the repos
See if any dependencies are outdated
(cd cordova-android && npm outdated --depth=0)
(The --depth=0 prevents from listing dependencies of dependencies.)
Alternative 1:
- Explicitly pin the outdated dependency versions in the
dependenciessection ofpackage.json. - Raise a new issue to update the dependencies in an upcoming release.
Alternative 2:
Within a new Pull Request: update any outdated dependencies in the project's package.json file. Be sure to run through the test section below for compatibility issues.
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)
TODO Get rid of package-lock.json afterwards
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
Preparation of the release includes a) handling version numbers, b) creating nice release notes and c) creating the release branch.
This should be automatically done by the coho prepare-platform-release-branch command as described in Create Release Branch section below.
This 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)
TODO what does that mean? Examples.
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 "Update RELEASENOTES & version for release $v ($RELEASE)")
(Should be Update RELEASENOTES.md for release $v ($RELEASE) 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:
- Creates a release branch
5.0.x(if it doesn't already exist) - Updates
cordova.jssnapshot on both5.0.xandmaster - Propagates version number from
--versionargument (or frompackage.jsonif there is no--versionargument) to all other files (VERSIONand similar [e.g.build.gradlefor Android]) on the release branch5.0.x - Prepares
masterfor future development already: It gives version (package.json,VERSIONand similar) a minor bump and adds-dev(=>5.1.0-dev) back
Run 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.
Create 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.
Create 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.
Run 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.
Run cordova-lib tests.
(cd cordova-lib/cordova-lib && npm test)
Clean up the project(s) you just created.
rm -rf androidTest*
Create an issue for it and fix it via a Pull Request before continuing.
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.
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/$RELEASE --tag 5.0.0
Sanity Check:
coho verify-archive cordova-dist-dev/$RELEASE/*.tgz
Upload:
(cd cordova-dist-dev && svn add $RELEASE && svn commit -m "Uploading release candidates for android release ($RELEASE)")
If everything went well the Release Candidate will show up here: https://dist.apache.org/repos/dist/dev/cordova/
For your platform:
- Ensure the Upgrade Guide for your platform is up-to-date
- Ensure the other guides listed in the sidebar are up-to-date for your platform
- Gather highlights from
RELEASENOTES.mdinto a Release Announcement blog post - Instructions on publishing a blog post are on the
cordova-docsrepo - Get blog post proofread by submitting a PR to
cordova-docsand 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)
The archive has been published to dist/dev:
https://dist.apache.org/repos/dist/dev/cordova/XXX/
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
- Revert adding of
-dev - Address the concerns
- Re-tag release using
git tag -fTODO this seems to be missing a few steps here - Add back
-dev - Start a new vote
First 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/$RELEASE/cordova-android* platforms/
svn add platforms/cordova-android*
svn commit -m "Published android release to dist ($RELEASE)"
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 $RELEASE
svn commit -m "Removing release candidates from dist/dev ($RELEASE)"
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-android
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 [email protected]
- Add the cordova bintray username and API key as system variables. Your
BINTRAY_USERshould 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
- Run the following command (replace 6.2.2 with released version):
(cd cordova-android/framework && git checkout 6.2.2 && gradle bintrayUpload)
- Load up the bintray webpage for cordova-android: https://bintray.com/cordova/maven/cordova-android. You should see a notification/warning about publishing the latest release. Hit the Publish link!
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.
- Go to: https://reporter.apache.org/addrelease.html?cordova
- Use
[email protected]as "Full version name" - Click "Update release data" to submit it to the list
Subject: [ANNOUNCEMENT] Cordova Android 5.0.0 Release
Cordova-Android@VERSION has been released!
Announce the release to the world!
- Publish the release blog post
- Tweet it on https://twitter.com/apachecordova
- Update these instructions if they were missing anything.
- That's it!
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".