The version number of the parent pom should reflect the branch name that you are now on (with a -SNAPSHOT suffix). In many cases this will have been done already during earlier development; but confirm that it has been updated. If it has not, make the change.

For example, if releasing core version 1.9.0, the POM should read:

If releasing Isis Core, check (via search.maven.org) whether there is a newer version of the Apache parent org.apache:apache.

If there is, update the <version> in the <parent> element in the parent POM to match the newer version:

where NN is the updated version number.

There should be no snapshot dependencies; the only mention of SNAPSHOT should be for the Isis modules about to be released.

As a quick check, do a grep for SNAPSHOT:

Or, for a more thorough check, load up each pom.xml and inspect manually:

The maven-versions-plugin should be used to determine if there are newer versions of any of the plugins used to build Isis. Since this goes off to the internet, it may take a minute or two to run:

Review the generated output and make updates as you see fit. (However, if updating, please check by searching for known issues with newer versions).

The maven-versions-plugin should be used to determine if there are newer versions of any of Isis' dependencies. Since this goes off to the internet, it may take a minute or two to run:

Update any of the dependencies that are out-of-date. That said, do note that some dependencies may show up with a new dependency, when in fact the dependency is for an old, badly named version. Also, there may be new dependencies that you do not wish to move to, eg release candidates or milestones.

For example, here is a report showing both of these cases:

For these artifacts you will need to search Maven central repo directly yourself to confirm there are no newer dependencies not shown in this list.

Make sure that all source code has been cleaned up and formatted according to the Apache Isis and ASF conventions. Use this Eclipse template and this import order.

The Apache Release Audit Tool RAT (from the Apache Creadur 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:

where rat.numUnapprovedLicenses property is set to a high figure, temporarily overriding the default value of 0. This will allow the command to run over all submodules, rather than failing after the first one.

All being well the command should complete. For each failing submodule, it will have written out a target\rat.txt; missing license notes are indicated using the key !???. You can collate these together using something like:

Investigate and fix any reported violations, typically by either:

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"]:

Run this in dry run mode first (shown here relative to the core module):

When happy, perform the updates by specifying the -x (execute) flag:

Once you’ve fixed all issues, confirm once more that apache-rat-plugin no longer reports any license violations, this time leaving the rat.numUnapprovedLicenses property to its default, 0:

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, relative to the root of each releasable module.

To capture the missing license information, use:

This Maven plugin creates a license.xml file in the target/generated-resources directory of each module.

Then, run the following script (shown here relative to the core module).

This searches for all licenses.xml files, and compares them against the contents of the supplemental-models.xml file. For example, the output could be something like:

If any missing entries are listed or are spurious, then update supplemental-models.xml and try again.

First, check that there are NO SNAPSHOT dependencies in any of the pom.xml of the modules of the core.

Next, delete all Isis artifacts from your local Maven repo:

Next, check that core builds independently, using the -o offline flag:

Confirm that the versions of the Isis artifacts now cached in your local repository are correct.

You should already have changed the parent POM of the releasable module to reference a released version of org.apache.isis.core:isis. Now, also check that there are remaining NO SNAPSHOT dependencies in any of the pom.xml of the modules of the component.

Next, delete all Isis artifacts from your local Maven repo:

Next, build the component, though without the offline flag. Maven should pull down the component’s dependencies from the Maven central repo, including the non-spshot of Isis core:

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). The versions of core should not be a SNAPSHOT.

Run the dry-run as follows:

where:

This is not quite fully automated; you may be prompted for the gpg passphrase. (Experiments in using --batch-mode -Dgpg.passphrase="…​" to fully automate this didn’t work; for more info, see here (maven release plugin docs) and here (maven gpg plugin docs).

Or, if you want to be prompted for the versions, you can omit the properties, eg:

Some modules might have additional profiles to be activated. For example, the (now mothballed) SQL ObjectStore required -P apache-release,integration-tests so that its integration tests are also run.

This should generate something like:

If you didn’t provide the releaseVersion, tag and developmentVersion tags, then you’ll be prompted for them. You can generally accept the defaults that Maven offers.

Assuming this completes successfully, re-run the command, but without the dryRun flag and specifying resume=false (to ignore the generated release.properties file that gets generated as a side-effect of using git). You can also set the skipTests flag since they would have been run during the previous dry run:

You should end up with artifacts in your local repo with the new version 1.9.0. There are then a couple of sanity checks that you can perform:

If you find problems and the release was performed on a branch, then just delete the branch and start over.

If running on *nix, then the command to stage the release is:

but if using mSysGit on windows, specify a different working directory:

You may (again) be prompted for gpg passphrase.

The command starts off by checking out the codebase from the tag (hence different working directory under Windows to avoid 260 char path limit). It then builds the artifacts, then uploads them to the Apache staging repository:

All being well this command will complete successfully. Given that it is uploading code artifacts, it could take a while to complete.

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 (using your ASF LDAP account):

And then check that the release has been staged (select staging repositories from left-hand side):

If nothing appears in a staging repo you should stop here and work out why.

Assuming that the repo has been populated, make a note of its repo id; this is needed for the voting thread. In the screenshot above the id is org.apache.isis-008.

After checking that the staging repository contains the artifacts that you expect you should close the staging repository. This will make it available so that people can check the release.

Press the Close button and complete the dialog:

Nexus should start the process of closing the repository.

All being well, the close should (eventually) complete successfully (keep hitting refresh):

The Nexus repository manager will also email you with confirmation of a successful close.

If Nexus has problems with the key signature, however, then the close will be aborted:

Use gpg --keyserver hkp://pgp.mit.edu --recv-keys nnnnnnnn to confirm that the key is available.

Finally, push both the branch and the tag created locally to the central origin server. For the tag, we append an -RCn suffix until the vote succeeds.

To push the branch, for example:

To push the tag, with the -RCn suffix, for example:

The remote tag isn’t visible locally (eg via gitk --all), but can be seen online.

The following boilerplate is for a release of the Apache Isis Core. Adapt as required:

Use the following subject:

And use the following body:

Remember to update:

Note that the email also references the procedure for other committers to verify the release.

If the vote has been successful, then replace the -RCn tag with another without the qualifier.

You can do this using the scripts/promoterctag.sh script; for example:

Or, if you like to execute the steps in that script by hand:

Then, continue onto the next section for the steps to promote and announce the release.

If the vote has been unsuccessful, then:

Address the problems identified in the vote, and go again.

From the Nexus pages, select the staging repository and select 'release' from the top menu.

This moves the release artifacts into an Apache releases repository; from there they will be automatically moved to the Maven repository.

As described in the Apache documentation, each Apache TLP has a release/TLP-name directory in the distribution Subversion repository at 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/ 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:

If necessary, checkout this directory structure:

Next, add the new release into the appropriate directory, and delete any previous release. You can use the upd.sh script to help; this downloads the artefacts from the Nexus release repository, adds the artefacts to subsversion and deletes the previous version.

At the end, commit the changes:

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.

Use JIRA to generate release notes:

<img src="resources/jira-create-release-notes.png" width="400px"></img>

If any of the tickets closed are tasks/subtasks, then please edit the contents of the file to associate them back together again.

In JIRA, go to the administration section for the Isis project and update the versions as released.

Update the Isis CMS website:

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).

For example, a new release of Isis Core would require:

In addition:

For more information on DOAP files, see these Apache policy docs.

Finally, log onto the Apache blog and create a new post. Copy-n-paste the above mailing list announcement should suffice.

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:

If the core was updated, then you’ll most likely need to update other POMs to the new -SNAPSHOT.

Next, do a sanity check that everything builds ok:

The trunk holds a STATUS file which is a brief summary of the current status of the project. Update this file with details of the release.

Finally, push the changes up to origin: