axion-release-plugin@v2

[bgalek]

Hello dear users!

I'm thinking about this project a lot, and I'm concerned that it has too many features for me to grasp.
I've certailny lost this project's scope really meant to be.
I'm almost not using it anymore myself since I mainly use GitHub's releases to handle my library releases.
With applications, I mostly rely on https://github.com/allegro-actions/next-version action.

I wanted to start a discussion about the most minimal set of features that the axion-release-plugin should provide - so that in the future, I could start rewriting this project.

For now, I'm sure that it:

• should give the user access to git tagged version (if any)
• should use specific strategies for popular CI server (GitHub, GitLab, Jenkins) and use their native APIs/EnvironmentVariables.
• should only fallback to using local .git when not on CI server
• should detect building from branches and create SNAPSHOT versions with branch names included if not tagged commit is being built
• should use filesystem .git files parsing instead of full-blown-git repository integration (just to simplify and speed up the code execution)
• will use Kotlin src instead of Groovy
• have some performance tests (I don't want this plugin to be slowing your builds down)

So basically this would mean not supporting a lot of other features.

I know that using v1 version with mono repositories, using better/newer ciphers, or local git configuration can be a pain now, but maybe there are some more things I should consider before I finalize the v2 feature set in my head.

So, if you stumble upon this post and feel like sharing what other features are crucial for you, please share your story.

[tacascer]

I love the feature set already listed in this post. This is all I would ever need!

[dsoneira]

It's understandable that maintaining this project is quite difficult when you're not the one who's created it in the first place. So first of all thank you for that 🙏

I really do welcome the move from Groovy to Kotlin. This is something that discouraged me in the past to contributing to the project.
Seeing that you are thinking about the future of the plugin is definitely a positive. I was getting worried a little bit since there seems some major work left to do in order to upgrade its own build to Gradle 8 / 9.

The standard axion-release-plugin features we currently use (in order of importance)

1. Current version

Based on latest tag (in branch) - add -SNAPSHOT if latest commit is not tagged.

2. Creating release (tag) / pushing tag

The basic release process (incl. dropping -SNAPSHOT, verifyRelease, createRelease, pushRelease) - since it wasn't mentioned explicitly.

3. Customizable tag prefix, incrementMinorIfNotOnRelease incrementer

We use release branches (e.g. release/1.20.x, release/1.21.x) where we only ever release hotfixes (1.20.1, 1.20.2, etc)
So we configure a custom tag prefix release/ and use the incrementMinorIfNotOnRelease version incrementer.

The non-standard axion-release-plugin features we currently use (in order of importance)

1. Hooking custom tasks into the release process

When releasing we also generate a changelog (toggable via property) via a Gradle task generateChangelog.
Gradle tasks should not be executed / invoked programatically - so using the axion-release-plugin hooks is hackish (especially when enabling / disabling Gradle tasks, e.g. via ./gradlew release -x generateChangelog)

This task generateChangelog changes some files which are committed as part of the release commit.

    scmVersion {
    // ...
            hooks {
                pre {
                    it.createReleaseCommit()
                }
            }
    }

private fun HookContext.createReleaseCommit() = commit(listOf("."), "[Lifecycle] Release version: $releaseVersion")

We ended up using a custom task setup by replacing release with a custom task which does nothing on its own. Basically it just acts as a lifecycle task (like build / check) and depends on other tasks to do the work (actions)

    with(tasks) {
            // ----- Base task setup
            replace(RELEASE_TASK, CustomReleaseTask::class)

            named(RELEASE_TASK) {
                dependsOn(VERIFY_RELEASE_TASK) // standard axion-release task
                dependsOn(PRE_RELEASE_TASK)
                dependsOn(CREATE_RELEASE_TASK) // standard axion-release task
                dependsOn(POST_RELEASE_TASK)
                dependsOn(PUSH_RELEASE_TASK) // standard axion-release task
            }

            register(PRE_RELEASE_TASK) {
                group = RELEASE_TASK_GROUP
                description = "Runs tasks before release"
                mustRunAfter(VERIFY_RELEASE_TASK)
            }

            register(POST_RELEASE_TASK) {
                group = RELEASE_TASK_GROUP
                description = "Runs tasks after release"
                mustRunAfter(CREATE_RELEASE_TASK)
            }

            named(CREATE_RELEASE_TASK) {
                mustRunAfter(PRE_RELEASE_TASK)
            }

            named(PUSH_RELEASE_TASK) {
                mustRunAfter(CREATE_RELEASE_TASK)
                mustRunAfter(POST_RELEASE_TASK)
            }

           // ------ Using our own DSL to register preRelease / postRelease / postPushRelease tasks
           configure<CustomReleasingExtension> {
              preRelease("generateChangelog")
              preRelease("resetMajorVersionMarker") // removes (comments out) `release.versionIncrementer=incrementMajor` in `gradle.properties`
              postRelease("deployToDokku")
              postPushRelease("updateGitHubReleases") // because the tag has to be present on GitHub for this to work
           }
    }

Please consider using something similar for the v2 version of axion-release.

2. useHighestVersion:

In our hotfixing workflow we first merge a fix to the oldest supported version. (e.g. release/1.20.x)
Then upmerge to all the more recent release branches (e.g. release/1.21.x, release/1.22.x)
And finally merge it back to main.
Consider the following setup (branch names / latest tag):

Setup branches

branch	latest tag
main	release/1.22.0
release/1.20.x	release/1.20.0
release/1.21.x	release/1.21.0
release/1.22.x	release/1.22.0

Creating a hotfix

git checkout release/1.20.x -b hotfix
touch hotfixed
git add .
git commit -m "hotfix"
# Hotfix gets merged by PR
git checkout release/1.20.x
git merge hotfix
 
./gradlew release

✅ Creates new tag: 1.20.1

Upmerging the hotfix

git checkout release/1.21.x
git merge release/1.20.x
 
./gradlew currentVersion

🟢 Expected: 1.21.1-SNAPSHOT
🔴 Actual: 1.20.2-SNAPSHOT (since the latest tag on this branch is now 1.20.1)

3. Configurable snapshot creator:

For applications which are deployed to AWS we use a configurable snapshot creator which includes the short commit SHA

    scmVersion {
    // ...
            snapshotCreator { _, scmPosition ->
                if (extension.snapshotWithHash.get()) {
                    "-${scmPosition.shortRevision}-SNAPSHOT"
                } else {
                    "-SNAPSHOT"
                }
            }
    }

4. Dry-Run (optional)

In our custom release extension DSL we support the dry-run functionality for tasks which are added to preRelease / postRelease.
Those tasks either:

• implement a marker interface DryRunnable - they know how to handle this themselves (e.g. output some logging message DRY-RUN: Generating changelog)
• are standard Gradle tasks - are skipped in a dry-run

abstract class CustomReleaseExtension {
	fun preRelease(vararg taskNames: String) {  
	    project.addReleaseHook(PRE_RELEASE_TASK, *taskNames)  
	}

	private fun Task.dryRunnableOrNoDryRunReleaseActive(): Boolean {
        if (this !is DryRunnable && isDryRunRelease()) {
            logger.quiet("DRY-RUN: Skipping task $name - Not DryRunnable")
            return false
        }

        return true
    }

	fun Task.isDryRunRelease(): Boolean {  
	    return project.gradle.taskGraph.hasTask(":$RELEASE_TASK") &&  
	        project.extensions.getByType<VersionConfig>().dryRun.get()  
	}

	/**  
	 * Adds a pre/post release task. *
	 * Consider making the task implement [DryRunnable] and log what it would normally do in dry-run mode. *
	 * Otherwise, the task is simply skipped during a dry-run.
	 * @param releasePhase: [PRE_RELEASE_TASK], [POST_RELEASE_TASK], or [RELEASE_TASK]
	 */  
	private fun Project.addReleaseHook(releasePhase: String, vararg taskNames: String) {  
	    for (task in taskNames) {  
	        tasks.named(releasePhase).configure {  
	            dependsOn(task)  
	        }  
	  
	        tasks.named(task).configure {  
	            onlyIf("Task is DryRunnable or no DRY-RUN release active") { dryRunnableOrNoDryRunReleaseActive() }  
	        }
	    }  
	}
	
}

We use the -Prelease.dryRun flag to test if our release process / conventions are working as intended by inspecting the DRY-RUN console output messages. Also by default it is enabled so that a developer / CI has to explicitly disable it in order to do a real release.

It's just some nice extra though, instead of using the standard Gradle --dry-run which at least shows all the tasks that would be executed and in which order.