You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@isis.apache.org by da...@apache.org on 2012/12/11 21:06:13 UTC
svn commit: r1420373 - in /isis/site/trunk/content: ./ contributors/
contributors/resources/
Author: danhaywood
Date: Tue Dec 11 20:06:09 2012
New Revision: 1420373
URL: http://svn.apache.org/viewvc?rev=1420373&view=rev
Log:
isis site - updating release process documentation for use witth git
Added:
isis/site/trunk/content/contributors/resources/nexus-staging-1.png (with props)
isis/site/trunk/content/contributors/resources/nexus-staging-2.png (with props)
isis/site/trunk/content/contributors/resources/nexus-staging-3.png (with props)
isis/site/trunk/content/contributors/resources/nexus-staging-4.png (with props)
Modified:
isis/site/trunk/content/contributors/about.md
isis/site/trunk/content/contributors/release-process.md
isis/site/trunk/content/contributors/release-snapshot.md
isis/site/trunk/content/contributors/verifying-releases.md
isis/site/trunk/content/documentation.md
Modified: isis/site/trunk/content/contributors/about.md
URL: http://svn.apache.org/viewvc/isis/site/trunk/content/contributors/about.md?rev=1420373&r1=1420372&r2=1420373&view=diff
==============================================================================
--- isis/site/trunk/content/contributors/about.md (original)
+++ isis/site/trunk/content/contributors/about.md Tue Dec 11 20:06:09 2012
@@ -10,9 +10,7 @@ Title: Contributors
### Committers
- [Updating the CMS site](updating-the-cms-site.html)
-- [Release snapshot](release-snapshot.html) [wip]
-- [Release process](release-process.html) [wip]
-<!--
-- [Verifying releases](verifying-releases.html) [wip]
--->
+- [Release snapshot](release-snapshot.html)
+- [Release process](release-process.html)
+- [Verifying releases](verifying-releases.html)
- [Key Generation](key-generation.html)
Modified: isis/site/trunk/content/contributors/release-process.md
URL: http://svn.apache.org/viewvc/isis/site/trunk/content/contributors/release-process.md?rev=1420373&r1=1420372&r2=1420373&view=diff
==============================================================================
--- isis/site/trunk/content/contributors/release-process.md (original)
+++ isis/site/trunk/content/contributors/release-process.md Tue Dec 11 20:06:09 2012
@@ -1,9 +1,5 @@
Title: Release Process
-{stub
-This page is a work-in-progress.
-}
-
Apache Isis consists of a number of separately releasable modules. Relative to the root of the [source code repo](https://git-wip-us.apache.org/repos/asf/isis/repo?p=isis.git;a=tree), these are:
- `core`
@@ -11,12 +7,12 @@ Apache Isis consists of a number of sepa
- `component/objectstore/nosql`
- `component/objectstore/sql`
- `component/objectstore/xml`
-- `component/security/ldap`
-- `component/security/sql`
- `component/profilestore/sql`
- `component/profilestore/xml`
- `component/progmodel/groovy`
- `component/progmodel/wrapper`
+- `component/security/ldap`
+- `component/security/sql`
- `component/viewer/bdd`
- `component/viewer/dnd`
- `component/viewer/html`
@@ -40,103 +36,102 @@ Once agreed, the formal release can begi
- vote on the staged artifacts (in particular, the signed source release ZIP from which the remaining artifacts are derivable)
- on a successful vote:
- promote the staged artifacts
- - merge in the branch back to into trunk
+ - distribute the source zip
+ - merge in the branch back to into master
- on a failed vote:
- drop the staging repository
- delete the branch and tag
- fix the problems and go round round the loop again.
-Before any of this can happen, there are a number of prerequisites, in terms of (a) the codebase itself, (b) the community process, and (c) the contributor acting as release manager and performing the release.
+Before any of this can happen, there are a number of prerequisites, in terms of (a) the codebase itself, (b) the community process, and (c) the committer acting as release manager and performing the release.
### Set up local environment
-First, clear out your local Maven repo of any Isis artifacts:
-
-<pre>
-cd ~/.m2/repository/org/apache
-mv isis isis-MOVED
-</pre>
-
-Second, create a branch in your local Git repo:
-
-<pre>
-git checkout -b release/x.y.z
-</pre>
-
-All release preparation is done locally; when we are done, this branch will be pushed back to master.
+#### Public/private key
+The most important configuration you require is to set up public/private key pair. This is used by the `maven-release-plugin` to sign the code artifacts. See the page on [key generation](key-generation.html) for more details.
-## Code Prerequisites
-
-Before making any formal release, there are a number of prerequisites that should always be checked
+In order to prepare the release, you'll (need to) have a `~/.gnupg` directory with the relevant files (`gpg.conf`, `pubring.gpg`, `secring.gpg` etc), and have `gpg` on your operating system PATH.
-### Update dependency versions
+{note
+If on Windows, the equivalent directory is `c:\users\xxx\appdata\roaming\gnupg`. For `gpg`, use either [cygwin.com](http://cygwin.com) or [gpg4win.org](http://www.gpg4win.org). Note also that the mSysGit version of `gpg` (as provided by GitHub's bash client) is not compatible with that provided by cygwin.
+}
-First, check (via [http://search.maven.org](http://search.maven.org)) whether there is a newer version of the Apache parent `org.apache:apache`. If so, update the `<parent>` element in Isis' own parent POM `org.apache.isis:isis`.
+#### Maven `settings.xml`
-Second, use the Maven versions plugin can be used to determine if there are newer versions of any of Isis' dependencies:
+During the release process the `maven-deploy-plugin` uploads the generated artifacts to a staging repo on the [Apache repository manager](http://repository.apache.org). This requires your Apache LDAP credentials to be specified in your `~/.m2/settings.xml` file:
<pre>
-mvn versions:display-dependency-updates > /tmp/foo
-grep "\->" /tmp/foo | sort -u
+<settings>
+ <servers>
+ <server>
+ <id>apache.releases.https</id>
+ <username>xxxxxxx</username>
+ <password>yyyyyyy</password>
+ </server>
+ ...
+ </servers>
+ ...
+</settings>
</pre>
-Update any of the dependencies that are out-of-date.
+where `xxxxxxx` and `yyyyyyy` are your Apache LDAP username and password. For more information, see these [ASF docs](http://www.apache.org/dev/publishing-maven-artifacts.html#dev-env).
+
+{note
+It is also possible to configure to use `.ssh` secure keys, and thereby avoid hardcoding your Apache LDAP password into your `.m2/settings.xml` file. A description of how to do this can be found, for example, [here](http://incubator.apache.org/bval/cwiki/release-setup.html).
+}
-### Sanity check
+#### Pull down code to release
-First, clear out your local Maven repo of any Isis artifacts:
+Set the HEAD of your local git repo to the commit to be released. In many cases this will be the tip of the origin's `master` branch:
<pre>
-cd ~/.m2/repository/org/apache
-mv isis isis-MOVED
+git checkout master
+git pull --ff-only
</pre>
-Next, check that the releasable module builds independently. For example, if releasing the `core` module, check that it builds:
-
+Then, create a release branch in your local Git repo:
<pre>
-cd core
-mvn clean install -o
+git checkout -b release/x.y.z
</pre>
-Or, if you were building an objectstore, make sure that it builds independently:
+All release preparation is done locally; if we are successful, this branch will be pushed back to master.
-<pre>
-cd component/objectstore/jdo
-mvn clean install -o
-</pre>
{note
-All remaining steps should be performed in the base directory of the module being released.
+Unless otherwise stated, you should assume that all remaining steps should be performed in the base directory of the module being released.
}
-<!--
-- site builds ok
+## Code Prerequisites
-<pre>
-sh msdf.sh -o
-</pre>
+Before making any formal release, there are a number of prerequisites that should always be checked.
-- archetype is ok
+### Update Apache parent (Isis Core only)
- - archetype runs ok
+If releasing Isis Core, check (via [http://search.maven.org](http://search.maven.org)) whether there is a newer version of the Apache parent `org.apache:apache`.
- using `-D archetypeCatalog=local`
+If there is, update the `<version>` in the `<parent>` element in the parent POM `org.apache.isis.core:isis`.
- - app generated from the archetype runs ok
--->
+### Update dependency versions
+
+The `maven-versions-plugin` should be used to determine if there are newer versions of any of Isis' dependencies:
+
+<pre>
+mvn versions:display-dependency-updates > /tmp/foo
+grep "\->" /tmp/foo | sort -u
+</pre>
+
+Update any of the dependencies that are out-of-date.
### Code cleanup / formatting
Make sure that all source code has been cleaned up and formatted according to the Apache Isis and ASF conventions. Full details are in [Isis coding conventions](coding-conventions.html).
-## License header notices (RAT tool)
+### License header notices (RAT tool)
-The Apache Release Audit Tool `RAT` (from the [Apache Creadur](http://creadur.apache.org) project) checks for missing license header files.
-
-The parent `pom.xml` of each releasable module specifies the RAT Maven plugin, with a number of custom exclusions.
+The Apache Release Audit Tool `RAT` (from the [Apache Creadur](http://creadur.apache.org) project) checks for missing license header files. The parent `pom.xml` of each releasable module specifies the RAT Maven plugin, with a number of custom exclusions.
To run the RAT tool, use:
@@ -161,14 +156,14 @@ Investigate and fix any reported violati
- updating the `<excludes>` element for the `apache-rat-plugin` plugin to ignore test files, log files and any other non-source code files
- also look to remove any stale `<exclude>` entries
-To add missing headers, you can if you wish use the groovy script `addmissinglicenses.groovy` to automatically insert missing headers for certain file types. The actual files checked are those with extensions specified in the line `def fileEndings = [".java", ".htm"]`:
+To add missing headers, you can if you wish use the groovy script `addmissinglicenses.groovy` (in the `scripts` directory) to automatically insert missing headers for certain file types. The actual files checked are those with extensions specified in the line `def fileEndings = [".java", ".htm"]`:
-- dry run:
+Run this in dry run mode first (shown here relative to the `core` module):
<pre>
-groovy addmissinglicenses.groovy
+groovy ../scripts/addmissinglicenses.groovy
</pre>
-- or to actually execute:
+When happy, perform the updates by specifying the `-x` (execute) flag:
<pre>
groovy addmissinglicenses.groovy -x
</pre>
@@ -181,11 +176,11 @@ for a in `find . -name rat.txt -print`;
</pre>
-## Missing License Check
+### Missing License Check
-Although Apache Isis has no dependencies which have incompatible licenses, the POMs for some of these dependencies (in the Maven central repo) do not necessarily contain the required license information. Without appropriate additional configuration, this would result in the generated `DEPENDENCIES` file and generated Maven site indicating dependencies as having "unknown" licenses.
+Although Apache Isis has no dependencies on artifacts with incompatible licenses, the POMs for some of these dependencies (in the Maven central repo) do not necessarily contain the required license information. Without appropriate additional configuration, this would result in the generated `DEPENDENCIES` file and generated Maven site indicating dependencies as having "unknown" licenses.
-Fortunately, Maven allows the missing information to be provided by configuring the `maven-remote-resources-plugin`. This is stored in the `src/main/appended-resources/supplemental-models.xml` file in the parent `[oai:isis]` module.
+Fortunately, Maven allows the missing information to be provided by configuring the `maven-remote-resources-plugin`. This is stored in the `src/main/appended-resources/supplemental-models.xml` file, relative to the root of each releasable module.
To capture the missing license information, use:
@@ -221,19 +216,53 @@ If any missing entries are listed or are
Ignore any missing license warnings for the TCK modules; this is a result of the TCK modules for the viewers (eg `bdd-concordion-tck`) depending on the TCK dom, fixtures etc.
}
+## Sanity check
-## Preparing a Release (`mvn release:prepare`)
+Before you cut the release, perform one last sanity check on the codebase.
-In order to prepare a release, you must have a public/private key pair, and have configured Maven. See the page on [key generation](key-generation.html) for more details.
+First, delete all Isis artifacts from your local Maven repo:
-In order to prepare the release, you'll (need to) have a `~/.gnupg` directory with the relevant files (`gpg.conf`, `pubring.gpg`, `secring.gpg` etc).
+<pre>
+rm -rf ~/.m2/repository/org/apache/isis
+</pre>
-{note
-If on Windows, the equivalent directory is `c:\users\xxx\appdata\roaming\gnupg`. For `gpg`, use either [cygwin.com](http://cygwin.com) or [gpg4win.org](http://www.gpg4win.org). Note also that the mSysGit version of `gpg` (as provided by GitHub's bash client) is not compatible with that provided by cygwin.
-}
+Next, check that the releasable module builds independently. The build process depends on whether the artifact is of Isis core or of one of its components:
+
+* For Isis core, build using the `-o` offline flag:
+
+ `mvn clean install -o`
+
+ Confirm that the versions of the Isis artifacts now cached in your local repository are correct.
+
+* For an Isis component, build without the offline flag; Maven should pull down the component's dependencies from the Maven central repo:
+
+ `mvn clean install`
+
+ Confirm that the versions of the Isis artifacts now cached in your local repository are correct (both those pulled down from Maven central repo, as well as those of the component built locally).
<!--
+- site builds ok
+
+<pre>
+sh msdf.sh -o
+</pre>
+
+- archetype is ok
+s
+ - archetype runs ok
+
+ using `-D archetypeCatalog=local`
+
+ - app generated from the archetype runs ok
+-->
+
+
+## Preparing a Release (`mvn release:prepare`)
+
+Most of the work is done using the `mvn release:prepare` goal. Since this makes a lot of changes, we run it first in "dry run" mode; only if that works do we run the goal for real.
+
+<!--
TODO: a section like this will be required when considering archetypes and/or maven sites.
### Manually update versions to the release version
@@ -243,6 +272,7 @@ There are a couple of locations where th
+
<!--
TODO: something equivalent to this will need to be documented for the archetype modules.
@@ -281,6 +311,9 @@ Then commit the `site.xml` file.
-->
+
+
+
### Dry-run
<pre>
@@ -359,7 +392,7 @@ You should end up with artifacts in your
For example, if building core, then the ZIP file will be called `isis-x.y.z-source-release.zip` and should reside in `~/.m2/repository/org/apache/isis/core/isis/x.y.z` directory.
- Unzip in a new directory, and build (see Chapter 3, Building Isis from Source).
+ Unzip in a new directory, and build.
* Inspect the `DEPENDENCIES` file.
@@ -387,28 +420,7 @@ Once the release has been built locally,
The Apache staging repository runs on Nexus server, hosted at [repository.apache.org](https://repository.apache.org). The process of uploading will create a staging repository that is associated with the host (IP address) performing the release. Once the repository is staged, the newly created staging repository is "closed" in order to make it available to others.
-Before you start, make sure you've defined the staging repo in your local `~/.m2/settings.xml` file:
-
-<pre>
-<settings>
- <servers>
- <!-- To publish a snapshot of some part of Maven -->
- <server>
- <id>apache.releases.https</id>
- <username>xxxxxxx</username>
- <password>yyyyyyy</password>
- </server>
- ...
- </servers>
- ...
-</settings>
-</pre>
-
-where `xxxxxxx` and `yyyyyyy` are your Apache LDAP username and password. For more information, see these [ASF docs](http://www.apache.org/dev/publishing-maven-artifacts.html#dev-env).
-
-{note
-It is also possible to configure to use `.ssh` secure keys, and thereby avoid hardcoding your Apache LDAP password into your `.m2/settings.xml` file. A description of how to do this can be found, for example, [here](http://incubator.apache.org/bval/cwiki/release-setup.html).
-}
+Before you start, make sure you've defined the staging repo in your local `~/.m2/settings.xml` file (see earlier on this page).
### Perform the Release
@@ -451,11 +463,15 @@ ckout\core
All being well this command will complete successfully.
+{note
+Depending on the module being released, the deploy process could take a long time. Go grab a bite of lunch.
+}
+
### Check the Repository
-If the mvn release:perform has worked then it will have put release artifacts into a newly created staging repository .
+If the `mvn release:perform` has worked then it will have put release artifacts into a newly created staging repository .
Log onto [repository.apache.org](http://repository.apache.org) (using your ASF LDAP account) and check that the release has been staged:
@@ -463,7 +479,7 @@ Log onto [repository.apache.org](http://
TODO: update screenshot
-->
-
+<img src="resources/nexus-staging-1.png" width="600px"/>
If nothing appears in a staging repo you should stop here and work out why.
@@ -480,7 +496,7 @@ Press the Close button and complete the
TODO: update screenshot
-->
-
+<img src="resources/nexus-staging-2.png" width="600px"/>
All being well, the close should complete successfully:
@@ -488,7 +504,7 @@ All being well, the close should complet
TODO: update screenshot
-->
-
+<img src="resources/nexus-staging-3.png" width="600px"/>
The Nexus repository manager will also email you with confirmation of a successful close.
@@ -498,7 +514,7 @@ If Nexus has problems with the key signa
TODO: update screenshot
-->
-
+<img src="resources/nexus-staging-4.png" width="600px"/>
Use `gpg --keyserver hkp://pgp.mit.edu --recv-keys nnnnnnnn` to confirm that the key is available.
@@ -521,7 +537,7 @@ In all cases, votes last for 72 hours an
### Start voting thread on dev@isis.apache.org
-The following boilerplate is for a release of the Apache Isis `core`. Adapt as required:
+The following boilerplate is for a release of the Apache Isis Core. Adapt as required:
Use the following subject:
<pre>
@@ -549,239 +565,263 @@ Please verify the release and cast your
[ ] -1
</pre>
+The value `orgapacheisis-nnn` is the repository id provided by Nexus earlier.
+The procedure for other committers to verify the release can be found [here](verifying-releases.html).
+## After the vote
-12.6.2. Other contributors cast their vote
+Once the vote has completed, post the results to the isis-dev mailing list.
-It is the responsibility of other contributors (or any ASF member) to cast their vote on the release. This section provides some guidance on this process.
+For example, use the following subject for a vote on Isis Core:
-12.6.2.1. Verifying the source release artifacts
+<pre>
+[RESULT] [VOTE] Apache Isis Core release x.y.z
+</pre>
-Download both the ZIP and .ASC files from the location specified in the voting email. To verify that the signature is correct, use:
+for a successful vote, using the body:
-gpg --verify isis-x.x.x-incubating.zip.asc isis-x.x.x-incubating.zip
-The ZIP file should then be unpacked.
+<pre>
+The vote has completed with the following result :
-Once unpacked, it is recommended that voters at a minimum sanity check the contents, as per Section 12.1.2, âSanity checkâ.
+ +1 (binding): <i>list of names</i>
+ +1 (non binding): <i>list of names</i>
-In particular, when building locally, confirm that the versions in your local repository (~/.m2/repository/org/apache/isis) are correct.
+ -1 (binding): <i>list of names</i>
+ -1 (non binding): <i>list of names</i>
-12.6.2.2. Verifying the binary release artifacts
+The vote is SUCCESSFUL.
+</pre>
-Optionally, voters can verify the binary releases (in the Maven staging repository). For this it is necessary to download each artifact from Nexus and its corresponding .ASC file. Since there are many such artifacts, we suggest you just choose one or two at random.
-12.6.2.3. Casting a Vote
+If the vote has been unsuccessful, then:
-When the above checks have been made (and any other checks that the voter thinks is relevant), they should cast a vote by replying to the email thread above.
+* delete your local branch
-12.6.3. After the isis-dev vote
+<pre>
+ git branch -D release/x.y.z
+</pre>
-Once the vote has completed, post the results to the isis-dev mailing list.
+* delete the remote origin server's branch
-Use the following subject:
+<pre>
+ git push origin --delete release/x.y.z
+</pre>
-[RESULT] [VOTE] Apache Isis release 0.x.x-incubating
-with the body:
+* drop the staging repository in [Nexus](http://repository.apache.org)
-The vote has completed with the following result :
+Address the problems identified in the vote, and go again.
- +1 (binding): <<list of names>>
- +1 (non binding): <<list of names>>
+## Promoting Release to Distribution
+### Release Binaries to Maven Central Repo
+From the Nexus pages, select the staging repository and select 'release' from the top menu.
-If the vote has been unsuccessful, then delete the branches and SVN tag, drop the staging repository, address the problems in trunk, and go again.
+<!--
+TODO: adda screenshot
+-->
+This moves the release artifacts into an Apache releases repository; from there they will be automatically moved to the Maven repository.
+### Release Source Zip
+As described in the [Apache documentation](http://www.apache.org/dev/release-publishing.html#distribution_dist), each Apache TLP has a `release/TLP-name` directory in the distribution Subversion repository at [https://dist.apache.org/repos/dist](https://dist.apache.org/repos/dist). Once a release vote passes, the release manager should `svn add` the artifacts (plus signature and hash files) into this location. The release is then automatically pushed to [http://www.apache.org/dist/](http://www.apache.org/dist/) by `svnpubsub`. Only the most recent release of each supported release line should be contained here, old versions should be deleted.
+Each project is responsible for the structure of its directory. The directory structure of Isis reflects the directory structure in our git source code repo:
+<pre>
+isis/
+ core/
+ component/
+ objectstore/
+ jdo/
+ nosql/
+ sql/
+ xml/
+ profilestore/
+ sql/
+ xml/
+ progmodel/
+ groovy/
+ wrapper/
+ security/
+ file/
+ ldap/
+ sql/
+ viewer/
+ bdd/
+ dnd/
+ html/
+ junit/
+ restfulobjects/
+ scimpi/
+ wicket/
+ example/
+ archetype/
+ quickstart_jdo_restful_wicket/
+ quickstart_dnd_bdd_junit/
+ site-skin/
+ tool/
+ maven-isis-plugin/
+</pre>
-12.7. Promoting Release to Distribution
-12.7.1. Release Binaries to Maven Central Repo
+If necessary, checkout this directory structure:
-From the Nexus pages, select the staging repository and select 'release' from the top menu.
+<pre>
+svn co https://dist.apache.org/repos/dist/release/isis isis-dist
+</pre>
-This moves the release artifacts into an Apache releases repository, from there they will be automatically moved to the Maven repository.
+Next, add the new release into the approprite directory, and delete any previous release. For example, if releasing Apache Isis Core `x.y.z`, superceding a previous release `p.q.r`, use:
-12.7.2. Release Source Zip
+<pre>
+cd core
+svn delete isis-p.q.r-source-release.zip
+svn delete isis-p.q.r-source-release.zip.asc
+svn add isis-x.y.z-source-release.zip
+svn add isis-x.y.z-source-release.zip.asc
+svn commit -m "publishing isis-x.y.z source to dist.apache.org"
+</pre>
-Releasing the source ZIP is a matter of copying the ZIP into the /www/www.apache.org/dist/incubator/isis directory on people.apache.org.
-Note
+## Update JIRA and generate Release notes
-There is an alternative and newer approach, namely to check in the release to subversion. At some stage these procedures will be updated to reflcet this newer approach.
+### Close All JIRA tickets for the release
-Assuming you've downloaded the ZIP file and signature file from the staging repo, and the dist directory already exists, use scp to copy the files up:
+Close all JIRA tickets for the release, or moved to future releases if not yet addressed. Any tickets that were partially implemented should be closed, and new tickets created for the functionality on the ticket not yet implemented.
-scp isis-x.x.x-incubating-source-release.* people.apache.org:/www/www.apache.org/dist/incubator/isis/.
-12.7.3. Promote and update the Website
+### Generate Release Notes in JIRA
-To promote the site, first log onto people.apache.org. Then:
+Use JIRA to generate draft release notes using the procedure documented [here](http://confluence.atlassian.com/display/JIRA/Creating+Release+Notes). If any of the tickets closed are tasks/subtasks, then please edit the contents of the file to associate them back together again.
-switch to the website directory:
+### Update ISIS website with release notes
-$ cd /www/incubator.apache.org
-Either:
+Update the Isis CMS website:
-move the previous site to one side:
+* Using the JIRA-generated release notes as a guide, update the relevant section of the CMS site.
-$ mv isis isis-0.x.w-incubating
-where 0.x.w is the previous version was uploaded
+ Typically this be will a new page in the core section or for one of the components. Make a note of the URL of this new page (for use in the mailing list announcement).
-or simply delete the site:
+ For example, a new release of Isis Core would have a release notes page `http://isis.apache.org/core/release-notes-x.y.z.html`
-$ rm -rf isis
-Move the new site into place, and for good measure touch every file to ensure it is picked up:
+* On the core/component's about page, provide a link to release notes providing details of the contents of the release.
-$ mv isis-0.x.x-incubating isis
-$ find isis -exec touch {} \;
-Finally, check that the download links are valid, as specified in downloads.html. If there are any errors or adjustments, make them directly, but remember to apply the same changes back to the source tree for the next iteration.
+* Update the [download page](../download.html) with a link to the source release zip file (under [http://dist.apache.org/dist/isis](http://dist.apache.org/dist/isis))
-The new site should become available within a couple of hours.
+* Update the version listed on the [documentation page](../documentation.html).
-12.7.4. Announce the release
-Announce the release to isis-dev@incubator.a.o mailing list.
+## Announce the release
-Use the following subject:
+Announce the release to dev@isis.apache.org mailing list.
-Subject: [ANN] Apache Isis version 0.x.x-incubating Released
-And use the following body (summarizing the main points as required):
+For example, for a release of Apache Isis Core, use the following subject:
-The Isis team is pleased to announce the release of Apache Isis version 0.x.x-incubating
+<pre>
+Subject: [ANN] Apache Isis version x.y.z Released
+</pre>
- http://incubator.apache.org/isis
+And use the following body (summarizing the main points as required):
+
+<pre>
+The Isis team is pleased to announce the release of
+Apache Isis Core version x.y.z
-<<summary of the main points of the release>>
+<i>summary of the main points of the release</i>
Full release notes are available at [1] on the Isis website.
-You can access this release directly from the Maven central repo [2], use the Maven archetype to configure an initial project [3],
-or download the release and build it from source [4].
+You can access this release directly from the Maven central repo [2],
+or download the release and build it from source [3].
Enjoy!
-The Isis team
-[1] http://incubator.apache.org/isis/release-notes-0.x.x-incubating.html
+[1] http://isis.apache.org/core/release-notes-x.y.z.html
[2] http://search.maven.org
-[3] http://incubator.apache.org/isis/quickstart-app.html
-[4] http://incubator.apache.org/isis/downloads.html
-
-
-
-
-
-12.8. Prepare for next iteration
-
-12.8.1. Merge changes from branch back into trunk
-
-Because we release from a branch, the changes made in the branch (changes to pom.xml made automatically by the release-plugin, or any manual edits) should be merged back from the release branch back into trunk. There are two ways to do this:
-
-The "official" way is to use SVN's merge command for this (using the "reintegrate" flag):
-
-$ cd .../trunk/framework
-$ svn merge --reintegrate https://svn.apache.org/repos/asf/incubator/isis/branches/0.x.x-incubating/framework .
-$ svn commit -m "reintegrating release branch 0.x.x-incubating ready for next iteration"
-However, you will find that this is very slow (the merge command alone takes something like ~1 hour) and will generate a massive change set which also will take an age to commit.
-
-Alternatively, then, you may well find it easy to perform the edits manually:
-
-one option is to use a directory comparison tool such as Beyond Compare or WinMerge to compare the branch workspace with the trunk workspace.
-
-Set the tool's filters to compare only pom.xml files, because these are the only files that the release process in the branch will have updated and require merging in.
-
-or, you could use UNIX command line tools to perform an update.
-
-The following command will locate every pom.xml and perform in place updates, saving the original file to pom.xml.bak:
-
-find . -name pom.xml -exec sed -i.bak -e 's/0\.1\.0/0\.2\.0/g' {} \;
-The above works on Cygwin, too (though you may need to fully qualified the find command as /usr/bin/find).
-
-12.8.2. Manually update versions to snapshot versions
-
-After the release there are a couple of locations where the version must be bumped up manually to the next SNAPSHOT version.
-
-12.8.2.1. Update <version> in archetype resources
-
-Open up the src/main/resources/archetype-resources/pom.xml in the [oai:quickstart-archetype] module, and update the <isis.version> property:
-
-<properties>
- <isis.version>0.x.y-incubating-SNAPSHOT</isis.version>
-</properties>
-Then commit the pom.xml file.
-
-12.8.2.2. Update skin <version>
-
-Open up the src/site/site.xml in the [oai:isis] parent module, and update the <version>:
-
-<skin>
- ...
- <version>0.x.y-incubating-SNAPSHOT</version>
-</skin>
-Then commit the site.xml file.
-
-12.8.3. Update examples etc (source code outside of trunk/framework)
-
-Finally, remember that the version in the pom.xml for any modules that are not in the release - specifically those outside of trunk/framework, such as the examples and domain-libs modules - should be manually updated also.
-
-
-
-
-
-
-12.9. Update Isis Project Incusbation Status page
+[3] http://isis.apache.org/download.html
+</pre>
-Update the Isis Project Incubation Status page to capture the new status of the project. In particular:
+### Blog post
-The News section should document the new release
+Finally, [log onto](https://blogs.apache.org/roller-ui/login.rol) the [Apache blog](http://blogs.apache.org/isis/) and create a new post. Copy-n-paste the above mailing list announcement should suffice.
-The Project Info section should be reviewed and updated if required
-Any links to missing Incubation status reports should be added
+## Prepare for next iteration
-The file is updated by checking out and editing the following file from SVN:
+### Merge changes from branch back into `master` branch
-https://svn.apache.org/repos/asf/incubator/public/trunk/site-author/projects/isis.xml
+Because we release from a branch, the changes made in the branch (changes to `pom.xml` made by the `maven-release-plugin`, or any manual edits) should be merged back from the release branch back into the `master` branch:
-For additional information, see this guidance on the incubator website.
+<pre>
+git checkout master # update master with latest
+git pull
+git checkout release/x.y.z # apply release commits onto master
+git rebase master
+git checkout master
+</pre>
+Next, do a sanity check that everything builds ok:
+<pre>
+rm -rf ~/.m2/org/apache/isis
+mvn clean install
+</pre>
+Finally, and run up an Isis application
+### Update `STATUS` file
+The trunk holds a [STATUS](https://git-wip-us.apache.org/repos/asf/isis/repo?p=isis.git;a=blob_plain;f=STATUS;hb=HEAD) file which is a brief summary of the current status of the project. Update this file with details of the release.
+### Push changes
+Finally, push the changes up to origin:
+<pre>
+git fetch # check no new commits on origin/master
+git push
+</pre>
+<!--
+TODO: may need to reinstate something like this
+### Manually update versions to snapshot versions
-##Post-Release
+After the release there are a couple of locations where the version must be bumped up manually to the next SNAPSHOT version.
-### Merge changes back to mainline
+#### Update `<version>` in archetype resources
-TODO: to document.
+Open up the `src/main/resources/archetype-resources/pom.xml` in the `oai:quickstart-archetype` module, and update the `<isis.version>` property:
-### Close All JIRA tickets for the release
+<pre>
+<properties>
+ <isis.version>x.y.z-SNAPSHOT</isis.version>
+</properties>
+</pre>
-All JIRA tickets for the release should be closed, or moved to future releases if not yet addressed.
+Then commit the `pom.xml` file.
-### Update CMS site with release notes
+#### Update skin <version>
-For the completed release, use JIRA to generate release notes using the procedure documented [here](http://confluence.atlassian.com/display/JIRA/Creating+Release+Notes). If any of the tickets closed are tasks/subtasks, then please edit the contents of the file to associate them back together again.
+Open up the `src/site/site.xml` in the `oai:isis` parent module, and update the `<version>`:
-Then, update the appropriate section of the CMS site:
+<pre>
+<skin>
+ ...
+ <version>x.y.z-SNAPSHOT</version>
+</skin>
+</pre>
-- on the [documentation page](../documentation.html) clearly indicate the latest version of the core or component just released
-- a the core or component's about page, provide a link to release notes providing details of the contents of the release.
+Then commit the `site.xml` file.
+-->
<!--
@@ -790,14 +830,3 @@ Then, update the appropriate section of
TODO: some sort of process required here...
-->
-
-### Update `STATUS` file
-
-The trunk holds a [STATUS](https://git-wip-us.apache.org/repos/asf/isis/repo?p=isis.git;a=blob_plain;f=STATUS;hb=HEAD) file which is a brief summary of the current status of the project. Update this file with details of the release.
-
-<!--
-DEFUNCT
-### Update downloads.apt.vm
-
-The website's `src/site/apt/downloads.apt.vm` file lists (what will be) the current release, along with any archived releases. Update this to reflect how things will be once the release is complete.
--->
\ No newline at end of file
Modified: isis/site/trunk/content/contributors/release-snapshot.md
URL: http://svn.apache.org/viewvc/isis/site/trunk/content/contributors/release-snapshot.md?rev=1420373&r1=1420372&r2=1420373&view=diff
==============================================================================
--- isis/site/trunk/content/contributors/release-snapshot.md (original)
+++ isis/site/trunk/content/contributors/release-snapshot.md Tue Dec 11 20:06:09 2012
@@ -1,9 +1,14 @@
Title: Deploying a Snapshot Release
-{stub
-This page is a work-in-progress; it needs to be updated with respect to the [release process](release-process.html) for multiple releasable modules.
+
+Apache Isis consists of a number of separately releasable modules; see the main [release process](release-process.html) documentation for full details. All the non-core components depend on the `core`, and use the `core`'s parent `pom.xml` as their parent pom.
+
+{note
+Unless otherwise stated, you should assume that the steps described here are performed in the base directory of the module being released.
}
+
+## Prerequisites
Before you start, make sure you've defined the snapshots repo in your local `~/.m2/settings.xml` file:
<pre>
@@ -29,10 +34,27 @@ It is also possible to configure to use
### Sanity Check
-Before deploying the snapshot, perform a quick sanity check:
+Before deploying the snapshot, perform a quick sanity check.
+
+First, delete all Isis artifacts from your local Maven repo:
+
+<pre>
+rm -rf ~/.m2/repository/org/apache/isis
+</pre>
+
+Next, check that the releasable module builds independently. The build process depends on whether the artifact is of Isis core or of one of its components:
+
+* For Isis core, build using the `-o` offline flag:
+
+ `mvn clean install -o`
+
+ Confirm that the versions of the Isis artifacts now cached in your local repository are correct.
+
+* For an Isis component, build without the offline flag; Maven should pull down the component's dependencies from the Maven central repo:
+
+ `mvn clean install`
-* builds ok (`mvn clean install`)
-* an example app runs ok
+ Confirm that the versions of the Isis artifacts now cached in your local repository are correct (both those pulled down from Maven central repo, as well as those of the component built locally).
### Deploy All Modules
@@ -47,7 +69,7 @@ This will deploy all the modules that ma
To confirm that they are present, browse to Apache's [Nexus repository manager](https://repository.apache.org) and search for "isis".
{note
-The deploy process is liable will take a long time. Go grab a bite of lunch.
+Depending on the module being released, the deploy process could take a long time. Go grab a bite of lunch.
}
Added: isis/site/trunk/content/contributors/resources/nexus-staging-1.png
URL: http://svn.apache.org/viewvc/isis/site/trunk/content/contributors/resources/nexus-staging-1.png?rev=1420373&view=auto
==============================================================================
Binary file - no diff available.
Propchange: isis/site/trunk/content/contributors/resources/nexus-staging-1.png
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: isis/site/trunk/content/contributors/resources/nexus-staging-2.png
URL: http://svn.apache.org/viewvc/isis/site/trunk/content/contributors/resources/nexus-staging-2.png?rev=1420373&view=auto
==============================================================================
Binary file - no diff available.
Propchange: isis/site/trunk/content/contributors/resources/nexus-staging-2.png
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: isis/site/trunk/content/contributors/resources/nexus-staging-3.png
URL: http://svn.apache.org/viewvc/isis/site/trunk/content/contributors/resources/nexus-staging-3.png?rev=1420373&view=auto
==============================================================================
Binary file - no diff available.
Propchange: isis/site/trunk/content/contributors/resources/nexus-staging-3.png
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: isis/site/trunk/content/contributors/resources/nexus-staging-4.png
URL: http://svn.apache.org/viewvc/isis/site/trunk/content/contributors/resources/nexus-staging-4.png?rev=1420373&view=auto
==============================================================================
Binary file - no diff available.
Propchange: isis/site/trunk/content/contributors/resources/nexus-staging-4.png
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Modified: isis/site/trunk/content/contributors/verifying-releases.md
URL: http://svn.apache.org/viewvc/isis/site/trunk/content/contributors/verifying-releases.md?rev=1420373&r1=1420372&r2=1420373&view=diff
==============================================================================
--- isis/site/trunk/content/contributors/verifying-releases.md (original)
+++ isis/site/trunk/content/contributors/verifying-releases.md Tue Dec 11 20:06:09 2012
@@ -1,38 +1,53 @@
Title: Verifying Releases
-12.6.2. Other contributors cast their vote
+Whenever a committer announces a vote on a release on the [dev mailing list](../support.html), it is the responsibility of the project's PMC to cast their vote on the release. Any other ASF member may also vote.
-It is the responsibility of other contributors (or any ASF member) to cast their vote on the release. This section provides some guidance on this process.
+This page provides some guidance on what a voter is expected to verify before casting their vote.
-12.6.2.1. Verifying the source release artifacts
+## Verifying the source release artifacts
Download both the ZIP and .ASC files from the location specified in the voting email. To verify that the signature is correct, use:
-gpg --verify isis-x.x.x-incubating.zip.asc isis-x.x.x-incubating.zip
-The ZIP file should then be unpacked.
+<pre>
+gpg --verify isis-x.y.z.zip.asc isis-x.y.z.zip
+</pre>
-Once unpacked, it is recommended that voters at a minimum sanity check the contents, as per Section 12.1.2, ÎéÎíSanity checkÎéÎí.
+### Building the source release artifacts
-In particular, when building locally, confirm that the versions in your local repository (~/.m2/repository/org/apache/isis) are correct.
+Assuming the ZIP file verifies, it should be unpacked, and then the artifact built from source.
-12.6.2.2. Verifying the binary release artifacts
+First, delete all Isis artifacts from your local Maven repo:
-Optionally, voters can verify the binary releases (in the Maven staging repository). For this it is necessary to download each artifact from Nexus and its corresponding .ASC file. Since there are many such artifacts, we suggest you just choose one or two at random.
+<pre>
+rm -rf ~/.m2/repository/org/apache/isis
+</pre>
-12.6.2.3. Casting a Vote
+The build process depends on whether the artifact is of Isis core or of one of its components:
-When the above checks have been made (and any other checks that the voter thinks is relevant), they should cast a vote by replying to the email thread above.
+* For Isis core, build using the `-o` offline flag:
-12.6.3. After the isis-dev vote
+ `mvn clean install -o`
-Once the vote has completed, post the results to the isis-dev mailing list.
+ Confirm that the versions of the Isis artifacts now cached in your local repository are correct.
-Use the following subject:
+* For an Isis component, build without the offline flag; Maven should pull down the component's dependencies from the Maven central repo:
-[RESULT] [VOTE] Apache Isis release 0.x.x-incubating
-with the body:
+ `mvn clean install`
-The vote has completed with the following result :
+ Confirm that the versions of the Isis artifacts now cached in your local repository are correct (both those pulled down from Maven central repo, as well as those of the component built locally).
- +1 (binding): <<list of names>>
- +1 (non binding): <<list of names>>
+The above steps are the bare minimum you should perform before casting a vote. Ideally, you should also run an Isis application (eg one of the examples) against the new code (either against a new version of core, or configured to use the new version of the component).
+
+## Verifying the binary release artifacts
+
+Optionally, you can verify the binary releases (in the Maven staging repository). For this it is necessary to download each artifact from Nexus and its corresponding .ASC file. Since there are many such artifacts, just verify one or two at random.
+
+
+<!--
+TODO: use the other creadur tools
+-->
+
+
+## Casting a Vote
+
+When you have made the above checks (and any other checks you think may be relevant), cast your vote by replying to the email thread on the mailing list. If you are casting `-1`, please provide details of the problem(s) you have found.
Modified: isis/site/trunk/content/documentation.md
URL: http://svn.apache.org/viewvc/isis/site/trunk/content/documentation.md?rev=1420373&r1=1420372&r2=1420373&view=diff
==============================================================================
--- isis/site/trunk/content/documentation.md (original)
+++ isis/site/trunk/content/documentation.md Tue Dec 11 20:06:09 2012
@@ -52,11 +52,9 @@ Title: Documentation
### Committers
- [Updating the CMS site](contributors/updating-the-cms-site.html)
-- [Release snapshot](contributors/release-snapshot.html) [wip]
-- [Release process](contributors/release-process.html) [wip]
-<!--
-- [Verifying releases](contributors/verifying-releases.html) [wip]
--->
+- [Release snapshot](contributors/release-snapshot.html)
+- [Release process](contributors/release-process.html)
+- [Verifying releases](contributors/verifying-releases.html)
- [Key Generation](contributors/key-generation.html)
}