General

Components

Community

Development

TDF

Release Guide

We are doing two kind of releases at the same time:

  1. One Maven release with the artefacts of each project.
  2. One GitHub release bundling artefacts of the ODF Toolkit as ZIPs.

Maven Release Guide

The release artifacts for each project are deployed to the Maven repository. Making release artefacts should follow the following steps:

Only once your configuration Setup

  1. Maven Repro Access
    Make sure you have access to Maven repro via our Sonatype JIRA issue. After this, you should be able to log in at https://oss.sonatype.org/#welcome. When logged in, will find in your profile a user token. This token along with the according user name have to be added to your local <USER_HOME>/.m2/settings.xml file. Something equivalent to:
    <server>
      <id>ossrh</id>
      <username>YOUR_USER_NAME</username><!-- from your profile -->
      <password>YOUR_PASSWORD</password><!-- being the given token -->
    </server>
  1. Install GNU PG
    GNU PG is necessary to sign the packages of our release.
    Install for your OS. See details in tutorial 'publish your artifacts to Maven'

  2. Configure GNU PG
    Add your GNU credentials (and you might as well your GIT credentials) to your local <USER_HOME>/.m2/settings.xml.

NOTE:
See our example settings.xml and search & replace the placeholders starting with 'YOUR_'.

Recipe for every release

There are two kinds of releases a quick SNAPSHOT release, where the SNAPSHOT will be exchanged by a timestamp or the final release.

Snapshot Release

  1. Deploy Snapshot

    mvn deploy
    

Final Release

  1. 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"
    
  2. 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
    
  3. 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).

  4. 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).

  5. 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:

    • Adding tag (signed -s, annotated (unsigned) -a, with message -m)
    git tag -s -a v0.12.0 2920b36c2b -m"odftoolkit-0.12.0"
    git push origin v0.12.0
    
    • Deleting tag
    git tag -d v0.12.0
    git push origin --delete v0.12.0
    
  6. What to Do If Something Goes Wrong

    • Step 1: Undo the release:
    git reset –hard HEAD~1 (Depending upon when the error occurred, you might undo multiple commits)
    
    • Step 2: Delete the tag.
    git tag -d tagName
    git push origin :refs/tags/tagName
    
  7. 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.

    1. If the release artefacts are correct, close the repository.
    2. After the closing process is done, you may release the repository.
    3. You may find the artefacts of the release among on Maven, e.g.: https://repo1.maven.org/maven2/org/odftoolkit/odftoolkit/
  8. Publish Document
    Publish all of the prepared document on the website and update the download page.

  9. 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/
    

Manual GitHub Release Guide

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 Six Release Artefacts (downloadable from GitHub)

The GitHub release has always six files:

Creating Release Artefacts

  1. Call from the ODF TOOLKIT base via command line:

    mvn clean
    
  2. 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.

  3. You might want to update the website to announce the release.

Bundling Release Artefacts:

  1. 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.

  2. 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.

Upload of the 6 Release Artefacts

  1. Browse to our GitHub release page.
  2. Press the "Draft a new release" button (or ask for access rights on the mailing list if not visible).
  3. Upload all 6 files from the release and name it like "'odftoolkit-' + version", for instance: odftoolkit-8.0.0-RC2

References

  1. How to Publish Your Artifacts to Maven Central

Impressum (Legal Info) | Privacy Policy (Datenschutzerklärung) | Statutes (non-binding English translation) - Satzung (binding German version) | Copyright information: Unless otherwise specified, all text and images on this website are licensed under the Apache License, v2.0. This does not include the source code of LibreOffice, which is licensed under the Mozilla Public License v2.0. “LibreOffice” and “The Document Foundation” are registered trademarks of their corresponding registered owners or are in actual use as trademarks in one or more countries. Their respective logos and icons are also subject to international copyright laws. Use thereof is explained in our trademark policy. LibreOffice was based on OpenOffice.org.