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.
Table of Contents |
---|
Before Release Day
...
Code Block |
---|
<settings> ... <servers> ... <server> <id>sonatype-nexus-snapshots</id> <username>your-jirasonatype-id</username> <password>your-jirasonatype-pwd</password> </server> <server> <id>sonatype-nexus-staging</id> <username>your-jirasonatype-id</username> <password>your-jirasonatyp-pwd</password> </server> <server> <id>github</id> <username>your-github-id</username> <password>your-github-pwd</password> </server> </servers> ... </settings> |
...
- create one if you haven't before
- ensure that it's listed within the contributor committer keys
Prepare and distribute test plan
...
NOTE: The value of RC_VERSION
will vary for each release.
Code Block |
---|
git checkout <master<main -or- maintenance-branch> git pull git push origin <master<main -or- maintenance-branch>:${RC_VERSION}-RC |
Release candidate branches CANNOT have the same version property as the master branch branch you are branching from (ie main 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 master 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.
...
Then we must merge the pull requests to increment the version numbers to the master main 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 main branch to 4.5.2-SNAPSHOT
Optional - Deploy Snapshot Artifacts
If the release candidate is coming off of a "maintenance" branch instead of mastermain, 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.
...
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 fcrepo. The name should be "Release Candidate 1 - RC_VERSION"
...
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.
...
- 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
Variables Used
These variables will be used These variables will be used in the examples that follow. The exact values of $ORG
and $REPO
will ,
$REPO, $CURR and $NEXT
will vary depending on which module and version is being released.
Code Block |
---|
ORG=fcrepo4fcrepo REPO=fcrepo-module-auth-webac CURR=46.5.10.0-alpha-2 NEXT=46.50.20-SNAPSHOT |
Github Release - part 1
Perform a clean checkout of the code from Github and prepare the release.
...
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 fcrepo to populate it locally.
Resolve dependencies and set main versions to $CURR
and dev versions to $NEXT
...
Note | |||||||
---|---|---|---|---|---|---|---|
Your GPG passphrase may not be masked in terminal.
|
...
Inspect/Verify local updates:
...
Code Block |
---|
rm -rf ~/.m2/repository/org/fcrepo
git checkout $REPO-$CURR # detached head state i.e. > git checkout fcrepo-6.4.0
mvn clean install |
Warning |
---|
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.
Code Block |
---|
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
. - Note: The checksum files should be of the format "[checksum] [filename]" (MacOSX produces a different format that will not work with standard verification tools).
- Click Publish Release
Info |
---|
For fcrepo-webapp-plus you need to build and attach 4 WAR files to the release. These should be build with the commands:
After each build, upload the war file from the |
Sonatype Release
Release the build artifacts to the Sonatype repository.
Code Block |
---|
mvn release:perform -DperformRelease -Dgoals=deploy |
Note | |||||||
---|---|---|---|---|---|---|---|
As before, your GPG passphrase may not be masked in terminal.
|
Warning | ||
---|---|---|
| ||
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:
Code Block |
---|
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
Sonatype Release
Release the build artifacts to the Sonatype repository.
Code Block |
---|
mvn release:perform -DperformRelease -Dgoals=deploy |
Note | |||||||
---|---|---|---|---|---|---|---|
As before, your GPG passphrase may not be masked in terminal.
|
Troubleshooting
Expand | ||||
---|---|---|---|---|
|
Warning | ||
---|---|---|
| ||
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://s01.oss.sonatype.org 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 https://repo1.maven.org/maven2/org/fcrepo/.
Docker Release (fcrepo only)
From the cloned fcrepo repository home run the following:
Code Block |
---|
git clone git@github.com:fcrepo-exts/fcrepo-docker.git
cd fcrepo-docker
DOCKER_PASSWORD=<password> DOCKER_USERNAME=<username> ./build-and-push-to-dockerhub.sh ../fcrepo-webapp/target/fcrepo-webapp-${CURR}.war latest ${CURR} |
Github Release - part 2
Go to
https://github.com/fcrepo/$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
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
).Code Block jarPath=fcrepo-webapp/target/fcrepo-webapp-$CURR-jetty-console.jar md5 -r ${jarPath} > ${jarPath}.md5 shasum ${jarPath}> ${jarPath}.sha1
- Click Publish Release
Github Pages
Update the Github Pages documentation:
Code Block |
---|
mvn site-deploy -DskipTests |
fcrepo 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 fcrepo/fcrepo and fcrepo-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
Expand | ||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||||||||||
Expand | ||||||||||||||||||
|
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.
...
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
Info |
---|
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 the maintenance branch.
Code Block |
---|
git push origin ${CURR}-RC:${CURR}-maintenance |
Info |
---|
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. |
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)
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
- 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
- -release-plugin] prepare for next development iteration
If this appears correct, you can push your release branch on to the maintenance branch.
Code Block |
---|
git push origin ${CURR}-RC:${CURR}-maintenance |
Info |
---|
Because there are no changes to main after code freeze and all bug fixes are on the ${CURR}-RC branch, this will operate as a fast-forward merge. |
Lyrasis wiki documentation updates
Current, in-progress Fedora Repository Documentation wiki: FEDORA6x
At the very minimum, update the following:
Note the version of Java against which the release was built.
New Wiki Space
- 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 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}
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.
- Update permissions on new wiki space to be like the previous space
- Add "fedora" category to new wiki space
- Space Tools → Overview
- Add logo
- Sidebar → Space Details
- Remove default space pages
- Set space "Home Page"
- Space Tools → Space Details
- Ensure `noformat` and `code` macros were copied successfully (this is a bug in the Confluence "copy space" utility)
- e.g: First Steps
- Update Documentation wiki page
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/
- 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 :
- Assuming a fcrepo4 release: Download and run the fcrepo-webapp-$CURR-jetty-console.jar
- Make sure that the checksums of the artifacts published in the github release page match those in sonatype.
- If we're talking about a maintenance release, make sure that all commits that went into the maintenance release are also on main (where appropriate)
Announce release
Let Danny Bernstein Let Carol Minton Morris know that the release is complete and can be announced.
...