We are doing two kind of releases at the same time:
The release artifacts for each project are deployed to the Maven repository. Making release artefacts should follow the following steps:
Maven Repro Access
Make sure you have access to Maven repro via our Sonatype JIRA issue. Add your userID & password to your local <USER_HOME>/.m2/settings.xml. In the end, you should be able to log in at https://oss.sonatype.org/#welcome.
Install GNU PG
Install in your OS. See details in tutorial 'publish your artifacts to Maven'
Configure GNU PG
Add your GNU and JIRA credentials to your local <USER_HOME>/.m2/settings.xml. See our example settings.xml and search & replace the placeholders starting with 'YOUR_'.
There are two kinds of releases a quick SNAPSHOT release, where the SNAPSHOT will be exchanged by a timestamp or the final release.
Deploy Snapshot
mvn deploy
Prepare documentation
Working on a release git branch and using a GitHub fork to test the new GitHub pages helps a lot!
git checkout -b release-candidate
The following documents need currently manual adjustment:
./README.md
./src/site/content/odftoolkit_website/ReleaseNotes.mdtext
./src/site/content/odftoolkit_website/downloads.mdtext
The mdtext files are being converted to HTML doing (on Linux)
cd src/site
build-html.sh
git add ../..
git commit -m"Documentation update for the upcoming release"
Prepare JavaDoc
JavaDoc has to be generated with the upcoming release number already set. Therefore instead of doing it manually I do a
mvn release:prepare # should generate the javadoc - otherwise 'mvn install'
git stash # to remove the changed pom.xml
cd src/site
copy-javadoc.sh
git add ../..
git commit -m"New JavaDoc for the upcoming release"
A clean start
Make sure that your working copy is clean. Preferably check out a clean version from GitHub.
mvn clean
mvn release:clean
Prepare the release
mvn release:prepare
This will start the interactive release preparation. You need to supply Maven with the versions of the release. "release version" should be the version of the intended release (recommended value should be fine). "SCM release tag or label" should include the RC version (e.g. odftoolkit-0.10.0). "new development version" should be the current SNAPSHOT version.
Perform the release
mvn release:perform
This will checkout the tag to the target directory, build and package everything and upload the artifacts to the staging repository. Users will download the mirrored release artifacts from machines outside TDF control. Users need to verify that the copy downloaded is identical to the original. Mirrored copies of checksums, KEYS and signature files (.asc and .md5 files) will be present on the mirrors but must never be used for verification. So, all links from the podling website to signatures, sums and KEYS need to refer to the original documents on GitHub. See release signing guide for more information.
Add the Git tag manually after branch rebase Push the branch and if the branch is rebased the tag has to be added and pushed on the correct commit manually. For instance for 0.11.0 release the git commands looked like:
git tag -s -a v0.11.0 4baf275b33 -m"odftoolkit-0.11.0"
git push origin v0.11.0
git tag -d v0.11.0
git push origin --delete v0.11.0
What to Do If Something Goes Wrong
git reset –hard HEAD~1 (Depending upon when the error occurred, you might undo multiple commits)
git tag -d tagName
git push origin :refs/tags/tagName
Review and approve the Maven Nexus Deliverables
Log into https://oss.sonatype.org/#welcome and review the artefacts of the release, if it is erroneous drop it.
Publish Document
Publish all of the prepared document on the website and update the download page.
Send Announcements
The release manager need to send announcements to odf-dev list. The sample looks like:
Subject:[ANNOUNCEMENT] "ODF Toolkit 0.11.0 Release"
To: dev@odftoolkit.org
Hi all,
The ODF Toolkit team is pleased to announce the release of 0.11.0 (>=JDK 11) supporting ODF 1.2.
The list of changes is available in the release notes[1].
All new ODF Toolkit components (binary, source and JavaDoc bundles) are available as GitHub releases [2].
Or in the central Maven repository under group ID "org.odftoolkit" and version "0.11.0" [3,4,5].
[1] ./ReleaseNotes.html
[2] https://github.com/tdf/odftoolkit/releases/tag/v0.11.0
[3] https://repo1.maven.org/maven2/org/odftoolkit/odfdom-java/0.11.0/
[4] https://repo1.maven.org/maven2/org/odftoolkit/odfvalidator/0.11.0/
[5] https://repo1.maven.org/maven2/org/odftoolkit/xslt-runner/0.11.0/
NOTE: This manual is just a fallback in case the automatic upload to GitHub does not work correctly. We have added a deployment GitHub action, that is being triggered, whenever a tag is being added, see see https://github.com/tdf/odftoolkit/blob/master/.github/workflows/deployment.yml
The GitHub release has always six files:
Three ZIPs representing the ODF Toolkit:
Three SHA files, one for each ZIP to proof their correctness.
Call from the ODF TOOLKIT base via command line:
mvn clean
Call from the ODF TOOLKIT base via command line one of the following.
mvn install -Ppedantic
mvn install -Ppedantic > mylogFile.txt 2>&1*
NOTE: The option pedantic checks if all files have either a valid license header or an explicit exception. Often helpful for reviewing the build output is redirecting it into an own logfile.
You might want to update the website to announce the release.
Test the JARs if they are working and if the documentation is correct, esp. JavaDoc references to ODF elements, attributes and units have been created correctly by our JavaDoc taglet project.
If all project artefacts have been created without an error, they can be bundled into ZIPs and signed via:
mvn antrun:run@prepare-github-release -Pprepare-release
The output will be created in the directory: 'ODF_TOOLKIT_BASE/target/release/'.
NOTE: Don't forget to check if the ZIPs of the result directory have the correct content.