Author: stain Date: Thu Jun 11 14:48:43 2015 New Revision: 1684907 URL: http://svn.apache.org/r1684907 Log: more about releasing
Modified: incubator/taverna/site/trunk/content/community/releasing.md Modified: incubator/taverna/site/trunk/content/community/releasing.md URL: http://svn.apache.org/viewvc/incubator/taverna/site/trunk/content/community/releasing.md?rev=1684907&r1=1684906&r2=1684907&view=diff ============================================================================== --- incubator/taverna/site/trunk/content/community/releasing.md (original) +++ incubator/taverna/site/trunk/content/community/releasing.md Thu Jun 11 14:48:43 2015 @@ -71,10 +71,10 @@ as the working directory. You need to have `gpg` and preferably a *GPG Agent* installed on the machine you will build the release on. This needs to be configured with your -GPG release key. +[GPG release key](https://www.apache.org/dev/release-signing.html). -Check that our -[KEYS](https://dist.apache.org/repos/dist/release/incubator/taverna/KEYS) +Check that the Apache Taverna +[KEYS](https://dist.apache.org/repos/dist/release/incubator/taverna/KEYS) file contains your correct key and fingerprint. If not, then: Find your PGP fingerprint: @@ -98,8 +98,10 @@ e.g.: DDDE E876 12E9 FB95 F5C8 D91E 4110 63A3 A0FF D119 -Now verify that [taverna.asc](https://people.apache.org/keys/group/taverna.asc) -includes the correct key fingerprint, and update on dist: + +Now verify that the +[people.apache.org taverna.asc](https://people.apache.org/keys/group/taverna.asc) +file now includes the correct key fingerprint, and update on dist: svn co https://dist.apache.org/repos/dist/release/incubator/taverna/ cd taverna @@ -123,7 +125,7 @@ released and which don't form part of th ## Git config -*Important*: Make sure that each new checkout have the correct +Make sure that each new checkout have the correct user name information and your `@apache.org` email address: cd incubator-taverna-maven-parent @@ -136,8 +138,6 @@ user name information and your `@apache. - - ### Verify build Now we'll make sure they build normally, *pass all the tests* and @@ -196,43 +196,53 @@ will perform a build. Check the list of open [Staging Repositories](https://repository.apache.org/#stagingRepositories) on the Nexus instance, and Close/Drop any old `orgapachetaverna-*` repositories. -Do not touch the other repositories. +Do not touch the other repositories from other projects. ## Creating release candidate ### Figure out release order -If more than one repository needs to be released, e.g. because the -newer SNAPSHOT version is needed, then those repositories needs -to be released in incrementing order. The dependency order is -generally from top to bottom of the list in -[code download page](/download/code) +If more than one git repository needs to be released, +e.g. because the newer SNAPSHOT version is needed, then those +repositories needs to be released in incremental order. The +dependency order is generally from top to bottom of the list on +the [code download page](/download/code), e.g. `taverna-language` +before `taverna-engine` before `taverna-workbench`. + ### Fix versions -Edit the top-level `pom.xml` of the repository to ensure there +Edit the top-level `pom.xml` of each project to release, ensuring there are no `-SNAPSHOT` dependencies in its `<parent>` and `<properties>`. **Do not fix** the `<version>` of the Maven project itself or -its submodules, as they must be on the form `-SNAPSHOT` in +its submodules, as they must be on the form `*-SNAPSHOT` in order for the Maven Release Plugin to modify them. Check if a newer `taverna-maven-parent` or other `taverna.*.version` -is needed. This is usually indicated by depending on an unreleased -SNAPSHOT version. Accordingly, after the release, do *not* update -these versions to the bumped SNAPSHOT versions, as that would +dependencies are needed. This is usually indicated by depending on an +unreleased SNAPSHOT version. Accordingly, after the release process, +do *not* update `master` to use the bumped SNAPSHOT versions, as that would wrongly indicate that a newer dependency is needed. -Update all `taverna.*.version` properties + +For compile/test purposes, update all `taverna.*.version` properties to the *latest released version*. -(Exception to the rule - when OSGi backwards-compatibility is -needed, e.g. a wsdl-activity that should work also with an older -taverna-engine release). + +Exception to the rule: - when OSGi backwards-compatibility is +needed, e.g. an updated wsdl-activity that should work also with an +older taverna-engine-api release. + +Remember that in OSGi, as long as we follow semantic +versioning and don't break API compatibility, an upstream +dependency can be updated without forcing an update release +of its downstream users. If you are updating `taverna-maven-parent`, then try to update this to the latest -[Apache super-pom](http://central.maven.org/maven2/org/apache/apache/). +[Apache super-pom](http://central.maven.org/maven2/org/apache/apache/) - be aware +that this could change Maven build settings. Commit your `pom.xml` changes (if any) and push. @@ -241,18 +251,20 @@ Commit your `pom.xml` changes (if any) a ### Prepare release candidate -Using the +We use the [Maven release plugin](https://maven.apache.org/maven-release/maven-release-plugin/) -is the recommended way to create -release candidates as it ensures a consistent release process: +to release candidates as it ensures a consistent release process: mvn release:prepare -(Note: The parameter `-Papache-release` is no longer needed, as it is activated by the -[maven-release-plugin configuration](https://github.com/apache/incubator-taverna-maven-parent/blob/master/pom.xml#L301) -in taverna-maven-parent) +**Note:** Maven will use `gpg` to tag and sign the artifacts - so you might want to +install and configure a **GPG Agent** to avoid repeatedly providing your +GPG passphrase. -The default for "What is the release version for" is usually good - but check the policy for version numbers below. + +The defaults for "What is the release version for" is usually good (assuming the SNAPSHOT version has been +correctly bumped for any major/minor/patch changes to the code), +but check the [policy for version numbers below](#Version_numbers). [INFO] Checking dependencies and plugins for snapshots ... What is the release version for "Apache Taverna Language APIs (Scufl2, Databundle)"? (org.apache.taverna.language:taverna-language) 0.15.0-incubating: : @@ -265,11 +277,11 @@ You will be asked for each submodule wha their version should be the same as their parent (except to explicitly allow API backward compatibility) -**Note**: Take care to use the previous version number if preparing a -second release candidate, as Maven would then suggest too high version +**Note**: Take care to use the correct version number if preparing a +second release candidate, as Maven could suggest a higher version number based on the bumped `-SNAPSHOT` version. -#### Apache Taverna version numbers +#### Version numbers * Has to end in `-incubating` (while Apache Taverna is incubating) * taverna-maven-parent is versioned with just major version, e.g. `4-incubating` @@ -284,14 +296,36 @@ Semantic versioning summary: > * MINOR version when you add functionality in a backwards-compatible manner, > and > * PATCH version when you make backwards-compatible bug fixes. +Use `git diff` against the previous release tag for a rough check for changes. + + git diff 0.15.0-incubating-RC2 + +Note that as we use of OSGi, the public Java API is usually just what is exposed +by the `*-api` modules, meaning that implementatoin changes normally should +just warrant a new patch version. We should also consider indirect APIs, such +as an Activity's expected JSON configuration or +the REST API of the Taverna Server. + +Check with dev@taverna if you are not sure. Usually bumping minor +(e.g. from `1.5.2` to `1.6.0`) is the right option, as we release all +modules in the git repository. + #### Tagging and next SNAPSHOT version -For the tag, use the proposed format, but modify `-RC1` -for any subsequent release candidates. +For the tag, use the proposed format (`0.15.0-incubating-RC1`), but +modify `-RC1` for any subsequent release candidates. What is SCM release tag or label for "Apache Taverna Language APIs (Scufl2, Databundle)"? (org.apache.taverna.language:taverna-language) 0.15.0-incubating-RC1: : +**Module-specific release**: If a hot-patch update of a +particular Maven module is being released from within its subfolder, +then prefix the tag-name with the module name, +e.g. `taverna-scufl2-t2flow-0.15.1-incubating-RC1`. Note that preparing a +single module release requires careful consideration for +setting the `<parent>` and `<dependency>` versions and +should generally be avoided. + The next development version should usually be one *patch version* higher, or for taverna-maven-parent simply the next number: @@ -305,11 +339,8 @@ Maven will now transform your poms, crea back to Apache's git repository. If you abort, you can start the process again using `mvn release:prepare`, -which will pick up your answers so far from `release.profiles`. +which will pick up your answers so far from the file `release.profiles`. -Note Maven will use `gpg` to tag and sign the artifacts - so you might want to -install and configure a **GPG Agent** to avoid repeatedly providing your -GPG passphrase. #### Rolling back @@ -330,7 +361,8 @@ If the preparation was successful, then mvn release:perform This will check out the tag, build it, then sign and -deploy the packaged source code and compiled JARs. +deploy the packaged source code and compiled JARs +to `repository.apache.org`. @@ -352,12 +384,11 @@ next to it and click *Close*. **DO NOT CLICK RELEASE YET** - the release candidate must pass *[VOTE]* emails on both dev@taverna and general@incubator before we release. -Once closing has finished (check with *Refresh*, browse to the +Once closing has finished (check with *Refresh*), browse to the *URL* of the [staging repository](https://repository.apache.org/content/repositories) which should be something like -https://repository.apache.org/content/repositories/orgapachetaverna-1001/ - +`https://repository.apache.org/content/repositories/orgapachetaverna-1003/` ### Uploading to dist.apache.org @@ -365,15 +396,15 @@ https://repository.apache.org/content/re The release candidate source code, checksums and signatures should be uploaded to [dist.apache.org](https://dist.apache.org/repos/dist/dev/incubator/taverna/) -using `svn` - here we'll check out to a folder `~/src/rc1/dist`: +using `svn` - which we'll check out to a new folder `~/src/rc1/dist`: svn co https://dist.apache.org/repos/dist/dev/incubator/taverna dist -The folder should normally be empty -- if +The `source` folder should normally be empty -- if you find remains of an earlier RC that is not still under *[VOTE]*, first remove them with `svn rm`: - cd dist + cd dist/source svn rm * Retrieve the source archives from the staging repository by looking for @@ -383,7 +414,11 @@ folder corresponding to the groupID and top-level project, e.g. `org/apache/taverna/language/0.15.0-incubating/` containing `taverna-language-0.15.0-incubating-source-release.zip` -Here's a convenient `wget` command to get all the release archives and +For consistency checking you also need to include the +PGP signature `.asc` and the checksums +``.sha1` and `.md5` + +Here's a convenient `wget` command to get all the release archives, their checksums and signatures: wget -e robots=off --recursive --no-parent --no-directories -A "*-source-release*" https://repository.apache.org/content/repositories/orgapachetaverna-1002/org/apache/taverna/ @@ -392,24 +427,35 @@ Make sure you have not got any extra fil `index.html` or duplicates like `*.zip.1` stain@biggie-utopic:~/src/rc1/dist$ ls + binaries/ source/ taverna-language-0.15.0-incubating-source-release.zip taverna-language-0.15.0-incubating-source-release.zip.sha1 taverna-parent-1-incubating-source-release.zip.md5 taverna-language-0.15.0-incubating-source-release.zip.asc taverna-parent-1-incubating-source-release.zip taverna-parent-1-incubating-source-release.zip.sha1 taverna-language-0.15.0-incubating-source-release.zip.md5 taverna-parent-1-incubating-source-release.zip.asc -Now make a corresponding versioned folder for each product, and include the RC number: +Under `source/`, make a corresponding versioned folder for each product, +and *include the RC number*, avoiding confusion in case you need to +make a second release candidate: - mkdir taverna-language-0.15.0-incubating-RC1 - mkdir taverna-parent-1-incubating-RC1 + mkdir source/averna-language-0.15.0-incubating-RC2 + mkdir source/taverna-parent-1-incubating-RC2 + mv *language*release* source/taverna-language-0.15.0-incubating-RC2 + mv *parent*release* source/taverna-parent-1-incubating-RC2 -Now add them to the `dist` folder with `svn add` and `svn commit` - ... TODO +Now add them to the `source` folder with `svn add` and `svn commit` + + svn add taverna-language-0.15.0-incubating-RC1 taverna-parent-1-incubating-RC1 + svn commit -m "taverna-language 0.15.0-incubating-RC1" If any binary distributions are also be provided from the [Download page](/download) (e.g. Taverna Workbench installers and Taverna Server `war`s), then download them as well *from the staging -repository* and add them similarly with their corresponding -`.asc`, `.md5` and `.sha1` files. +repository* and add them under equivalent versioned folders in `binaries/`, +including their corresponding +`.asc`, `.md5` and `.sha1` files, + +Versioned folders make it easier to tidy up after a dropped release +candidate, and easier to promote the release. Now verify that the files are available on [https://dist.apache.org/repos/dist/dev/incubator/taverna/](https://dist.apache.org/repos/dist/dev/incubator/taverna/) - @@ -419,15 +465,118 @@ you might need a *Refresh* in the browse ## Voting +Any Apache release must be approved through a +[vote](http://www.apache.org/foundation/voting.html) +of the project's PMC. As Apache Taverna is an incubating project, a Taverna release must be +approved by both the [Apache Taverna PPMC](/about) and the +[Apache Incubator IPMC](http://incubator.apache.org/guides/ppmc.html). + +Before an Apache Taverna release can be distributed, it must thus pass two stages: + +* [VOTE] on dev@taverna +* [VOTE] on general@incubator + +Each of the *[VOTE]* threads should be open for **at least 72 hours**, allowing time for +sufficient [review](#Reviewing), and catering for differences in +holidays and timezones. + +Including 24 hours grace period for the download mirrors, +this means a release takes a minimum of a week before +a release candidate might be published and released. + +Anyone in the [community](/community) can participate in the +review and vote, not just PMC members or committers. Only votes +from IPMC members are **binding**. + + +### Vote email to dev@taverna + +To start the release vote, modify the below example and send to dev@taverna. +Remember `[VOTE]` in the subject line. + +Subject: [VOTE] Release Apache Taverna Language 0.15.0-incubating RC2 + +I am pleased to be calling this vote for the source release of + + Apache Taverna Maven Parent 1-incubating + Apache Taverna Language 0.15.0-incubating + +Apache Taverna Language is a set of APIs for workflow definitions (SCUFL2) +and workflow inputs/outputs/run (DataBundle), as consumed and produced by the +Apache Taverna workflow system. The API includes support for working with +Research Object Bundles, and loading/saving Taverna workflows in different +formats. + + +The release candidates to be voted over are available at: + + https://dist.apache.org/repos/dist/dev/incubator/taverna/source/taverna-parent-1-incubating-RC2/ + https://dist.apache.org/repos/dist/dev/incubator/taverna/source/taverna-language-0.15.0-incubating-RC2/ + + SHA-1 checksums: + 8199880048a59cde622e0caa24c3bc3d83bc5d5a taverna-parent-1-incubating-source-release.zip + 7032e9d2be834f7c029aae562b62613481bf6939 taverna-language-0.15.0-incubating-source-release.zip + + MD5 checksums: + 7f9b107b9f1dc0407783ac0ad484d6ea taverna-parent-1-incubating-source-release.zip + 35d3085b596b2dd4b30a0234259efade taverna-language-0.15.0-incubating-source-release.zip + + +Build the release candidate in the above order, using: + mvn clean install -### Vote +The release candidates correspond to the following git commits: + + https://git-wip-us.apache.org/repos/asf?p=incubator-taverna-maven-parent.git;a=commit;h=3ba669c78782d3fc3b548e2a512d201ee922b34a + https://git-wip-us.apache.org/repos/asf?p=incubator-taverna-language.git;a=commit;h=3340e2090e604b40ac0b88675f57c1d12032d060 + + + +Release candidates are signed with a GPG key available at: + + https://dist.apache.org/repos/dist/release/incubator/taverna/KEYS + +A staged Maven repository is available for review at: + + https://repository.apache.org/content/repositories/orgapachetaverna-1003/ + +The changelog for this release is available from JIRA: + + https://issues.apache.org/jira/secure/ReleaseNote.jspa?projectId=12318322&version=12332247 + https://issues.apache.org/jira/secure/ReleaseNote.jspa?projectId=12318322&version=12332246 + + + +Please vote on releasing these packages as: + + Apache Taverna Maven Parent 1-incubating + Apache Taverna Language 0.1.0-incubating + + +The vote is open for at least 72 hours and passes if a +majority of at least three +1 Apache Taverna PPMC votes are cast. + +[ ] +1 Release this package +[ ] 0 I don't feel strongly about it, but don't object +[ ] -1 Do not release this package because... + +Anyone can participate in testing and voting, not just +committers, please feel free to try out the release candidate +and provide your votes. + + + + + +### Tallying the vote + +### Vote email to general@incubator -**TODO** ## Dropping a release candidate -If a release candidate is to be dropped, e.g. it fails the *[VOTE]*, then +If a release candidate is to be dropped, e.g. it fails the *[VOTE]*, then: In Nexus, tick the [staging repository](https://repository.apache.org/#stagingRepositories) and *Drop*. @@ -439,8 +588,43 @@ Roll back the SNAPSHOT version number: mvn release:update-versions -DautoVersionSubmodules=true -DdevelopmentVersion=0.15.0-incubating-SNAPSHOT` -In dist, svn rm all. +In your `dist` checkout, `svn rm` the dropped RC folders: + + svn rm *RC* - svn rm */* ## Distributing + +Once a *[VOTE] [Results]* email has been agreed on general@incubator, +then: + +* Promiote the release candidate to a release + +### Moving to release area + + +Use full URL `svn mv` to move the accepted release candidate +to the `release` folder structure on dist.apache.org, +e.g. at +[https://dist.apache.org/repos/dist/release/incubator/taverna/source/](https://dist.apache.org/repos/dist/release/incubator/taverna/source/) +but remember to remove the `-RC1` from the folder name. + + svn mv https://dist.apache.org/repos/dist/dev/incubator/taverna/source/taverna-language-0.15.0-incubating-RC2 https://dist.apache.org/repos/dist/release/incubator/taverna/source/taverna-language-0.15.0-incubating + svn mv https://dist.apache.org/repos/dist/dev/incubator/taverna/source/taverna-parent-1-incubating-RC2 https://dist.apache.org/repos/dist/release/incubator/taverna/source/taverna-parent-1-incubating + +### Update download page + +Wait 24 hours for the download mirrors to pick up the new release from `dist.apache.org`. + +TODO. + + +### Removing old versions + +TODO + +### Releasing Maven repository + +Tick the correct [staging repository](https://repository.apache.org/#stagingRepositories) (perhaps do a quick check of an SHA1 sum against the vote email), then click *Release*. +It should then propagate to [Apache's release Maven repository](https://repository.apache.org/content/repositories/releases/org/apache/taverna/) +and eventually mirrored to [Maven Central](http://central.maven.org/maven2/org/apache/taverna/).