Continuous Integration

Continuous integration for the AsciidoctorJ project is performed by GitHub Actions. You can find recent build results, including the build status of pull requests, on the asciidoctor/asciidoctorj page.

Release and publish the artifacts

Releases are made by the Release workflow, which is started by hand from the main branch with the following inputs:

releaseVersion: the version to release, e.g. 3.0.2.
nextVersion: the next development version, e.g. 3.0.3-SNAPSHOT. Defaults to the next patch version (or, for a pre-release such as 4.0.0-alpha.1, to 4.0.0-SNAPSHOT).

Before starting it, make sure that the == Unreleased section of CHANGELOG.adoc describes all the changes of the release, grouped in category sections such as === Improvements or === Bug Fixes.

The workflow:

sets the release version in gradle.properties
rolls the == Unreleased section of CHANGELOG.adoc into == <releaseVersion> (<date>) and starts a new == Unreleased section, with bestikk-changelog
for a final release, updates the version of the documentation and the versions it mentions (AsciidoctorJ, AsciidoctorJ PDF, AsciidoctorJ EPUB3 and JRuby, taken from build.gradle) in docs/antora.yml
commits Release v<releaseVersion> and tags it v<releaseVersion>
builds the release with ./gradlew clean build
sets the next development version in gradle.properties and commits Prepare next development iteration <nextVersion>
pushes the commits and the tag to main
publishes the artifacts to Maven Central with ./gradlew publishToSonatype closeAndReleaseSonatypeStagingRepository
creates the GitHub release, using the section of CHANGELOG.adoc converted to Markdown by bestikk-changelog as release notes
waits until the distribution is available on Maven Central and publishes it to SDKMAN with ./gradlew asciidoctorj-distribution:sdkMajorRelease (sdkMinorRelease for a pre-release, so that it is not made the default version)

The workflow runs in the release environment, which provides the following secrets:

GPG_KEY_ID, GPG_PRIVATE_KEY and GPG_PASSPHRASE to sign the artifacts
OSS_SONATYPE_USERNAME and OSS_SONATYPE_PASSWORD to publish the artifacts to Maven Central
SDKMAN_CONSUMER_KEY and SDKMAN_CONSUMER_TOKEN to publish the release to SDKMAN

Release by hand

If needed, a release can still be made from a local machine. The following properties have to be set, for example in the file ~/.gradle/gradle.properties:

~/.gradle/gradle.properties

signing.keyId=...              (1)
signing.password=...
signing.secretKeyRingFile=/home/YOUR_USERNAME/.gnupg/secring.gpg

sdkman_consumer_key=...        (2)
sdkman_consumer_token=...

sonatypeUsername=...           (3)
sonatypePassword=...

1	Settings for signing the artifacts
2	Credentials for publishing a new release to sdkman
3	Credentials for publishing artifacts to Maven Central

Then run the same steps as the workflow:

Update the version in gradle.properties to a release version, i.e. from 3.0.2-SNAPSHOT to 3.0.2, and the versions in docs/antora.yml. Roll the == Unreleased section of CHANGELOG.adoc into == 3.0.2 (<date>), then commit and tag:
```
# npx @bestikk/changelog release 3.0.2 --release-heading "{version} ({date})"
# git commit -am "Release v3.0.2"
# git tag v3.0.2
```
Build the release with
```
# ./gradlew clean build
```

Publish the artifacts to Maven Central with

# ./gradlew publishToSonatype closeAndReleaseSonatypeStagingRepository

Create the GitHub release, using the output of npx @bestikk/changelog notes 3.0.2 --release-heading "{version} ({date})" as release notes.
Once the distribution is available on Maven Central, publish the new version to sdkman with
```
# ./gradlew asciidoctorj-distribution:sdkMajorRelease
```
Upgrade the version to the next version by changing the version property in gradle.properties to version=3.0.3-SNAPSHOT, commit and push the commits and the tag:
```
# git commit -am "Prepare next development iteration 3.0.3-SNAPSHOT"
# git push origin main v3.0.2
```