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.
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-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 work 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 and development branches and begin final test phase
Create a release candidate branch and a development branch, release testing wiki page and notify developers to test.
RC_VERSION=4.5.1
Using the above variables, complete the below git
commands for each module being released.
NOTE: The value of RC_VERSION
will vary for each release.
git checkout master git pull git push origin master:${RC_VERSION}-RC git push origin master:DEV
Tag the release candidate branch
git tag -a "<artifact-id>-${RC_VERSION}-RC-1" -m "<artifact-id>-${RC_VERSION}-RC-1" git push origin --tags
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:
- Follow the release order of the spreadsheet plan
- 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.
- 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
and $REPO
will vary depending on which module is being released.
ORG=fcrepo4 REPO=fcrepo-module-auth-webac CURR=4.5.1 NEXT=4.5.2-SNAPSHOT
Github Release
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
Your GPG passphrase may not be masked in terminal.
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
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.
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
Go to
https://github.com/fcrepo4/$REPO/releases/tag/$REPO-$CURR
- Click Edit tag, and update title to "Release $CURR"
- If appropriate, attach binaries and checksums that have been published to Maven Central
- e.g. http://repo1.maven.org/maven2/org/fcrepo/fcrepo-webapp/4.5.1/
- Note: The Maven artifact for fcrepo-webapp-<version>-jetty-console needs to be renamed from w
ar
tojar
.
- Click Publish Release
For fcrepo-webapp-plus you need to build and attach 4 WAR files to the release. These should be build with the commands:
mvn clean install
mvn clean install -Pwebac
mvn clean install -Paudit
mvn clean install -P\!webac,\!audit
After each build, upload the war file from the ./target
directory to the release page, they are required for the fcrepo-vagrant product.
Sonatype Release
Release the build artifacts to the Sonatype repository.
mvn release:perform -DperformRelease -Dgoals=deploy
As before, your GPG passphrase may not be masked in terminal.
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.
- 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 Pages
Update the Github Pages documentation:
mvn site-deploy -DskipTests
The pages will be visible at http://$ORG.github.io/$REPO/site/$CURR/$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
Push Release Branch to Master
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.
- Changing from SNAPSHOT version to release version. Something like [maven-release-plugin] prepare release $REPO-$CURR
- Changing from release version to next development version. Something like [maven-release-plugin] prepare for next development iteration
fcrepo-vagrant is an exception to the above rule. The master branch of fcrepo4-exts/fcrepo-vagrant is tied to the last full release version. So you don't update the Fedora version to the new SNAPSHOT version but instead leave it at the just released (${CURR}) version.
If this appears correct, you can push your release branch on to master.
git push origin HEAD:master
Because there are no changes to master after code freeze and all bug fixes are on the ${CURR}-RC branch, this will operate as a fast-forward merge.
Merge DEV branch into master
Process TBD
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:
Documentation
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)
{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
- Go to the release management page.
- For the release you just made (there should be an open package icon to the left of it)
- click the gear icon on the left and choose "release"
- enter the date you finished the release
- the package should be closed
- if you are not already listed as the release manager in the description, enter "Release Manager: your-name-here"
- Create the next release
- 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
Let Carol Minton Morris know that the release is complete and can be announced.
Ontologies
Ontologies are released on their own schedule and do not need to be released. But they should be tagged with the current version when a release is performed, to make it easy to identify the version of the ontology that each release was using.
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