Maven release steps (manual) - abelsromero/asciidoctor-maven-plugin GitHub Wiki
This document explains the steps to complete the publication of the asciidoctor-maven-plugin
from a local build to Maven Central.
ℹ️
|
This guide assumes that:
|
-
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>
-
The id must match exactly the id in the
distributionManagement
section of the project’spom.xml
. You can validate access try to login in https://oss.sonatype.org/.
-
-
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>
-
The id must match exactly the id used in the command in later steps
-
Note it’s the username, not the email account
-
-
Expose your GPG key information as environment variables.
Use
gpg --list-keys
to obtain the key name.export GPG_KEYNAME="..." export GPG_PASSPHRASE="..."
❗
|
Before continuing, please check that:
|
-
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 inREADME.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
andmaven-site-plugin-version
inantora.yml
. -
Assign version to
Unreleased
section in CHANGELOG. -
Look for TODO’s in docs that need to be made available for next release.
-
-
Validate code
Run full tests and signature
$ mvn verify -Prun-its -Prelease
Clean any generated resource
$ mvn clean
-
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 adjustdevelopmentVersion
,releaseVersion
andtag
.$ 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}
.
-
-
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 withmvn deploy -Prelease
. -
-
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.
-
Create the release in GitHub.
-
Close GitHub milestone.
-
Report on socials and https://asciidoctor.zulipchat.com/#narrow/stream/279652-announce.C2.A0.F0.9F.93.A2/topic/releases