This document is intended to be used and kept up to date by the Fedora Release Manager.  It details the steps necessary to perform an official release of Fedora.

The release version in the documentation below is identified as X.Y , replace this in the instructions with the current release (eg 4.0.1).
X is the major point version, Y is the minor point version, and Z is the maintenance point.

The previous release version (snapshot previous documentation) is identified as A.B , replace this with the previous release (eg 4.0).

Before Release Day

Verify release privileges

To make sure release day goes smoothly, you should ensure that:

• You have an account with commit access for the fedora project on github. As a committer, you should already have this level of access.
• You have an account with edit privileges on the duraspace.org Confluence wiki.
• You have an oss.sonatype.com account and have requested to be given permission to publish to the org.fcrepo groupId by adding a comment to the Fedora Sonatype Hosting Ticket
• You have project configuration privileges on JIRA (you'll see an error here if you don't)
• Your maven settings.xml includes the following:

Before Release Day

Verify release privileges

To make sure release day goes smoothly, you should ensure that:

• You have an account with commit access for the fedora project on github. As a committer, you should already have this level of access.
• You have an account with edit privileges on the duraspace.org Confluence wiki.
• You have an oss.sonatype.org account and have requested to be given permission to publish to the org.fcrepo groupId by adding a comment to the Fedora Sonatype Hosting Ticket
• You have project configuration privileges on JIRA (you'll see an error here if you don't)
• Your maven settings (~/.m2/settings.xml) includes the following:

<settings>
  ...
  <servers>
    ...
    <server>
      <id>sonatype-nexus-snapshots</id>
      <username>your-sonatype-id</username>
      <password>your-sonatype-pwd</password>
    </server>
    <server>
      <id>sonatype-nexus-staging<

<settings>
  ...
  <servers>
    ...
    <server>
      <id>sonatype-nexus-snapshots</id>
      <username>your-jirasonatype-id</username>
      <password>your-jirasonatyp-pwd</password>
    </server>
    <server>
      <id>sonatype-nexus-staging<<id>github</id>
      <username>your-jiragithub-id</username>
      <password>your-jiragithub-pwd</password>
    </server>
    <server></servers>
      <id>github</id>
      <username>your-github-id</username>
      <password>your-github-pwd</password>
    </server>
  </servers>
  ...
</settings>
...
</settings>

...

• create one if you haven't before
• ensure that it's listed within the contributor committer keys

Prepare and distribute test plan

...

• Which platform/configuration combinations will be tested
• Which automated tests will be run, and by whom
• Which manual tests will be run, and by whom
• Which service compatibility tests (external search, external triplestore) will be run, and by whom
• Instructions on how testers will report on test results

Create release

...

branches and begin final test phase

Create a release candidate branch, release testing wiki page and notify developers to test.

git checkout -b fcrepo-4.0.0-beta-01-RC
git push origin fcrepo-4.0.0-beta-01-RC

Update online resources

If any online resources have been modified or added to during the release, these must be updated.

Release Day

Determine which modules will be released.

Of the projects in https://github.com/fcrepo4. which should be released.  Typically we keep the release versions in sync for those that have had a formal release.

Based on the modules to be released, create a release process spreadsheet like this.

Release Order

Due to dependency chains, the following release order is required.  Furthermore, the artifacts of dependencies must be propagated to maven central before the next one can be released.

1. fcrepo-build-tools: if schedule for a release, must be handled first since it's version number is present in the other modules
2. fcrepo4: the main project, always part of a release, takes the vast majority of the time (also push gh-pages)
3. fcrepo-message-consumer (also push gh-pages)
4. fcrepo-module-auth-rbacl (also push gh-pages)
5. fcrepo-module-auth-xacml (also push gh-pages)
6. fcrepo-camel (also push gh-pages)
7. ontology (no push to sonatype)
8. --- labs below
9. fcrepo4-client (also push gh-pages)
10. fcrepo-audit (also push gh-pages)
11. fcrepo-camel-toolbox (also push gh-pages)
12. ----
13. fcrepo-webapp-plus (no push to sonatype)
14. fcrepo4-release-tests (ditto)
15. fcrepo4-oaiprovider (ditto)
16. fcrepo4-swordserver (ditto)
17. migration-utils (ditto)
18. fcrepo4-upgrade-utils (ditto)
19. ---
20. fcrepo4-vagrant (update versions)
21. fcrepo-karaf (update versions)

Merge the release candidate branch into master (if any commits were made)

git checkout fcrepo-4.0.0-beta-01-RC
git pull origin fcrepo-4.0.0-beta-01-RC
git checkout master
git merge fcrepo-4.0.0-beta-01-RC
git push origin master
git branch -d fcrepo-4.0.0-beta-01-RC
git push origin :fcrepo-4.0.0-beta-01-RC

Build and release the final distribution to Maven Central

In order to build the release make sure that:

• you have a working PGP installation with your code signing key as the default key

Run the following commands to generate and upload all built artifacts to the Sonatype staging repository (for example, X.X.X = 4.3.0 and X.X.Y = 4.3.1-SNAPSHOT) :

git checkout -b local-release
mvn release:clean
mvn release:prepare -DreleaseVersion=X.X.X -DdevelopmentVersion=X.X.Y-SNAPSHOT -DautoVersionSubmodules=true -DpushChanges=false
Note: If there are javadoc failures, use the following, then file a JIRA ticket for the next development cycle
mvn release:prepare -DreleaseVersion=X.X.X -DdevelopmentVersion=X.X.Y-SNAPSHOT -DautoVersionSubmodules=true -DpushChanges=false -Darguments="-Dmaven.javadoc.failOnError=false"

• Review the local commits for correctness (`git diff HEAD~1`, and `git diff HEAD~2`)

• Remove/or move local Maven repository

rm -rf ~/.m2/repository/org/fcrepo

• Checkout tag
• Build/Test release tag

git checkout <release-tag>
mvn clean install

• Push tags and commits to GitHub

git push origin local-release:master
git push origin --tags

• return to the release tag

git checkout <release-tag>

• Deploy to Sonatype

mvn release:perform -DperformRelease -Dgoals=deploy

Login to https://oss.sonatype.org

Find the staging repository, check that it looks good, and "Close" it. Then "Release" it. This will publish the artifacts to the Sonatype releases repository and start the process of syncing them with central. The artifacts may take several hours to reach central. When finished, they'll be available at http://repo1.maven.org/maven2/org/fcrepo.

Build GitHub documentation site

Checkout release tag for publishing the release documentation

mvn site-deploy -DskipTests
** Resume from a given module, if necessary
mvn site-deploy -DskipTests -rf <module>

Update index.html pages in branch "gh-pages" for releases projects: fcrepo4, and fcrepo-camel-toolbox

Troubleshooting site-deploy

Create GitHub release

Under GitHub account/releases, select "Draft new release".

• Write a description

• Create MD5 and SHA1 files for each of the release artifacts

  Code Block
  title compute-checksums.sh
  for x in `ls *.war`; do echo $x; md5sum $x > ${x}.md5; sha1sum $x > ${x}.sha1; done

• Upload artifacts to GitHub release (war, war.md5, war.sha1)
  • See the artifacts found in "Downloads" to know which need to be uploaded to GitHub

Complete the Duraspace wiki documentation updates

Current, in-progress Fedora Repository Documentation wiki: https://wiki.duraspace.org/display/FEDORA4x

At the very minimum, update the following:

Downloads
Release Notes

Note the version of Java against which the release was built.

If this is a new major or minor point release, copy the current, in-progress documentation to create the release wiki, then update accordingly. Mark the new pages as current, and update the pages in the previous documentation to indicate they are out-of-date.

• Add the following header to the previous major release wiki space (see: Space Admin -> Themes -> Configure Theme)

  No Format
  {note:title=Old Release} This documentation covers an old version of Fedora. Looking for another version? [See all documentation|FF:Documentation]. {note}

If this is a maintenance point release, create separate child release note pages for each release covered by the documentation.
Otherwise, post the release notes in the Release Notes page (see Fedora 4.0.0 Release Notes for an example).

Update any other documentation as needed, per changes/features added with this release.

Make sure the license and copyright information is up-to-date with this release.

Close the release in Jira, and create the next one

1. Go to the release management page.
2. For the release you just made (there should be an open package icon to the left of it)
   
   1. click the gear icon on the left and choose "release"
   2. enter the date you finished the release
   3. the package should be closed
   4. if you are not already listed as the release manager in the description, enter "Release Manager: your-name-here"
3. Create the next release
   1. enter a name (ie, Fedora 4.x.y) in the form at the top, and click Add.  If the release manager is known, enter that in the note.

Update the Fedora Repository site

Fedora Repository site (Drupal): http://www.fedorarepository.org/

• No need to perform this step until the website refactor has been performed.

Announce release

...

RC_VERSION=4.5.1

Using the above variables, complete the below git commands for each module being released.   The modules to be released are shown in the Fedora modules release plan.   A new page may need to be added for this release.   When the steps below are complete for a specific module, change the color to green, so that others know what's been done. 

NOTE: The value of RC_VERSION will vary for each release.

git checkout <master -or- maintenance-branch>
git pull
git push origin <master -or- maintenance-branch>:${RC_VERSION}-RC

Release candidate branches CANNOT have the same version property as the branch you are branching from (ie master or n.x-maintenance branch, depending on whether this is a major, minor, or patch release)  in the pom.xml file. The versions on the original branch will need to be incremented at the same time you create the release branches. You will need to pull in another community member to create a pull request with the version change, or another committer if you are going to create the pull requests yourself.

In this case, you can use the "versions-maven-plugin" to update project version numbers. See versions-maven-plugin documentation. For example:

mvn versions:set -DnewVersion=${RC_VERSION}-SNAPSHOT

Verify that the previous SNAPSHOT version is no longer anywhere in the code base.  Verify that the code base builds.  Commit the changes. 

Tag the release candidate branch

git checkout ${RC_VERSION}-RC
git tag -a "<artifact-id>-${RC_VERSION}-RC-1" -m "<artifact-id>-${RC_VERSION}-RC-1"
git push origin --tags

Then we must merge the pull requests to increment the version numbers to the master branch. 

Example: During the 4.5.1 release our branches should have the version 4.5.1-SNAPSHOT, this will be incremented on the master branch to 4.5.2-SNAPSHOT

Optional - Deploy Snapshot Artifacts

If the release candidate is coming off of a "maintenance" branch instead of master, it is possible that snapshot artifacts have not been deployed to the Sonatype snapshot repository. If this is the case, Travis will fail to build.

You can check if the snapshot artifacts exist by looking for each module. For example:

https://oss.sonatype.org/content/repositories/snapshots/org/fcrepo/fcrepo-http-commons/

If the snapshot artifacts do not exist, you can deploy them to Sonatype with the following command:

mvn -DaltDeploymentRepository=sonatype-nexus-snapshots::default::https://oss.sonatype.org/content/repositories/snapshots/ deploy -DskipTests

Build resources

These build scripts may be of use for building the set of release candidate modules.  

Once a release has been created, it should be uploaded to GitHub as a Pre-Release.   A Pre-Release should be created for fcrepo4, fcrepo-webapp-plus, and fcrepo4-vagrant.   The name should be  "Release Candidate 1 - RC_VERSION"

Notes

The vagrant release cannot be tested until after the fcrepo-webapps-plus RC files have been uploaded to GitHub, as the vagrant file relies on them being there first. 

Update online resources

If any online resources have been modified or added to during the release, these must be updated.

Release Day

Determine which modules will be released.

Create a new tab in the Fedora modules release plan spreadsheet.

Notes: 

1. Follow the release order of the spreadsheet plan
2. Some projects need pom.xml dependency version properties to be updated prior to release (e.g. fcrepo-camel-toolbox). This should be documented starting with 4.4.1.
3. fcrepo4-vagrant must have its 'install_scripts/fedora_camel_toolbox.sh' and 'install_scripts/config' scripts updated with non-SNAPSHOT non-LATEST version.

Variables Used

These variables will be used in the examples that follow.  The exact values of $ORG, $REPO, $CURR and $NEXT will vary depending on which module and version  is being released.

ORG=fcrepo4
REPO=fcrepo4
CURR=5.0.2
NEXT=5.1.0-SNAPSHOT

Github Release - part 1

Perform a clean checkout of the code from Github and prepare the release.

git clone git@github.com:$ORG/$REPO.git
cd $REPO
git checkout -b ${CURR}-RC origin/${CURR}-RC # or the release branch if named differently
mvn release:clean

If release:clean fails, you may need to revert the RC commit with git revert HEAD.  If the parent snapshot is not available, build an old version of fcrepo4 to populate it locally.

Resolve dependencies and set main versions to $CURR and dev versions to $NEXT

mvn release:prepare -DreleaseVersion=$CURR -DdevelopmentVersion=$NEXT -DautoVersionSubmodules=true -DpushChanges=false

-Darguments=-Dgpg.keyname=<Your Key ID>

Inspect/Verify local updates:

git diff HEAD~1
git diff HEAD~2 HEAD~1

These diffs should only contain changes of version numbers (from ${CURR}-SNAPSHOT to $CURR or $CURR to $NEXT) or occasionally HEAD to the current tag name ($REPO-$CURR)

Remove your local copies of Fedora artifacts to be sure of a clean build, and build the release.

rm -rf ~/.m2/repository/org/fcrepo
git checkout $REPO-$CURR # detached head state
mvn clean install

Push the changes to Github.

git push origin --tags # mvn task relies on the tag, make sure it does not collide with a branch name

Sonatype Release

Release the build artifacts to the Sonatype repository.

mvn release:perform -DperformRelease -Dgoals=deploy

-Darguments=-Dgpg.keyname=<Your Key ID>

• Go to https://oss.sonatype.org/index.html  and log in

• Click Staging Repositories in left navigation

• Search for "fcrepo" in upper right search box (project will not have $REPO in title)

• Select repository and verify that $REPO is present in the Content tab
• Click Close, then Refresh, then Release

This will publish the artifacts to the Sonatype releases repository and start the process of syncing them with Maven Central, which may take several hours. When finished, they'll be available at http://repo1.maven.org/maven2/org/fcrepo.

Github Release - part 2

• Go to https://github.com/fcrepo4/$REPO/releases/tag/fcrepo-$CURR

• Click Edit tag, and update title to "Release $CURR"
• Attach fcrepo-webapp-$CURR binaries and checksums that have been published to Maven Central to the Github release
  
  • e.g. http://repo1.maven.org/maven2/org/fcrepo/fcrepo-webapp/5.0.2/

• Build the fcrepo-webapp-$CURR-jetty-console.jar for the release using

  Code Block
  mvn clean install -Pone-click -pl fcrepo-webapp

  
  

• Create checksums for the fcrepo-webapp-$CURR-jetty-console and attach the binary and checksums to the Github release.
  • Note: The checksum files should be of the format "[checksum] [filename]" (MacOSX's md5 requires the use of the -r argument to produce the correct format. I.e. md5 -r fcrepo-webapp-5.0.2-jetty-console.jar >> fcrepo-webapp-5.0.2-jetty-console.jar.md5).
• Click Publish Release

Github Pages

Update the Github Pages documentation:

mvn site-deploy -DskipTests

fcrepo4 pages will be visible at http://docs.fcrepo.org/site/$CURR/$REPO/

Other module pages will be located at:  $ORG.github.io/$REPO/site/$CURR/fcrepo/$REPO

For fcrepo4/fcrepo4 and fcrepo4-exts/fcrepo-camel, manually add links to the current releases.  The easiest way to do this is to search for an old version number and copy/update for the current release.

Troubleshooting

Failed to execute goal com.github.github:site-maven-plugin:0.12:site (github) on project fcrepo-module-auth-rbacl: Error creating commit: Invalid request.
[ERROR] 
[ERROR] For ‘properties/name’, nil is not a string.
[ERROR] For ‘properties/name’, nil is not a string. (422)

Push Release Branch to Maintenance

The release branch has changes made since code freeze. It also contains the update to the version numbers for future development.

git checkout ${CURR}-RC # this is your local copy of the release branch 
git log

Ensure that your commit history matches the release branch's commit history, except for the two additional commits.
 

1. Changing from SNAPSHOT version to release version. Something like [maven-release-plugin] prepare release $REPO-$CURR
2. Changing from release version to next development version. Something like [maven-release-plugin] prepare for next development iteration

If this appears correct, you can push your release branch on to the maintenance branch.

git push origin ${CURR}-RC:${CURR}-maintenance

Duraspace wiki documentation updates

Current, in-progress Fedora Repository Documentation wiki: https://wiki.duraspace.org/display/FEDORA5x

At the very minimum, update the following:

• Documentation
• Downloads
• Releases
• Fedora Upgrade Notes  

Note the version of Java against which the release was built.

New Wiki Space

1. If this is a new major or minor point release, copy the current, in-progress documentation to create the release wiki, then update accordingly. Mark the new pages as current, and update the pages in the previous documentation to indicate they are out-of-date.

   1. Add the following header to the previous major release wiki space (see: Space Tools -> Look and Feel -> Sidebar, header and footer)

      No Format
      {note:title=Old Release} This documentation covers an old version of Fedora. Looking for another version? [See all documentation|FF:Documentation]. {note}

      
      

   2. Add the following header to the new release wiki space

      No Format
      {tip:title=Current Release} This documentation covers the current version of Fedora. Looking for another version? [See all documentation|FF:Documentation]. {tip}

      Make sure the license and copyright information is up-to-date with this release.

2. Update permissions on new wiki space to be like the previous space
3. Add "fedora" category to new wiki space
   1. Space Tools → Overview
4. Add logo
   1. Sidebar → Space Details
5. Remove default space pages
6. Set space "Home Page"
   1. Space Tools → Space Details
7. Ensure `noformat` and `code` macros were copied successfully (this is a bug in the Confluence "copy space" utility)
   1. e.g: First Steps
8. Update Documentation wiki page

Close the release in Jira, and create the next one

1. Go to the release management page.
2. For the release you just made (there should be an open package icon to the left of it)
   
   1. click the gear icon on the left and choose "release"
   2. enter the date you finished the release
   3. the package should be closed
   4. if you are not already listed as the release manager in the description, enter "Release Manager: your-name-here"
3. Create the next release
   1. enter a name (ie, Fedora 4.x.y) in the form at the top, and click Add.  If the release manager is known, enter that in the note.

Update the Fedora Repository site

Fedora Repository site (Drupal): http://www.fedorarepository.org/

• Update Download page based on Downloads page in wiki
• Update News on front page with release information
• Update Documentation page with link to current release documentation

Last sanity checks : 

1. Assuming a fcrepo4 release: Download and run the fcrepo-webapp-$CURR-jetty-console.jar
2. Make sure that the checksums of the artifacts published in the github release page match those in sonatype.
3. If we're talking about a maintenance release,  make sure that all commits that went into the maintenance release are also on master (where appropriate) 

Announce release

Let Carol Minton Morris know that the release is complete and can be announced.

CURR=4.5.1
ORG=fcrepo4
REPO=fcrepo-webac-ontology
git clone git@github.com:$ORG/$REPO
cd $REPO
git tag -a "$REPO-$CURR" -m "$REPO-$CURR" # except fcrepo4/ontology should be fcrepo-ontology-$CURR
git push --tags