Version 10

    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:


    1. Update the '' file
    2. Verify the branch builds successfully
    3. Mark the release in JIRA
    4. Run the release script
    5. Update the 'latest' symbolic link on
    6. Check and promote the artifacts in the Maven repository staging area
    7. Build and upload the quickstarts
    8. Update the project's site (using Magnolia)
    9. Announce the release
    10. Thank contributors
    11. Change the banner in


    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
    • Use the Magnolia content management system for the ModeShape project site at
    • Log into the Maven repository to close staged repositories
    • Update the official ModeShape blog and Twitter accounts
    • Update the banner in the ModeShape IRC room


    1. Update ''

    Edit the '' 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 '' 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 Maven repository in a staging area (authorization required)
    • upload all artifacts and documentation to (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/' 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/ --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/ --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 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/ --verbose 2.5.0.Final


    This will take longer than the dry run, because it copies all of the documentation and downloads to 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

    The release script uploaded all of the documentation and downloads to 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 Connecting to 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 Maven repository staging area

    The release script used Maven to deploy the artifacts to a staging area within the 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
    $ 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
    $ 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
    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 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:



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



    10. Update the banner in

    The final step is to update the banner in ModeShape's IRC room on This can be done issuing the following commands into your IRC client after you've authenticated:


    /msg ChanServ op #modeshape


    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


    If your message contains a URL to the blog post, you'll want to use a shortened URL using a service such as