Skip to content

publishing.md

Latest commit

 

History

History
116 lines (87 loc) · 4.07 KB

publishing.md

File metadata and controls

116 lines (87 loc) · 4.07 KB
Raw

Publishing

Artifacts are published to GitHub Packages only. Maven Central is not used.

Target

  • Repository: https://maven.pkg.github.com/magnusp/libsql-java
  • Repository id: github
  • GroupId: io.github.magnusp.libsql
  • ArtifactIds: libsql-jdbc, libsql-client, libsql-hrana-codec, plus the parent POM. libsql-itests and libsql-conformance set maven.deploy.skip and are not published.

The github id matches the server that actions/setup-java configures from GITHUB_ACTOR and GITHUB_TOKEN in .github/workflows/publish.yml.

Versioning

The build uses Maven CI-friendly versions: <version>${revision}${sha1}${changelist}</version>. The defaults live in the root pom.xml.

Build Trigger or command Resolved version
Local development ./mvnw clean install 0.2.0-dev
main prerelease push to main 0.2.0-rc.<12-char-sha>
Release tag v0.2.0 0.2.0
Release candidate tag v0.2.0-rc.1 0.2.0-rc.1
Custom ./mvnw -Drevision=0.3.0 -Dsha1= -Dchangelist= clean install 0.3.0

Branch builds set revision to <base>-rc and sha1 to .<short-sha>, producing 0.2.0-rc.<sha>. Tag builds leave both suffixes empty. ${changelist} defaults to -dev locally; CI clears it.

No Maven SNAPSHOT versions

-SNAPSHOT is never produced or published. GitHub Packages for Maven is immutable, so a repeated -SNAPSHOT publish would fail or silently confuse consumers. Every published version is a concrete prerelease or release.

The -rc. qualifier is a recognized Maven prerelease for Renovate, so its default ignoreUnstable setting filters these builds. A bare SHA qualifier such as 0.2.0-01fea7f408be looks stable to Renovate and must not be used.

A side effect of immutability: a given commit maps to one 0.2.0-rc.<sha> version. Re-running the publish workflow for the same commit attempts to republish the same version and will be rejected by GitHub Packages. Publish a new commit or a tag instead.

Workflow

.github/workflows/publish.yml runs on pushes to main and on v* tags:

  1. Tag build: the version is the tag name without the leading v.
  2. Branch build: the base revision is read from the POM, then suffixed with -rc. and the 12-character commit SHA.
  3. The workflow refuses any resolved version containing -SNAPSHOT.
  4. ./mvnw clean deploy -Prelease -DdeployAtEnd=true runs the full unit and integration test suite, then deploys the main, sources, and javadoc artifacts once at the end of the reactor.

Deployment order

deployAtEnd=true defers all uploads until every module has built and tested. A build or test failure therefore deploys nothing. It is not transactional: if an upload fails mid-batch, earlier artifacts remain published. GitHub Packages has no staging or promotion step. A partial publish must be cleaned up by deleting the affected version and publishing a new one.

Release process

  1. Merge to main. The workflow publishes 0.2.0-rc.<sha>.
  2. Tag the commit and push the tag: 
    git tag v0.2.0
git push origin v0.2.0
  3. The workflow publishes 0.2.0.
  4. Bump revision in the root pom.xml for the next development cycle.

Consuming

GitHub Packages requires authentication even for public packages.

Add the repository:

<repositories>
    <repository>
        <id>github</id>
        <url>https://maven.pkg.github.com/magnusp/libsql-java</url>
    </repository>
</repositories>

Add a server to ~/.m2/settings.xml:

<servers>
    <server>
        <id>github</id>
        <username>YOUR_GITHUB_USERNAME</username>
        <password>${env.GITHUB_TOKEN}</password>
    </server>
</servers>

The token needs read:packages to consume. Publishing uses the workflow's GITHUB_TOKEN with packages: write.

Then depend on:

<dependency>
    <groupId>io.github.magnusp.libsql</groupId>
    <artifactId>libsql-jdbc</artifactId>
    <version>0.2.0</version>
</dependency>

Use a 0.2.0-rc.<sha> version to consume a specific main build.