Release Workflow

This is the workflow for releasing a new version of XSpec:

1. Prepare the release

   1. Write release notes (draft). Most of the content is from a private generator, if AirQuick is available to run it (see comment). The New Contributors section comes from GitHub automated release notes; insert this section under "Merged Pull Requests" heading.
   2. Create a pull request incrementing the version (without -SNAPSHOT) of pom.xml and the Oxygen add-on and merge it into master

2. Release it

   1. Deploy the XSpec artifact to Maven Central

      • This step must be done immediately before publishing the release so that we can fix any error in pom.xml which can be found only by deploying the artifact.
      • Actual deployment to Sonatype is performed automatically by a GitHub Actions workflow.

   2. Publish the release at Releases page

   3. Promote the release

3. Prepare the next development

   1. Close the milestone related to the release
   2. Create the milestone for the next release

4. Start the next development

   1. Create a pull request incrementing the version (with -SNAPSHOT) of pom.xml and merge it into master

Version scheme

The version number consists of three parts, X.Y.Z. Use the Z part for pre-releasing:

• Whenever a commit is made into the master branch, a GitHub Actions workflow deploys it automatically to Sonatype as X.Y-SNAPSHOT.

  • We omit the Z part for simplicity. (See this for Maven version comparison.)

• Whenever a notable change is made into the master branch, increment Z in oxygen-addon.xml and update the add-on changelog.

  • Do not push a git tag. Do not publish a GitHub pre-release. Do not announce it.

• When we want to release a stable version, perform this procedure:

  1. Increment Z in oxygen-addon.xml.
  2. Notify the XSpec discussion list of the upcoming X.Y release. (Ignore the Z part for simplicity.)
  3. After a while, increment Z and release it:
     1. Write X.Y.Z (without -SNAPSHOT) to oxygen-addon.xml and pom.xml.
     2. Push vX.Y.Z git tag and publish vX.Y.Z GitHub release.
  4. Announce the availability of vX.Y. (Ignore the Z part for simplicity.)

Here's an example timeline:

	master branch commit timeline	Oxygen add-on release (oxygen-addon.xml)	Maven deployment (pom.xml)	git tag	GitHub Release	Release Announcement
	Bump Maven version to start the next development	(unreleased)	2.0-SNAPSHOT	(none)	(none)	(none)
	...trivial or under-the-hood changes...	(unreleased)	2.0-SNAPSHOT	(none)	(none)	(none)
	Notable feature or fix	(unreleased)	2.0-SNAPSHOT	(none)	(none)	(none)
	Release to Oxygen add-on channel	2.0.0	2.0-SNAPSHOT	(none)	(none)	(none)
	...trivial or under-the-hood changes...	(unreleased)	2.0-SNAPSHOT	(none)	(none)	(none)
	Notable feature or fix	(unreleased)	2.0-SNAPSHOT	(none)	(none)	(none)
	Release to Oxygen add-on channel	2.0.1	2.0-SNAPSHOT	(none)	(none)	(none)
	...trivial or under-the-hood changes...	(unreleased)	2.0-SNAPSHOT	(none)	(none)	(none)
	Notable feature or fix	(unreleased)	2.0-SNAPSHOT	(none)	(none)	(none)
	Release to Oxygen add-on channel	2.0.2	2.0-SNAPSHOT	(none)	(none)	(none)
	...trivial or under-the-hood changes...	(unreleased)	2.0-SNAPSHOT	(none)	(none)	(none)
	Release to Oxygen add-on channel (Stable Release Candidate)	2.0.3	2.0-SNAPSHOT	(none)	(none)	(none)
	Stable Release	2.0.4	2.0.4	v2.0.4	v2.0.4	v2.0
	Bump Maven version to start the next development	(unreleased)	2.1-SNAPSHOT	(none)	(none)	(none)
	...trivial or under-the-hood changes...	(unreleased)	2.1-SNAPSHOT	(none)	(none)	(none)
	Notable feature or fix	(unreleased)	2.1-SNAPSHOT	(none)	(none)	(none)
	Release to Oxygen add-on channel	2.1.0	2.1-SNAPSHOT	(none)	(none)	(none)
	...trivial or under-the-hood changes...	(unreleased)	2.1-SNAPSHOT	(none)	(none)	(none)
	Notable feature or fix	(unreleased)	2.1-SNAPSHOT	(none)	(none)	(none)
	Release to Oxygen add-on channel	2.1.1	2.1-SNAPSHOT	(none)	(none)	(none)
	...trivial or under-the-hood changes...	(unreleased)	2.1-SNAPSHOT	(none)	(none)	(none)
	Release to Oxygen add-on channel (Stable Release Candidate)	2.1.2	2.1-SNAPSHOT	(none)	(none)	(none)
	Stable Release	2.1.3	2.1.3	v2.1.3	v2.1.3	v2.1

Updating Oxygen add-on

See the latest comment in oxygen-addon.xml.

Promoting the release

• Post a message on the XSpec mailing list
• Promote the new release on xml.com
• Post a message on the xml-dev mailing list
• Add post on xspec.io
• Ask users to tweet about the new release