This document explains the steps to complete the publication of the asciidoctor-maven-plugin from a local build to Maven Central.

1. MavenCentral setup

   Add your MavenCentral credentials (it’s recommended to use a token instead of user+password) to your Maven settings as in the example below. Usually found in $HOME/.m2/settings.xml.

   <servers>
   	<server>
   		<id>osshr</id> (1)
   		<username>OSS_SONATYPE_USERNAME</username>
   		<password>OSS_SONATYPE_API_KEY</password>
   	</server>
   </servers>

   1. The id must match exactly the id in the distributionManagement section of the project’s pom.xml. You can validate access try to login in https://oss.sonatype.org/.

2. GitHub setup

   This step is not mandatory. It depends on your local configuration, but doing it ensures a reproducible build without surprises. This is then, highly recommended.

   Add your GitHub credentials to your Maven settings ($HOME/.m2/settings.xml) as in the example below.

   <servers>
   	<server>
   		 <id>github</id> (1)
   		 <username>GITHUM_USERNAME</username> (2)
   		 <password>GITHUB_PASSWORD</password>
   	</server>
   </servers>

   1. The id must match exactly the id used in the command in later steps

   2. Note it’s the username, not the email account

3. Environment GPG setup

   Expose your GPG key information as environment variables.

   Use gpg --list-keys to obtain the key name.

   export GPG_KEYNAME="..."
   export GPG_PASSPHRASE="..."

1. Update documentation

   Last commit before release should leave everything ready since it will be the last in the tag. The following changes to documentation must be done:

   • Update :release-version: and :maven-site-plugin-version: attribute in README.adoc.

   • (only v2.2.x) Add reference to the old README in the proper tag in the README.adoc introduction note.

   • Update version (in case of new major/minor change), release-version and maven-site-plugin-version in antora.yml.

   • Assign version to Unreleased section in CHANGELOG.

   • Look for TODO’s in docs that need to be made available for next release.

2. Validate code

Run full tests and signature

Clean any generated resource

1. Prepare the release

   If you want to test this in your own github repo, replace the owner (asciidoctor) with your GitHub username in the <scm> section.

   Execute the prepare goal of the maven-release-plugin. You’ll have to adjust developmentVersion, releaseVersion and tag.

   $ mvn -B release:prepare -Darguments="-Prelease -Dmaven.test.skip"

   During this step, if you have git commit signature enabled, a pop-up will ask for your pass, pay attention it’s NOT the gpg artifacts signature.

   If something fails during this step:

   • Run mvn release:rollback: this will undo changes locally and remove the created remote tag. But it will create another commit restoring original version.

   • Reset commits made by the plugin in your local repo and push force to remote to restore if necessary.

   • Check all previous steps and restart.

     This command will automatically increase the minnor version and create a tag named asciidoctor-maven-plugin-${release-version} by default this is OK. If custom version or tag is required, these can be set passing -DreleaseVersion=${version} or -Dtag=${tag-name}.

2. Deploy to Maven Central

   Execute Maven’s deploy goal to publish in Maven Central

   $ mvn release:perform -Darguments="-Prelease -Dmaven.test.skip"

   ℹ️	Depending on the OS and key management during the process you’ll be asked for your gpg passphrase. The same set in settings.xml. You can add -Dmaven.test.skip to -Darguments if everything has been checked before to speed up this step. Add -Pgpg if the profile is not activated by default.

   If something fails during this step, tags and prepare commits will be already pushed to asciidoctor repo. Rollback as explained in previous step and re-start.
   However, (not recommended) if the error was punctual (e.g. network) and everything is fine. Check code is correct, clone the newly created tag and deploy directly with mvn deploy -Prelease.

3. Synchronize with Maven Central

   If everything went fine, artifacts will be in a Staging Repository in https://oss.sonatype.org.

   Login with your account and push the "Close" button . Validations happen during this moment, so error can still occur. Check the "Activity" tab below for any hint on errors.

   If ok, an email is sent account owner.

   Finally, push the "Release" button to complete the process. Files will be publicly available in a few minutes.

4. Create the release in GitHub.

5. Close GitHub milestone.

6. Report on socials and https://asciidoctor.zulipchat.com/#narrow/stream/279652-announce.C2.A0.F0.9F.93.A2/topic/releases