You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@taverna.apache.org by st...@apache.org on 2015/06/11 16:48:44 UTC
svn commit: r1684907 -
/incubator/taverna/site/trunk/content/community/releasing.md
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/).