This process has changed significantly since the SVN days.
Releasing ModeShape is typically done by the project lead (or another integration manager only after communicating with the project lead). This document outlines the basic process, which is as follows:
- Update the 'release_notes.md' file
- Verify the branch builds successfully
- Mark the release in JIRA
- Run the release script
- Update the 'latest' symbolic link on JBoss.org
- Check and promote the artifacts in the JBoss.org Maven repository staging area
- Build and upload the quickstarts
- Update the project's site (using Magnolia)
- Announce the release
- Thank contributors
- Change the banner in irc.freenode.net#modeshape
Each of these steps is described in more detail below.
0. Prerequisites
You must have all of the following abilities in order to perform a release:
- JIRA administration privileges for ModeShape
- Write privilege on the official ModeShape Git repository on GitHub.
- Connect to file management machines at JBoss.org
- Use the Magnolia content management system for the ModeShape project site at JBoss.org
- Log into the JBoss.org Maven repository to close staged repositories
- Update the official ModeShape blog and Twitter accounts
- Update the banner in the ModeShape IRC room
1. Update 'release_notes.md'
Edit the 'release_notes.md' file in the source code to reflect the upcoming release, commit it, and push to your ModeShape fork. This file uses Markdown syntax, which is a format that is designed to be easily editable while also convertible to HTML. The release script actually converts it to both HTML and text. For details about this format, see the Markdown syntax rules and documentation.
2. Verify the branch builds successfully
Switch to your local Git clone of the official ModeShape Git repository, and pull all recent changes. Note that you may need to merge the changes to the 'release_notes.md' file from Step 1.
Then run an assembly build to ensure that the current state of the code base builds successfully, that all unit and integration tests pass, and that all documentation and assemblies are produced:
$ mvn -Passembly clean install
This is basically a test run of what the release process will do (without requiring all the cleanup that a dry-run will entail).
Check the results, including the assemblies and JavaDoc folders in 'modeshape-distribution/target'. If everything looks good, continue with the next step.
3. Mark the release in JIRA
Once you know the software builds successfully, go to JIRA administration to mark the version as "Released". Before you do, make sure the version name follows JBoss conventions (e.g., "3.6.0.Final", not "3.6").
4. Run the release script
The release script automates most of the work of producing and publishing the actual software artifacts. The script can be run in two modes: the regular mode and a 'dry-run' mode. The 'dry-run' mode is sort of a practice mode that goes through all of the motions of the release, including:
- verify that the local Git repository is a writable clone of the official ModeShape Git repository on GitHub;
- create a local branch for the new release;
- change the project-related versions in the POM files and documentation;
- commit those changes locally;
- create a tag for the release;
- generate the release notes in multiple formats;
- generate emails to all the people who have filed, commented on, or worked on issues fixed in this release;
- run a full assembly build of the software to product all artifacts and documentation; and
- place a copy of all artifacts and documentation in the '../archive' folder
When running in regular mode, the script does all of the above steps plus several more:
- deploy all artifacts to the JBoss.org Maven repository in a staging area (authorization required)
- upload all artifacts and documentation to JBoss.org (authorization required); and
- push the commit and tag to the official Git repository (authorization required)
The script is located in the ModeShape Git repository at 'bin/release.py' and is written in Python, which is available on most platforms. To execute the script, simply use the following command to display the built-in help explaining the various arguments and options:
$ bin/release.py --help
It's always best to first run the script in dry-run mode. Be sure the version exactly matches the name of the version in JIRA. For example, the following is the command to do a dry-run of releasing "2.5.0.Final" from the 'master' branch:
$ bin/release.py --dry-run --verbose 2.5.0.Final
This typically takes 10-20 minutes (depending upon your machine), since it runs all of the steps outlined above. Running all the tests and building the JavaDoc are quite time-consuming. When this completes, the archive of the information is placed in the '../archive/<version>' folder (relative to where the script is run), and all the files that would be deployed to JBoss.org are placed in the '~/modeshape_release_dry_run' folder. Before continuing, check that this folder contains all the expected information. If not, do not continue, and contact the project admin.
If you get a cryptic error from the release script somewhere in the "__get_issues_from_jira" method, double check that the JIRA version exactly matches the release number (e.g., "3.6.0.Final").
If the dry run was successful, you need to delete the '../archive/<version>' and '~/modeshape_release_dry_run' folders, and then run the script again in the regular mode (without the '--dry-run' option). For example:
$ bin/release.py --verbose 2.5.0.Final
This will take longer than the dry run, because it copies all of the documentation and downloads to JBoss.org and pushes the commit and tag to the official Git repository. When it completes successfully, verify that the official Git repository on GitHub contains the correct tag.
You can then continue with the next step.
5. Update the 'latest' symbolic link on JBoss.org
The release script uploaded all of the documentation and downloads to JBoss.org. However, it doesn't change the 'latest' symbolic link to point to the latest version, so you have to do this manually using SFTP:
$ sftp modeshape@filemgmt.jboss.org Connecting to filemgmt.jboss.org... sftp> cd /docs_htdocs/modeshape sftp> rm latest sftp> ln 2.5.0.Beta1 latest sftp> exit
This change will be pushed to the public site a short time later during the next automated synchronization.
UPDATE: This step is no longer required.
6. Promote the artifacts in the JBoss.org Maven repository staging area
The release script used Maven to deploy the artifacts to a staging area within the JBoss.org Maven repository. You need to review these artifacts, test them, and if all is found acceptable close the staging area. (Most of this process, including setup, is covered on the Maven Deploying a Release page.)
After closing the staging area, you should test the staged artifacts by using them in a build of the ModeShape examples Git repository. The first time you do this, set up a 'settings-staging.xml' file in your ~/.m2 directory (see the Maven Staging Settings page for details), and then clone the examples Git repository:
$ git clone https://github.com/ModeShape/modeshape-examples $ cd modeshape-examples
Now, each release needs to be tested. Change the ModeShape version used in the examples to the newly staged version, and save the file.
Then, be sure that your local Maven staging repository (e.g., "~/.m2/repository-staging" defined in the "settings-staging.xml" file) is empty:
$ rm -rf ~/.m2/repository-staging
and then build the examples using your staged settings:
$ mvn -s ~/.m2/settings-staging.xml clean install $ rm -rf ~/.m2/repository-staging
Commit the change to use the latest version and (if you have privilege) push the commit to the Git repository on GitHub:
$ git commit -m "Changed to use release 2.5.0.Final" . $ git push origin master
Then go back to Nexus and release your staging area to push the artifacts out into the public Maven repository, which will then push the same artifacts into Maven Central (though this may take some time).
Now all the hard work has been done, and all of the software and documentation has been published. All that remains is to document the release and make the announcements. So the next step is updating the project's site.
7. Build and upload the quickstarts
Once the ModeShape artifacts have been released and published on Nexus, the next steps are to update the Quickstarts to use the new release, create the quickstart distribution, and upload it to the project's downloads area.
$ git clone https://github.com/ModeShape/quickstart $ cd quickstart
Edit the various POMs to change the version of the quickstarts and the ModeShape version. Then, build the distribution:
$ mvn clean install -Pdist
If this works, upload the distribution to the JBoss downloads area (using the appropriate ModeShape version on line 3):
$ cd dist/target $ sftp modeshape@filemgmt.jboss.org sftp> cd /downloads_htdocs/modeshape/3.6.0.Final sftp> put modeshape-quickstarts-*.zip sftp> exit
Then commit the changes to the quickstarts:
$ git commit -m "Changed to use release 3.6.0.Final" . $ git push origin master
8. Update the project's site
JBoss.org uses Magnolia for its content management system. Log into the ModeShape account on Magnolia, update the downloads and documentation pages, update the main page, and create an announcement of the release. Then publish all of the modified pages.
9. Announce the release
Releases are typically announced in multiple places to tell as many people as possible:
- A blog post on the official ModeShape blog (see some older posts for examples);
- Tweet from the @modeshape and @jbossdeveloper Twitter accounts, typically referencing the blog post (e.g., "ModeShape 2.5.0.Beta1 has been released. Get all the details: http://bit.ly/eRvg0g #jcr")
- An announcement and discussion thread on the ModeShape forums;
- An email with a summary and link to the blog post, sent to modeshape-dev@lists.jboss.org, modeshape-users@lists.jboss.org, and modeshape-announce@lists.jboss.org; and
- An email to internal Red Hat mailing lists with a similar announcement
10. Thank contributors
A recent addition to the ModeShape release process is sending a thank you email to each of the people that have filed, commented on, or worked on the JIRA issues fixed in the release. This is made possible by a custom plugin on the JBoss.org JIRA that generates a report with this information, but it still wasn't as easy as we'd like it to be.
Our release script automatically generates these emails and makes it very easy for you to review and send them. When it is run, the release script accesses the JIRA contribution report for the release, accesses JIRA to find the information about each issue, generates an email for each of the contributors, and generates an HMTL page (called 'contributions.html' located in the generated archive folder) with a mailto link for each contributor.
Simply open this file, click on each link to open the email in your email client (with the To, Subject and body filled in automatically), then review and send each one. Each email contains the list of JIRAs that the contributor has affected, and thanks them for their contribution and effort. A sample is included below:
Hello Jane, Thank you for participating in the ModeShape community. We've recently released ModeShape 2.5.0.Beta1, and you've played an important part in this release by helping identify and solve the following issues: - MODE-1048 [1] - If initialContent file is not a valid location - MODE-1078 [2] - NPE when LockManager attempts to process a change from cluster. - MODE-1112 [3] - Pushing changes upstream that enable building ModeShape in Mead For more details about ModeShape and the new 2.5.0.Beta1 release, please see the project website at http://www.jboss.org/modeshape. We greatly appreciate your contribution as it helped us make ModeShape better for you as well as for other users. Please keep up the good work, and we encourage you to continue to give us feedback and play an active role in the ModeShape community. Thank you very much, --The ModeShape team [1] https://issues.jboss.org/browse/MODE-1048 [2] https://issues.jboss.org/browse/MODE-1078 [3] https://issues.jboss.org/browse/MODE-1112
10. Update the banner in irc.freenode.net#modeshape
The final step is to update the banner in ModeShape's IRC room on freenode.net. This can be done issuing the following commands into your IRC client after you've authenticated:
/msg ChanServ op #modeshape topic #modeshape <YOUR NEW TOPIC ANNOUNCING THE RELEASE>
For example, the new banner might be:
Welcome to ModeShape! This is where we discuss JCR, federation, connectors, sequencers, and such. New -- ModeShape 2.5.0.Beta1 http://bit.ly/eRvg0g
If your message contains a URL to the blog post, you'll want to use a shortened URL using a service such as http://bit.ly.
Comments