Releasing OSHI

Credentials

• Put your repository credentials in your Maven settings.xml file for both snapshot and staging repositories in pom.xml.
• Put your gpg certificate credentials in the settings.xml file

Snapshots

• Other than during releases, the version number in the pom.xml should end in -SNAPSHOT
• A GitHub Action deploys snapshots for pushes to the master branch. Snapshot releases may also be manually deployed using mvn clean deploy

Prepare

• Make sure tests pass on all configured CI operating systems.
• Manually run tests on any non-CI-covered OS using mvn clean test.
• Review SonarQube for any bugs.
• Choose an appropriate version number for the release
  • Proactively change version numbers in the download links on README.md.
  • Copy README.md to src/site/markdown/index.md
    • HTML-escape &, <, and > in any links in the site version
    • Edit markdown URLS from src/site/markdown/ to same-directory links
  • Change release dates and in-progress versions in CHANGELOG.md
  • Move "Your contribution here" to a new empty "In Progress" section
  • Commit changes as a "x.x release" (no need to push upstream yet)

Release

• To perform a full release including the modular artifact you must have JAVA_HOME pointing to JDK 11 or higher.

See this page for a summary of the below steps

• mvn clean deploy

  • Do a final snapshot release and fix any errors in the javadocs
  • If pom sorting or license headers are rewritten as part of this deployment, commit the changes

• mvn release:clean

  • Takes a few seconds

• mvn release:prepare

  • Takes a few minutes
  • This will ask for the version being released, removing -SNAPSHOT
  • This will suggest the next version, increment appropriately

• mvn release:perform

  • Takes a few minutes.
  • This pushes the release to the OSSRH staging repository
  • This also pushes to gh_pages

• Log on to Nexus and release the deployment from OSSRH to the Central Repository.

• Release the site; this can be done anytime after release:prepare:

  • Create/reset/rebase your local site branch to the just-released tag
  • Push your local site branch upstream

• Add a title and release notes to the tag on GitHub and publish the release to make it current.

Ongoing Maintenance

As development progresses, update version in pom.xml using -SNAPSHOT appended to the new version using Semantic Versioning standards:

• Increment major version (x.0) for API-breaking changes or additions
• Increment minor version (x.1) for substantive additions, bugfixes and changes that are backwards compatible
• Increment patch version (x.x.1) for minor bugfixes or changes that are backwards compatible