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. Maven’s GPG setup

   Add your GPG information to your Maven settings ($HOME/.m2/settings.xml) as a profile.

   The use of a profile is recommended to be able to use different signing configurations and keep configuration tidy, but it’s not mandatory.

   <profile>
   	<id>gpg</id>
   	<properties>
   		<gpg.executable>gpg2</gpg.executable>
   		<gpg.passphrase>GPG_PASSPHRASE</gpg.passphrase> (1)
   	</properties>
   </profile>
   
   <activeProfiles>
   	<activeProfile>gpg</activeProfile> (2)
   </activeProfiles>

   1. Passphrase to your GPG keychain

   2. Profile activated by default

If you have more than one key, set <keyname> in the maven-gpg-plugin plugin configuration with the keu id.

1. Update documentation

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

   • Update :release-version: attribute in README.adoc.

   • Add reference to the old README in the proper tag in the README.adoc introduction note.

   • Update version and release version in antora.yml.

   • Assign version to Unreleased section in CHANGELOG.

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

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

   If something fails during this step:

   • Run mvn release:rollback: this will undo changes locally and remove remote tag if it has been already created. 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}.

3. Deploy to Maven Central

   Execute Maven’s deploy goal to publish in Maven Central

   $ mvn release:perform -Darguments="-Prelease-profile -DskipTests"

   ℹ️	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 -DskipTests 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-profile.

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

5. Create the release in GitHub.