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:
NOTE: To gather the release notes information it is helpful to go backward through issues and pull requests in GitHub!
./README.md
./src/site/content/odftoolkit_website/ReleaseNotes.mdtext
./src/site/content/odftoolkit_website/downloads.mdtext
./src/site/site/content/odftoolkit_website/javadoc.mdtext # the older API exists only on odftoolkit.org (but we keep API DIFF files here, too!)
./docs/api/index.html # one of a very few HTML files to be edited - insertion of version#!
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, which is done and a build via, after an interactive process:
mvn release:prepare # build with release data javadoc for release generated in target
git status -sb # there should be no uncommitted / changed files
Now copy the JavaDoc files with our script:
cd src/site
copy-javadoc.sh
git commit -am"New JavaDoc for the upcoming release"
Creating the API diff file for ODFDOM API:
git clone https://github.com/siom79/japicmp
cd japicmp
mvn install
cd japicmp/target
java -jar .\japicmp-0.18.4-SNAPSHOT-jar-with-dependencies.jar -m -n .\odfdom-java-0.12.0.jar -o .\odfdom-java-0.11.0.jar --ignore-missing-classes --html-file odfdom-api-changes-0.11.0-0.12.0.html # adjust versions numberes :-)
cp odfdom-api-changes-0.11.0-0.12.0.html <YOUR_ODFTOOLKIT_DIR>/docs/api
cd <YOUR_ODFTOOLKIT_DIR>/docs/api
git status -sb # there should be only one field
git add .
git commit -m"Adding ODFDOM API changes of this release - created via japicmp-0.18.4-SNAPSHOT" # version may vary
JUST IN CASE: A clean start after errors
Make sure that your working copy is clean.Preferably check out/a cd clean.Preferably check out/a git status -sb # there should be only one field git add .
git rebase -i HEAD~12 # drop the two maven release commits
mvn clean
mvn release:clean
git tag -d <YOUR_RELEASE_TAG> # git tag -d odftoolkit-0.12.0
mvn release:prepare # start over
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. Strangely, it already does two commits one for the release and one for the follow-up SNAPSHOT - even the release has not succeded now. 'mvn release:perform' will check out the first commit again (a bit suboptimal IMHO).
Perform the release
mvn release:perform
"mvn release:perform" will checkout the tag (created by mvn release:prepare) 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 project website to signatures, sums and KEYS need to refer to the original documents on GitHub. See release signing guide for more information (from Apache).
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.12.0 release the git commands looked like:
git tag -s -a v0.12.0 2920b36c2b -m"odftoolkit-0.12.0"
git push origin v0.12.0
git tag -d v0.12.0
git push origin --delete v0.12.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.12.0 Release"
To: dev@odftoolkit.org
Hi all,
The ODF Toolkit team is pleased to announce the release of 0.12.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.12.0" [3,4,5].
[1] ./ReleaseNotes.html
[2] https://github.com/tdf/odftoolkit/releases/tag/v0.12.0
[3] https://repo1.maven.org/maven2/org/odftoolkit/odfdom-java/0.12.0/
[4] https://repo1.maven.org/maven2/org/odftoolkit/odfvalidator/0.12.0/
[5] https://repo1.maven.org/maven2/org/odftoolkit/xslt-runner/0.12.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.