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 [email protected]
-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 [email protected] mailing list.
+## Announce the release
-Use the following subject:
+Announce the release to [email protected] 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)
}
