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 manager privileges on the Fedora Repository Drupal site.
- 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
- Your maven settings.xml includes the following:
<settings> ... <servers> ... <server> <id>sonatype-nexus-snapshots</id> <username>your-jira-id</username> <password>your-jira-pwd</password> </server> <server> <id>sonatype-nexus-staging</id> <username>your-jira-id</username> <password>your-jira-pwd</password> </server> <server> <id>github</id> <username>your-github-id</username> <password>your-github-pwd</password> </server> </servers> ... </settings>
Note about encrypted passwords
Encrypted passwords works for the plugin that references the sonatype-nexus passwords, but NOT the one that uses github. To avoid a cryptic error, enter your github password in plaintext.
Ensure you have a trusted code signing key
- create one if you haven't before
- ensure that it's listed within the contributor keys
Prepare and distribute test plan
The test plan should also be ready prior to code freeze.
It should include:
- 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 branch 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.
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.
- fcrepo-build-tools: if schedule for a release, must be handled first since it's version number is present in the other modules
- fcrepo4: the main project, always part of a release, takes the vast majority of the time
- fcrepo-message-consumer
- fcrepo-module-auth-rbacl
- fcrepo-module-auth-xacml
- fcrepo-sample-dataset (no push to sonatype, just version bump)
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
It may be best to create fresh clones of the to-be-released projects, perhaps in well-named release folder. Leaving these directories pristine may help in the event that you wish to roll back or otherwise deal with an unexpected error.
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:
mvn checkout -b local-release mvn release:clean mvn release:prepare -DdryRun -DreleaseVersion=X.X.X -DdevelopmentVersion=X.X.Y-SNAPSHOT -DautoVersionSubmodules -DpushChanges=false mvn release:clean && mvn release:prepare -DreleaseVersion=X.X.X -DdevelopmentVersion=X.X.Y-SNAPSHOT -DautoVersionSubmodules -DpushChanges=false
- Review the local commits for correctness
- Remove/or move local Maven repository
mv ~/.m2/repository ~/.m2/repository-yyyy-mm-dd
- Checkout tag
- Build/Test release tag
git checkout <release-tag> mvn clean install
- Push tags and commits to GitHub
Up until this point, all of the changes made are strictly in your local repository and working directory. From this point on, the changes you make will be visible to the world and in some cases difficult to back-out of.
git checkout local-release 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
Point of no return
The following steps, once completed are final. They cannot be undone, revoked or altered. Only proceed if you've completed all the above steps and are absolutely certain the release is ready for publication.
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, fcrepo-message-consumer, fcrepo-module-auth-xacml, etc
Troubleshooting site-deploy
Error creating blob: API rate limit exceeded
Github only allows a certain number of requests per hour. Once that number is hit you'll have to wait an hour before resuming your operation. The site documentation may exhaust this limit several times.
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
compute-checksums.shexport RELEASE_VERSION=4.0.0-beta-01 sha1sum fcrepo-webapp-$RELEASE_VERSION.war |cut -f1 -d' ' > fcrepo-webapp-$RELEASE_VERSION.war.sha1 md5sum fcrepo-webapp-$RELEASE_VERSION.war |cut -f1 -d' ' > fcrepo-webapp-$RELEASE_VERSION.war.md5 sha1sum fcrepo-webapp-$RELEASE_VERSION-jetty-console.war |cut -f1 -d' ' > fcrepo-webapp-$RELEASE_VERSION-jetty-console.war.sha1 md5sum fcrepo-webapp-$RELEASE_VERSION-jetty-console.war |cut -f1 -d' ' > fcrepo-webapp-$RELEASE_VERSION-jetty-console.war.md5 sha1sum fcrepo-webapp-$RELEASE_VERSION-auth.war |cut -f1 -d' ' > fcrepo-webapp-$RELEASE_VERSION-auth.war.sha1 md5sum fcrepo-webapp-$RELEASE_VERSION-auth.war |cut -f1 -d' ' > fcrepo-webapp-$RELEASE_VERSION-auth.war.md5 sha1sum fcrepo-message-consumer-webapp-$RELEASE_VERSION.war |cut -f1 -d' ' > fcrepo-message-consumer-webapp-$RELEASE_VERSION.war.sha1 md5sum fcrepo-message-consumer-webapp-$RELEASE_VERSION.war |cut -f1 -d' ' > fcrepo-message-consumer-webapp-$RELEASE_VERSION.war.md5 sha1sum fcrepo-message-consumer-webapp-$RELEASE_VERSION-jetty-console.war |cut -f1 -d' ' > fcrepo-message-consumer-webapp-$RELEASE_VERSION-jetty-console.war.sha1 md5sum fcrepo-message-consumer-webapp-$RELEASE_VERSION-jetty-console.war |cut -f1 -d' ' > fcrepo-message-consumer-webapp-$RELEASE_VERSION-jetty-console.war.md5
- Upload artifacts to GitHub release (war, war.md5, war.sha1)
Complete the Duraspace wiki documentation updates
Current Fedora Repository Documentation wiki: https://wiki.duraspace.org/display/FEDORA36
At the very minimum, update the following:
This section needs updating - A.Woods 2014-01-02
If this is a new major or minor point release, copy the previous point release documentation to create the current wiki (/FEDORA XY ), then update accordingly. Mark the new pages as current, and update the pages in the previous documentation to indicate they are out-of-date.
If this is a maintenance point release, create separate child release note pages for each release covered by the documentation (see https://wiki.duraspace.org/display/FEDORA36/Release+Notes for an example).
Otherwise, post the release notes in the Release Notes page (see https://wiki.duraspace.org/display/FEDORA35/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.
Update the Fedora Repository site
Fedora Repository site (Drupal): http://www.fedorarepository.org/
Sitemap: http://www.fedora-commons.org/sitemap
- Copy Software -> Current Release to Software -> Previous Releases -> Release X.Y
Move Release X.Y to the top of the list of release pages.
Change state to published in green view tab, state: in green right-hand drop-down menu
Select Release X.Y as the default page to display for the Previous Releasesfolder:- navigate to Previous Releases folder
- select green view tab
- select display drop-down menu
- select change content item as default view...
- Edit Software -> Current Release to refer to the new version of the software
- Edit the Software page to update the Download link: http://downloads.sourceforge.net/fedora-commons/fcrepo-installer-X.Y.jar
- Edit the Homepage:
- select Manage Portlets
- select the Current Releases portlet.
- update the link to the installer: http://downloads.sourceforge.net/fedora-commons/fcrepo-installer-X.Y.jar
- update the link to the source: https://github.com/fcrepo/fcrepo/zipball/vX.Y
- Edit the Announcementsfolder:
- add a Fedora Repository X.Y.Z Released page
- move the page to top of Announcements list
- change state the state of the page to published
- expire previous release announcement page
In the Software section:
- Make sure the default view for the Fedora Repository reflects the new release
- Update the previous version to point to the archived documentation
- Make sure the license information is up-to-date with the latest release
On the homepage:
- Make sure the link to the current version goes to the right place and is labeled properly.
Announce release
Let Carol Minton Morris know that the release is complete and can be announced.
Depending on the significance of the release, the announcement will be disseminated in various forms to:
- The DuraSpace blog
- The fedorarepository.org homepage (as a news item)
- Twitter (@FedoraRepo, others)
- Mailing lists (fedora-community, fedora-tech, fedora-advisors, fedora-steering)