Add release script that reacts on tags like v2.0.0

[PattaFeuFeu]

Description

Closes #314

Adds a GitHub Actions script for releasing new versions of this library.

The action is triggered by tag pushes that are formatted like v2.0.0 (could also be v2.0.0-rc1 as long as we have v` and a major, minor, patch version, separated by a dot).

The action first runs gradle check. If that finishes successfully, we continue. If it doesn’t, the build fails.

After check, it runs assemble generatePomFileForBigbonePublication to assemble JAR variants (the same ones that would also be published) and a POM file.

Afterwards, it runs publish to run maven-publish with the configuration in bigbone.library-conventions.gradle.

It then zips the JAR files and POM file into an archive named like BigBone-v2.0.0-20231105.182643.zip.

Finally, a GitHub release is created with the ZIP attached. Release notes are created automatically.
The release is set to pre-release and draft so that we can have a last look or add additional information before we actually publish.

What still needs to be done

It’s currently unclear to me which signing config parameters are necessary. We will need to add secrets to GitHub and reference them in the script so that we pipe them into the necessary gradle steps that need them.

Type of Change

(Keep the one that applies, remove the rest)

• New feature (non-breaking change which adds functionality)

How Has This Been Tested?

I ran most of the gradle calls locally, and tested the bash script locally. Since I do not have the necessary signing config properties on my machine, I couldn’t test it completely unfortunately.

Mandatory Checklist

• My change follows the projects coding style
• I ran gradle check and there were no errors reported
• I have performed a self-review of my code
• I have added tests that prove my fix is effective or that my feature works
• New and existing unit tests pass locally with my changes
• KDoc added to all public methods

[andregasser]

Hey there!

Thanks for preparing this. I have done some research and I think what we should do is something like this:

release.yml

We should change this

- name: Publish the library
  uses: gradle/gradle-build-action@v2
  with:
    arguments: publish

into this:

- name: Publish the library
  uses: gradle/gradle-build-action@v2
  with:
    arguments: publish
  env:  
    SONATYPE_USERNAME: ${{ secrets.OSS_SONATYPE_USERNAME }}
    SONATYPE_PASSWORD: ${{ secrets.OSS_SONATYPE_PASSWORD }}
    ORG_GRADLE_PROJECT_signingKeyId: ${{ secrets.SIGNING_KEY_ID }}
    ORG_GRADLE_PROJECT_signingKey: ${{ secrets.SIGNING_PRIVATE_KEY }}
    ORG_GRADLE_PROJECT_signingPassword: ${{ secrets.SIGNING_PASSWORD }}

This injects GitHub secrets I have set up as environment variables into this GitHub action, so that Gradle can access it. Naming of the ORG_GRADLE_PROJECT_* vars is according to the Gradle Signing plugin documentation.

bigbone.library-conventions.gradle

Change this:

credentials {
    username = project.properties.containsKey("sonatypeUsername") ? sonatypeUsername : ""
    password = project.properties.containsKey("sonatypePassword") ? sonatypePassword : ""
}

into this:

credentials {
    username = System.getenv("SONATYPE_USERNAME") ?: ""
    password = System.getenv("SONATYPE_PASSWORD") ?: ""
}

Doing so, we instruct Gradle to read credentials needed for Maven Central publishing from environment variables instead from Gradle properties.

Then, in the same file, we would need to change this as well:

signing {
    sign publishing.publications.bigbone
}

into this:

signing {
    def signingKeyId = findProperty("signingKeyId")
    def signingKey = findProperty("signingKey")
    def signingPassword = findProperty("signingPassword")
    useInMemoryPgpKeys(signingKeyId, signingKey, signingPassword)  
    sign publishing.publications.bigbone
}

This instructs Gradle to process an ascii-armored privatae key for signing. This process is also documented in the Gradle Signing plugin documentation.

Does that make sense to you? What do you think?

[PattaFeuFeu]

@andregasser All of that sounds like what I had planned anyway. I just didn’t know how your current signing setup worked exactly so I lacked the knowledge about which specific keys would need to be set.

[PattaFeuFeu]

@andregasser I have implemented your suggestions as you wrote them. 😊 Ready for review now.

[andregasser]

Hello @PattaFeuFeu,

This looks good to me and we can merge this.

But: Whenever we create a tag like v2.0.0 to trigger a release, we must set the BigBone version in libs.versions.toml beforehand to 2.0.0 as well, as otherwise the publish will target the wrong repository (snapshots instead of releases - see see bigbone.library-conventions.gradle for details). But I think we can handle this.

It would be nice if we could also build another workflow file for publishing snapshots to Maven Central. What about creating a second file snapshot.yml? It is actually the same as release.yml but in this case the workflow is not triggered via tag creation, but is only executed manually when needed. Same here, the version in libs.versions.toml needs to be set to something like X.Y.Z-SNAPSHOT before running the workflow.

What do you think of this?

[andregasser]

👍

[PattaFeuFeu]

But: Whenever we create a tag like v2.0.0 to trigger a release, we must set the BigBone version in libs.versions.toml beforehand to 2.0.0 as well, as otherwise the publish will target the wrong repository (snapshots instead of releases - see see bigbone.library-conventions.gradle for details). But I think we can handle this.

That flow has worked for me for some time now in a different project. We often create a commit with the updated version and tag that commit then.
We could also update the flow to update that file based on what the version in the tag is, but that would be a more involved script. I’d like to try this approach here out first. 😊

It would be nice if we could also build another workflow file for publishing snapshots to Maven Central. What about creating a second file snapshot.yml? It is actually the same as release.yml but in this case the workflow is not triggered via tag creation, but is only executed manually when needed. Same here, the version in libs.versions.toml needs to be set to something like X.Y.Z-SNAPSHOT before running the workflow.

What do you think of this?

We could just reuse this script and additionally add on: workflow_dispatch: as one of the potential triggers. This way, we’ll get a branch picker in the actions for this action.

I can add that to this PR before we merge?

[codecov]

Codecov Report

Merging #336 (f2d2eea) into master (83ca484) will not change coverage.
Report is 1 commits behind head on master.
The diff coverage is n/a.

Additional details and impacted files

@@            Coverage Diff            @@
##             master     #336   +/-   ##
=========================================
  Coverage     47.29%   47.29%           
  Complexity      498      498           
=========================================
  Files           136      136           
  Lines          3673     3673           
  Branches        240      240           
=========================================
  Hits           1737     1737           
  Misses         1755     1755           
  Partials        181      181           

[andregasser]

👍

[andregasser]

We could just reuse this script and additionally add on: workflow_dispatch: as one of the potential triggers. This way, we’ll get a branch picker in the actions for this action.

Great idea, sure let's do it like that. 😊