Simplify Gradle build logic for making releases. #700

blackwinter · 2025-06-24T14:32:22Z

Resolves #684.

Release and release candidate builds require a clean working directory and a matching tag: Create a tag for the release version first, then execute whatever build target you need with the corresponding version specified as project property (-PpublishVersion=A.B.C or -PpublishVersion=A.B.C-rcN). Release builds additionally enforce signing of the generated artifacts.

Ad hoc builds from branches (including master) or arbitrary "version" designators always result in SNAPSHOT builds and don't require a clean working directory or a matching tag: Specify the desired "version" as project property (-PpublishVersion=A-B-C-SNAPSHOT) or simply omit it (will then use the current branch name).

Behavioural changes:

Release candidates use tags instead of branches, just like regular releases.
Release candidates require a clean working directory, just like regular releases.
Publish version must be passed explicitly, it's no longer inferred from repository state and/or tags.
Ad hoc builds ignore tags altogether (no need to fake a dirty working directory in order to work around the previous build logic).
Branch names don't carry any meaning (previously releases/* for release builds and *-rc* for release candidates).
Aborts the build instead of warning/skipping if any preconditions aren't met (i.e. working directory state, matching tag).

Release and release candidate builds require a clean working directory and a matching tag: Create a tag for the release version first, then execute whatever build target you need with the corresponding version specified as project property (`-PpublishVersion=A.B.C` or `-PpublishVersion=A.B.C-rcN`). Release builds additionally enforce signing of the generated artifacts. Ad hoc builds from branches (including `master`) or arbitrary "version" designators always result in SNAPSHOT builds and don't require a clean working directory or a matching tag: Specify the desired "version" as project property (`-PpublishVersion=A-B-C-SNAPSHOT`) or simply omit it (will then use the current branch name).

dr0i

Besides he empty line I think this is good 👍

MAINTAINING.md

TobiasNx · 2025-07-14T15:26:07Z

@blackwinter can you help me how to review this? what should I try to run?

blackwinter · 2025-07-14T16:02:49Z

First of all, you should review the updated steps in MAINTAINING.md. Do they make sense to you? Are they sufficiently simple, fool-proof, without providing too many opportunities for mistakes?

Then you could run various scenarios (without actually pushing/publishing anything!). Different branches/detached head, different publishVersions, with and without providing the required tags (which should be cleaned up afterwards!). The most basic task would be clean which then just prints the version; you could also generate the distribution with assemble.

If you need more guidance we should meet for a "review session".

In order to minimize risk of injection attacks.

MAINTAINING.md

TobiasNx · 2025-07-29T14:02:33Z

I followed the MAINTINGING.md locally creating snapshots, rc and releases with tags. This seems to work for the main part.

Two things may need some adjustments:

The documentation is not very clear with regard to the signing creadentials and that additionally to the gradle credentials git needs gpg credentials to be able to create a signed tag. Documentation should be more clear when gpg credentials are needed. In my current test it seems that only for creating a release and not for creating a rc signing credentials for gradle are needed. This propably should be done in another ticket
We should add:
- How to add gpg credentials to git, as it is a prerequisite for creating a signed tag.
- We should make it more explicit for what we need gradle signing credentials
- Update the signing credentials code block (keyName seems to be unnecessary also " are not needed for file paths):

signing.gnupg.homeDir=/home/user/.gnupg # <--- no "..."
signing.password=...
# depending on gradle plugin versions etc. you may need to use:
signing.keyId=[last 8 sign of the gpg keys]
signing.secretKeyRingFile=/home/user/.gnupg/secring.gpg # <--- no "..."

Hint that one has to create a keyring gpg --keyring secring.gpg --export-secret-keys > ~/.gnupg/secring.gpg
For further info https://docs.gradle.org/current/userguide/signing_plugin.html#sec:signatory_credentials

When building a release candidate this is handled as Snapshot and the build gets a -SNAPSHOT suffix, is this correct? @dr0i I remember that you complained when I was uploading the last release candidate for the first time that the runner archives should not have SNAPSHOT in the name and the build should be named "metafacture-core-A.B.C-rcN" See test 4.

For further context what I tested:

Created a new branch on this basis testBranchGradle

./gradlew assemble without -PpublishVersion

$./gradlew assemble

> Configure project :
Making snapshot build: testBranchGradle-SNAPSHOT
...
BUILD SUCCESSFUL in 17s
109 actionable tasks: 44 executed, 65 up-to-date

./gradlew clean

$ ./gradlew clean
> Configure project :
Making snapshot build: testBranchGradle-SNAPSHOT
...

BUILD SUCCESSFUL in 1s
34 actionable tasks: 34 executed

./gradlew assemble with -PpublishVersion=

 $ ./gradlew assemble -PpublishVersion=TestCase

> Configure project :
Making snapshot build: TestCase-SNAPSHOT
...
BUILD SUCCESSFUL in 22s
108 actionable tasks: 106 executed, 2 up-to-date

Create a tag: git tag -s metafacture-core-7.0.1-rc8

./gradlew assemble -PpublishVersion=7.0.1-rc8

 ./gradlew assemble -PpublishVersion=7.0.1-rc8

> Configure project :
Making release candidate build: 7.0.1-rc8-SNAPSHOT
...
BUILD SUCCESSFUL in 11s
108 actionable tasks: 43 executed, 65 up-to-date

./gradlew assemble -PpublishVersion=7.0.1-rc9 fails because the tag has a different name.

 ./gradlew assemble -PpublishVersion=7.0.1-rc9

FAILURE: Build failed with an exception.

* Where:
Build file '/home/tobias/git/metafacture-core/build.gradle' line: 369

* What went wrong:
A problem occurred evaluating root project 'metafacture-core'.
> HEAD has no matching annotated tag: metafacture-core-7.0.1-rc9

* Try:
> Run with --stacktrace option to get the stack trace.
> Run with --info or --debug option to get more log output.
> Run with --scan to get full insights.
> Get more help at https://help.gradle.org.

BUILD FAILED in 492ms

When adding a commit and creating a new tag this works.

When changes were added but not commited,

$ ./gradlew assemble -PpublishVersion=7.0.1-rc9

FAILURE: Build failed with an exception.

* Where:
Build file '/home/tobias/git/metafacture-core/build.gradle' line: 355

* What went wrong:
A problem occurred evaluating root project 'metafacture-core'.
> Working copy has modifications

* Try:
> Run with --stacktrace option to get the stack trace.
> Run with --info or --debug option to get more log output.
> Run with --scan to get full insights.
> Get more help at https://help.gradle.org.

BUILD FAILED in 1s

Interestingly release candidates do not complain if singing credentials in gradle.properties are added or not. It always seems to work.
Try to create a release, without tag, fails as intended.

$ ./gradlew assemble -PpublishVersion=7.0.1

FAILURE: Build failed with an exception.

* Where:
Build file '/home/tobias/git/metafacture-core/build.gradle' line: 369

* What went wrong:
A problem occurred evaluating root project 'metafacture-core'.
> HEAD has no matching annotated tag: metafacture-core-7.0.1

* Try:
> Run with --stacktrace option to get the stack trace.
> Run with --info or --debug option to get more log output.
> Run with --scan to get full insights.
> Get more help at https://help.gradle.org.

BUILD FAILED in 498ms

Try to create a release, with matching tag, but without signing credentials fails as intended.

$ ./gradlew assemble -PpublishVersion=7.0.1

> Configure project :
Making release build: 7.0.1

> Task :metafacture-runner:signArchives FAILED

[Incubating] Problems report is available at: file:///home/tobias/git/metafacture-core/build/reports/problems/problems-report.html

FAILURE: Build failed with an exception.

* What went wrong:
Execution failed for task ':metafacture-runner:signArchives'.
> Cannot perform signing task ':metafacture-runner:signArchives' because it has no configured signatory

* Try:
> Run with --stacktrace option to get the stack trace.
> Run with --info or --debug option to get more log output.
> Run with --scan to get full insights.
> Get more help at https://help.gradle.org.

Deprecated Gradle features were used in this build, making it incompatible with Gradle 9.0.

You can use '--warning-mode all' to show the individual deprecation warnings and determine if they come from your own scripts or plugins.

For more on this, please refer to https://docs.gradle.org/8.14.2/userguide/command_line_interface.html#sec:command_line_warnings in the Gradle documentation.

BUILD FAILED in 3s
91 actionable tasks: 33 executed, 58 up-to-date

10 Building release with tag and credentials works:

$ ./gradlew assemble -PpublishVersion=7.0.1

> Configure project :
Making release build: 7.0.1

[Incubating] Problems report is available at: file:///home/tobias/git/metafacture-core/build/reports/problems/problems-report.html

Deprecated Gradle features were used in this build, making it incompatible with Gradle 9.0.

You can use '--warning-mode all' to show the individual deprecation warnings and determine if they come from your own scripts or plugins.

For more on this, please refer to https://docs.gradle.org/8.14.2/userguide/command_line_interface.html#sec:command_line_warnings in the Gradle documentation.

BUILD SUCCESSFUL in 13s
109 actionable tasks: 12 executed, 97 up-to-date

blackwinter · 2025-07-29T14:14:39Z

Thanks a lot for the thorough review! Does this mean you approve the pull request?

The documentation is not very clear with regard to the signing creadentials and that additionally to the gradle credentials git needs gpg credentials to be able to create a signed tag.

Just to be clear: This isn't related to the current pull request; signed tags have already been part of the workflow.

In my current test it seems that only for creating a release and not for creating a rc signing credentials for gradle are needed.

That's correct and hasn't changed with this pull request. Why do think release candidates should be signed?

It seems to be new

~~Is there something missing here? What "seems to be new"?~~Section has been updated by @TobiasNx.

Interestingly release candidates do not complain if singing credentials in gradle.properties are added or not. It always seems to work.

See above.

TobiasNx · 2025-07-29T14:26:13Z

Thanks a lot for the thorough review! Does this mean you approve the pull request?

yes

The documentation is not very clear with regard to the signing creadentials and that additionally to the gradle credentials git needs gpg credentials to be able to create a signed tag.

Just to be clear: This isn't related to the current pull request; signed tags have already been part of the workflow.

Yes, but testing the changes showed a couple of flaws in our documentation.

In my current test it seems that only for creating a release and not for creating a rc signing credentials for gradle are needed.

That's correct and hasn't changed with this pull request. Why do think release candidates should be signed?

MAINTINGING.md says the following:

metafacture-core/MAINTAINING.md

Line 34 in 2debe28

    
           To upload to Sonatype you need (as well for the release candidate as for the release) a `gradle.properties` in the root directory that looks like this:

blackwinter · 2025-07-29T14:38:12Z

When building a release candidate this is handled as Snapshot and the build gets a -SNAPSHOT suffix, is this correct?

Again, this behaviour hasn't changed:

metafacture-core/build.gradle

Lines 354 to 357 in d835ff4

    
           if (grgit.branch.current().name.contains('-rc')) { 
        
             logger.lifecycle('Release candidate branch found') 
        
             return "${grgit.branch.current().name}-SNAPSHOT" 
        
           }

See also:

metafacture-core/MAINTAINING.md

Line 88 in d835ff4

    
           1. Make an annotated signed tag (it's important to do that _after_ uploading to Sonatype's snapshot repository because otherwise the `-SNAPSHOT` will not be appended to the release candidate thus will not land in `snapshot repository`):

blackwinter · 2025-07-29T14:38:33Z

To upload to Sonatype you need (as well for the release candidate as for the release) a gradle.properties in the root directory that looks like this:

I see, thanks. I'll leave it for @dr0i to give his reasons for the comment (introduced in e95332d).

dr0i · 2025-09-23T12:08:12Z

We need signing all files when uploading to maven central. There are other possibilities to using gpg but why not using gpg ?

blackwinter · 2025-09-23T12:12:25Z

Can you please elaborate? How is the signing currently done in master and how is it (not) done here? I can't see any changes related to signing...

dr0i · 2025-09-23T12:37:49Z

Idk, you came up with the question in #700 (comment) . I don't see that you removed any information re signing so I am (still) good.
I am unasigning me here.

dr0i · 2025-09-23T12:41:20Z

build.gradle

-      scmInfo.isRelease()
+      scmInfo.isRelease
    }
    sign publishing.publications.mavenArtifacts


This is the The Signing Plugin, no? It needs the gpg properties as explained here : https://docs.gradle.org/current/userguide/signing_plugin.html

Yes, it is, and it does. @TobiasNx: Is there anything that needs to be changed in the context of this pull request or can we merge?

With regard to code I dont know. With regard to the build process of RC I think both of my questions are still unanswered: #700 (comment)
If @dr0i says that is irrelevant go ahead.

With regard to the documentation of the Signing Plugin we could open another ticket where we could improve it.

blackwinter · 2025-09-23T12:44:32Z

So it's a discussion between you and @TobiasNx then. Maybe you can continue elsewhere if there's nothing actually blocking this pull request?

TobiasNx · 2025-09-24T06:45:54Z

Perhaps I am wrong, but there are still two questions for @dr0i that were not answered. Both are related to release candidates:

One regarding the SNAPSHOT suffix on release candidates:

2. When building a release candidate this is handled as Snapshot and the build gets a -SNAPSHOT suffix, is this correct? @dr0i I remember that you complained when I was uploading the last release candidate for the first time that the runner archives should not have SNAPSHOT in the name and the build should be named "metafacture-core-A.B.C-rcN" See test 4.

Create a tag: git tag -s metafacture-core-7.0.1-rc8

./gradlew assemble -PpublishVersion=7.0.1-rc8

./gradlew assemble -PpublishVersion=7.0.1-rc8

Configure project :
Making release candidate build: 7.0.1-rc8-SNAPSHOT
...
BUILD SUCCESSFUL in 11s
108 actionable tasks: 43 executed, 65 up-to-date

(See here: #700 (comment)) To be specific I uploaded the RC only to Github packages: https://github.com/metafacture/metafacture-core/releases/tag/metafacture-core-7.0.0-rc1)

One regarding the Singing of release candidates, see #700 (comment):
I saw that when building a RC no gradle credentials for signing were needed but the documentation states that RCs need signing. @blackwinter asked why release candidates need signing and why @dr0i introduced the requirement here: https://github.com/metafacture/metafacture-core/wiki/Maintainer-Guidelines/_compare/bff60478201c92d05baee267ce470bde22dfb2b4...e95332d7a06f81ef3bf1ab1d777c08d93856ffb6

blackwinter · 2025-09-24T08:58:03Z

Sorry to keep belaboring this point, but neither of your questions is related to the modifications made here. The behaviour is unchanged. It's okay to discuss and maybe improve the documentation and/or the code, but any action to be taken is out-of-scope for this pull request, isn't it?

TobiasNx · 2025-09-25T08:42:24Z

@blackwinter talked to @dr0i go ahead, we will adjust any documentation later.

Fix internal link in MAINTAINING.md. (#591)

5d3f4e8

blackwinter requested review from TobiasNx and dr0i June 24, 2025 14:32

blackwinter assigned dr0i Jun 24, 2025

blackwinter added the Dev Infrastructure label Jun 24, 2025

blackwinter added this to Metafacture Jun 24, 2025

blackwinter moved this to Review in Metafacture Jun 24, 2025

blackwinter assigned TobiasNx Jun 24, 2025

blackwinter force-pushed the 684-simplifyGradleBuildLogic branch from dfee37c to ab7f368 Compare June 25, 2025 09:26

dr0i approved these changes Jul 1, 2025

View reviewed changes

MAINTAINING.md Show resolved Hide resolved

dr0i removed their assignment Jul 1, 2025

blackwinter assigned dr0i Jul 1, 2025

dr0i removed their assignment Jul 1, 2025

TobiasNx assigned blackwinter and unassigned TobiasNx Jul 14, 2025

blackwinter assigned TobiasNx and unassigned blackwinter Jul 14, 2025

Use environment variable in GitHub workflow. (#700)

2debe28

In order to minimize risk of injection attacks.

TobiasNx reviewed Jul 18, 2025

View reviewed changes

MAINTAINING.md Show resolved Hide resolved

blackwinter requested a review from TobiasNx July 18, 2025 08:55

TobiasNx approved these changes Jul 29, 2025

View reviewed changes

blackwinter assigned dr0i Jul 29, 2025

blackwinter unassigned TobiasNx Jul 29, 2025

dr0i assigned blackwinter and unassigned dr0i Sep 23, 2025

dr0i mentioned this pull request Sep 23, 2025

Use jreleaser for publishing to central.sonatype.com #677

Closed

blackwinter assigned dr0i and unassigned blackwinter Sep 23, 2025

dr0i removed their assignment Sep 23, 2025

dr0i reviewed Sep 23, 2025

View reviewed changes

blackwinter assigned TobiasNx Sep 23, 2025

TobiasNx assigned dr0i and unassigned TobiasNx Sep 24, 2025

TobiasNx assigned blackwinter and unassigned dr0i Sep 25, 2025

blackwinter merged commit bcef668 into master Sep 25, 2025
1 check passed

github-project-automation bot moved this from Review to Done in Metafacture Sep 25, 2025

blackwinter deleted the 684-simplifyGradleBuildLogic branch September 25, 2025 08:54

Simplify Gradle build logic for making releases. #700

Simplify Gradle build logic for making releases. #700

Uh oh!

Conversation

blackwinter commented Jun 24, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

dr0i left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

TobiasNx commented Jul 14, 2025

Uh oh!

blackwinter commented Jul 14, 2025

Uh oh!

Uh oh!

TobiasNx commented Jul 29, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

blackwinter commented Jul 29, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

TobiasNx commented Jul 29, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

blackwinter commented Jul 29, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

blackwinter commented Jul 29, 2025

Uh oh!

dr0i commented Sep 23, 2025

Uh oh!

blackwinter commented Sep 23, 2025

Uh oh!

dr0i commented Sep 23, 2025

Uh oh!

dr0i Sep 23, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

blackwinter Sep 23, 2025

Choose a reason for hiding this comment

Uh oh!

TobiasNx Sep 24, 2025

Choose a reason for hiding this comment

Uh oh!

blackwinter commented Sep 23, 2025

Uh oh!

TobiasNx commented Sep 24, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

blackwinter commented Sep 24, 2025

Uh oh!

TobiasNx commented Sep 25, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

blackwinter commented Jun 24, 2025 •

edited

Loading

TobiasNx commented Jul 29, 2025 •

edited

Loading

blackwinter commented Jul 29, 2025 •

edited

Loading

TobiasNx commented Jul 29, 2025 •

edited

Loading

blackwinter commented Jul 29, 2025 •

edited

Loading

dr0i Sep 23, 2025 •

edited

Loading

TobiasNx commented Sep 24, 2025 •

edited

Loading