This page describes the technical steps for doing a Platforms Release.
dist/devAndroid 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.
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 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 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:
dependencies section of package.json.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.
npm audit checkEnsure 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.
package.jsonThis 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) 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:
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.xmaster for future development already: It gives version (package.json, VERSION and similar) a minor bump and adds -dev (=> 5.1.0-dev) backRun 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 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.
dist/devAttention: 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:
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)
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
-devgit tag -f TODO this seems to be missing a few steps here-devdist/ & 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/$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-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".