build.gradle

buildscript {
    rootProject.version = '0.19.0-SNAPSHOT'
    rootProject.group = 'ch.tutteli.atrium'

    def toolProjectsFun = subprojects.findAll {
        it.projectDir.path.contains('/misc/tools/') || it.projectDir.path.contains('\\misc\\tools\\')
    }
    ext {
        // main
        kboxVersion = '0.15.1'
        kbox = { "ch.tutteli.kbox:kbox:$kboxVersion" }
        niokVersion = '1.4.7'
        niok = { "ch.tutteli.niok:niok:$niokVersion" }
        // keep in sync with /buildSrc/build.gradle.kts
        kotlinVersion = '1.3.72'

        // test
        jacocoToolVersion = '0.8.8'
        junitPlatformVersion = '1.8.2'
        jupiterVersion = '5.8.2'
        spekVersion = '2.0.12'
        spekExtensionsVersion = '1.2.1'
        spekExtensions = { "ch.tutteli.spek:tutteli-spek-extensions:$spekExtensionsVersion" }
        mockkVersion = '1.10.0'

        //TODO remove with 1.0.0
        mockitoKotlinVersion = '2.2.0'
        mockito = { "com.nhaarman.mockitokotlin2:mockito-kotlin:$mockitoKotlinVersion" }

        // project setup
        tutteli_plugins_version = '0.33.1'
        node_plugin_version = '3.4.0'
        d8_version = '1.6.84'

        // release
        gradle_nexus_publish_plugin_version = '1.1.0'

        //TODO 0.19.0 add all modules and remove this afterwards
        newMultiplatformProjectNames = [
            "core",
            "logic", "logic-kotlin_1_3",
            "translations-en_GB", "translations-de_CH",
            "api-fluent-en_GB", "api-fluent-en_GB-kotlin_1_3",
            "api-infix-en_GB", "api-infix-en_GB-kotlin_1_3",
            "fluent-en_GB",
            "infix-en_GB",
            "verbs",
            "verbs-internal",
            "specs"
        ]

        // gh-pages.gradle
        docProjects = (subprojects - toolProjectsFun).findAll {
            !it.name.endsWith("-js") &&
                !it.name.endsWith("-android") &&
                !it.name.contains("robstoll") &&
                !it.name.startsWith("${rootProject.name}-specs")

        }
        findSamples = { Collection<Project> projects ->
            projects.findAll { it.name.contains("-api-") }
                .collect { Paths.get(it.projectDir.absolutePath + "/src/test/kotlin/ch/tutteli/atrium/api/") }
                .findAll { Files.exists(it) }
                .collect {
                    List<java.nio.file.Path> l = Files.walk(it, 10).withCloseable { stream ->
                        return stream
                            .filter { file -> file.fileName.toString().endsWith("Samples.kt") }
                            .collect(Collectors.toList())
                    }
                    l.collect { it.toAbsolutePath().toString() }
                }.flatten()
        }

        ghPages_version = rootProject.version
        srcKotlin = 'src/main/kotlin'
        github_url = "https://github.com/robstoll/${rootProject.name}"
        dokka_sourceMapping = "tree/main"


        toolProjects = toolProjectsFun

        // jacoco-multi-project.gradle
        jacocoMulti = [
            sourceProjects:
                (subprojects - toolProjectsFun).findAll {
                    !it.name.endsWith("-js") &&
                        // would have two classes with the same name if we add it as project as well,
                        // (clashes with "${rootProject.name}-translations-en_GB"
                        it.name != "${rootProject.name}-translations-de_CH" &&
                        // does not make sense to listen specs in coverage
                        !it.name.startsWith("${rootProject.name}-specs") &&
                        !it.name.contains("smoke-test")

                },
            jacocoProjects:
                (subprojects - toolProjectsFun).findAll {
                    !(it.projectDir.path.contains("/translations/") || it.projectDir.path.contains("\\translations\\")) &&
                        !it.name.endsWith("-common") &&
                        !it.name.endsWith("-js") &&
                        !it.name.startsWith("${rootProject.name}-specs")
                }
        ]
    }

    repositories {
        gradlePluginPortal()
    }
    dependencies {
        classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlinVersion"
        classpath "ch.tutteli:tutteli-gradle-dokka:$tutteli_plugins_version"
        classpath "ch.tutteli:tutteli-gradle-kotlin-module-info:$tutteli_plugins_version"
        classpath "ch.tutteli:tutteli-gradle-kotlin-utils:$tutteli_plugins_version"
        classpath "ch.tutteli:tutteli-gradle-project-utils:$tutteli_plugins_version"
        classpath "ch.tutteli:tutteli-gradle-publish:$tutteli_plugins_version"
        classpath "ch.tutteli:tutteli-gradle-spek:$tutteli_plugins_version"
        classpath "com.github.node-gradle:gradle-node-plugin:$node_plugin_version"
        classpath "io.github.gradle-nexus:publish-plugin:$gradle_nexus_publish_plugin_version"
    }
}

apply plugin: "ch.tutteli.project.utils"
apply plugin: 'ch.tutteli.kotlin.utils'
kotlinutils.kotlinVersion = kotlinVersion

repositories {
    mavenCentral()
}

configurations {
    dependabot
}

dependencies {
    // helps dependabot to recognise versions which it should update
    dependabot "org.jacoco:org.jacoco.core:$jacocoToolVersion"
    dependabot "org.junit.jupiter:junit-jupiter-engine:$jupiterVersion"
    dependabot "org.junit.platform:junit-platform-console:$junitPlatformVersion"
    dependabot "ch.tutteli.spek:tutteli-spek-extensions:$spekExtensionsVersion"
    dependabot "ch.tutteli.niok:niok:$niokVersion"
    dependabot "ch.tutteli.kbox:kbox:$kboxVersion"

    //TODO remove with 1.0.0
    dependabot "com.nhaarman.mockitokotlin2:mockito-kotlin:$mockitoKotlinVersion"

}

subprojects {
    group = rootProject.group

    repositories {
        mavenCentral()
    }
}

def commonProjects = getCommonProjects()
def jsProjects = getJsProjects()

def newMultiplatformProjects = newMultiplatformProjectNames.collect { prefixedProject(it) }
configure(newMultiplatformProjects) { subproject ->
    apply plugin: "kotlin-multiplatform"

    kotlin {
        jvm {
            compilations.main.kotlinOptions {
                jvmTarget = "11"
            }
            compilations.test.kotlinOptions {
                jvmTarget = "11"
            }

            //for module-info.java and Java sources in test
            withJava()

            def testProvider = testRuns["test"].executionTask
            testProvider.configure {
                useJUnitPlatform {
                    includeEngines("spek2", "junit-jupiter")
                }
            }
        }
        //TODO 0.19.0 activate as soon as all modules have been transitioned to new MPP
//        js {
//            nodejs()
//        }

        targets.all {
            compilations.all {
                //TODO 0.20.0 or later once we drop support of Kotlin 1.2
                //kotlinOptions.allWarningsAsErrors = true
            }
        }

        sourceSets {
            commonMain {
                dependencies {
                    api(kotlin("stdlib-jdk8"))
                    api(kotlin("reflect"))
                }
            }
            commonTest {
                dependencies {
                    implementation kotlin('test-common')
                    implementation kotlin('test-annotations-common')
                }
            }

            jvmTest {
                dependencies {
                    implementation kotlin('test-junit')
                    runtimeOnly "org.junit.jupiter:junit-jupiter-engine:$jupiterVersion"
                    implementation("org.spekframework.spek2:spek-dsl-jvm:$spekVersion") {
                        exclude group: 'org.jetbrains.kotlin'
                    }
                    runtimeOnly("org.spekframework.spek2:spek-runner-junit5:$spekVersion") {
                        exclude group: 'org.jetbrains.kotlin'
                    }
                }
            }
            //TODO 0.19.0 activate once all are migrated to MPP
//            jsTest {
//                dependencies {
//                    implementation kotlin('test-js')
//                }
//            }

            all {
                languageSettings {
                    languageVersion = '1.2'
                    apiVersion = '1.2'
                    useExperimentalAnnotation('kotlin.Experimental')
                }
            }
            configureEach {
                if (it.name.endsWith("Test")) {
                    languageSettings {
                        languageVersion = '1.3'
                        apiVersion = '1.3'
                    }
                }
            }
        }
    }

    //TODO 0.19.0 update tutteli-gradle-plugins and remove as this is handled there
    // calling the Kotlin extension function in buildSrc
    ConfigureTestTasksKt.configureTestTasks(subproject)

    sourceCompatibility = 11
    targetCompatibility = 11

    //TODO 0.19.0 update tutteli-gradle-plugins and remove as this is handled there and allows to use the normal java/ directory instead of module/
    def moduleInfoReplaceMe = {
        if (subproject.components.findByName('java') == null) throw new IllegalStateException("""\
            Could not find the java component.
            Did you forget to apply the kotlin plugin? Make sure it is applied before this plugin.
            """.stripIndent()
        )

        def srcModule = "src/module"
        def moduleInfo = subproject.file("$srcModule/module-info.java")

        if (moduleInfo.exists()) {

            subproject.sourceSets {
                module {
                    java {
                        srcDirs = [srcModule]
                        compileClasspath = main.compileClasspath
                    }
                }
                main {
                    kotlin { srcDirs += [srcModule] }
                }
            }
            subproject.compileModuleJava.configure {
                dependsOn subproject.jvmMainClasses

                //TODO 0.19.0 use this as soon as sources are in default folder for jvmMain
                destinationDir = subproject.kotlin.jvm().compilations.main.output.classesDirs.getFiles().findAll { it.getPath().contains("kotlin") }[0]
//                destinationDir = project.compileKotlin.destinationDir
                doFirst {
                    options.compilerArgs = ['--module-path', classpath.asPath]
                    classpath = subproject.files()
                }
            }
            subproject.tasks.getByName('jvmJar').dependsOn subproject.compileModuleJava
        }
    }
    moduleInfoReplaceMe()
}

//TODO 0.19.0 cleanup this file once we have transitioned all modules to the new MPP plugin
configureCommonProjects()
configureAndroidProjects()
configureJsProjects()
configureJvmProjects()

configure(subprojects.findAll {
    def parentName = it.projectDir.parentFile.name
    it.name != "bc-tests" && parentName != "old" && parentName != "bc-tests"
} - commonProjects - jsProjects - newMultiplatformProjects) { subproject ->
    apply plugin: 'kotlin'
    dependencies {
        implementation "org.jetbrains.kotlin:kotlin-stdlib-jdk8:$kotlinVersion"
    }
    compileKotlin {
        kotlinOptions {
            jvmTarget = "11"
        }
    }
    compileTestKotlin {
        kotlinOptions {
            jvmTarget = "11"
        }
    }

    sourceCompatibility = 11
    targetCompatibility = 11
}

configure(commonProjects) {
    compileKotlinCommon {
        kotlinOptions.languageVersion = '1.2'
    }
    compileTestKotlinCommon {
        //TODO activate as soon as https://youtrack.jetbrains.com/issue/KT-30580 is fixed
        kotlinOptions.allWarningsAsErrors = false
    }
}
configure(jsProjects) { subProject ->
    compileKotlin2Js {
        kotlinOptions {
            if (subProject.name.startsWith("atrium-translations")) {
                //necessary as the module name is then also called atrium-translations-js and can be shared (the name) by the other translation modules
                outputFile = "$buildDir/classes/kotlin/main/atrium-translations-js.js"
            }
            languageVersion = '1.2'
        }
    }

    compileTestKotlin2Js {
        //TODO activate as soon as https://youtrack.jetbrains.com/issue/KT-21348 is fixed
        kotlinOptions.allWarningsAsErrors = false
    }
}

def nonCommonAndJsProjects = subprojects - commonProjects - jsProjects


//TODO 0.19.0 configure dokka plugins again also for newMultiplatformProjects
configure(nonCommonAndJsProjects - toolProjects - newMultiplatformProjects) { Project subproject ->
    apply plugin: 'ch.tutteli.dokka'
    apply plugin: 'ch.tutteli.kotlin.module.info'

    dokka {
        samples = findSamples([subproject])
    }
    compileKotlin {
        kotlinOptions {
            languageVersion = '1.2'
            //TODO activate as soon as https://youtrack.jetbrains.com/issue/KT-34257 is fixed
            allWarningsAsErrors = false
        }
    }
}

//allow kotlin 1.3 for kotlin_1_3 modules
configure(subprojects.findAll { it.name.endsWith('-kotlin_1_3-common') }) {
    compileKotlinCommon.kotlinOptions.languageVersion = '1.3'
}
configure(subprojects.findAll { it.name.endsWith('-kotlin_1_3-android') }) {
    compileKotlin.kotlinOptions.languageVersion = '1.3'
}
configure(subprojects.findAll { it.name.endsWith('-kotlin_1_3-js') }) {
    compileKotlin2Js.kotlinOptions.languageVersion = '1.3'
}
configure(subprojects.findAll { it.name.endsWith('-kotlin_1_3-jvm') }) {
    compileKotlin.kotlinOptions.languageVersion = '1.3'
}


def apiProjects = subprojects.findAll {
    it.name.startsWith("${rootProject.name}-api") &&
        (it.name.endsWith("-jvm") ||
            (it.name.endsWith("-common") && (it.name.contains("api-fluent-") || it.name.contains("api-infix-")))
        )
}
//testJar and testSourcesJar for bc-tests
configure(apiProjects) { apiProject ->
    createTestJarTask(apiProject)
    createTestSourcesJarTask(apiProject)
}

def bundleSmokeTests = subprojects.findAll { it.name.contains('-smoke-test') }

//TODO 0.19.0 newMultiPlatformProject have to be published differently
configure(subprojects - bundleSmokeTests - toolProjects - newMultiplatformProjects - jsProjects) { subproject ->
    apply plugin: 'ch.tutteli.publish'

    tutteliPublish {
        resetLicenses 'EUPL-1.2'
    }
}

//TODO 0.19.0 spek is used in another way, see above, but we have not yet applied the jacoco plugin
configure(jacocoMulti.jacocoProjects + getAndroidProjects() - newMultiplatformProjects) {
    apply plugin: 'ch.tutteli.spek'
    spek.version = spekVersion

    // we don't want to have a dependency on dl.bintray anymore (the current version of ch.tutteli.spek (which is old)
    // still adds it for convenience reasons.
    repositories.removeAll {
        it instanceof MavenArtifactRepository && (it as MavenArtifactRepository).url.toString().startsWith("https://dl.bintray.com")
    }

    dependencies {
        testImplementation mockito(), excludeKotlin
    }

    afterEvaluate {
        junitjacoco {

            jacoco {
                toolVersion = jacocoToolVersion
            }

            jacocoReport {
                if (project.hasProperty('jacocoAdditional')) {
                    project.jacocoAdditional.each { otherProject ->
                        sourceSets otherProject.sourceSets.main
                    }
                }
                reports {
                    html.enabled = true
                }
            }
        }
    }
}


// this is already configured for newMultiplatformProjects further above, thus the substraction
configure(subprojects - toolProjects - newMultiplatformProjects) {
    sourceSets {
        all {
            languageSettings {
                useExperimentalAnnotation('kotlin.Experimental')
            }
        }
    }
}

// takes some time to configure since gradle 6.9 so only if CI
if (Boolean.parseBoolean(System.getenv('CI'))) {
    apply from: 'gradle/scripts/check-dexer.gradle'
}
apply from: 'gradle/scripts/gh-pages.gradle'
apply from: 'gradle/scripts/jacoco-multi-project.gradle'

configure(bundleSmokeTests) {

    def suffix = "-smoke-test"
    def isABundleAndNotExtensionSmokeTest = it.name.endsWith(suffix)
    if (isABundleAndNotExtensionSmokeTest) {
        def bundleUnderTest = it.name.substring(0, it.name.indexOf(suffix))
        Project bundle = project(":$bundleUnderTest")

        description = "Represents a JDK >= 9 smoke test for $bundleUnderTest"

        sourceCompatibility = JavaVersion.current()
        targetCompatibility = JavaVersion.current()

        ext.jacocoAdditional = [bundle]

        sourceSets {
            // we are reusing the source from the bundle, so that we do not have to re-invent the spec
            test { kotlin { srcDirs += ["${bundle.projectDir}/src/test/kotlin"] } }
        }

        dependencies {
            //I don't see how to set up compileTestKotlin with --patch-module, so we have put the module-info.java directly in src/test/kotlin instead
            testImplementation bundle
        }
    }
}


import java.nio.file.Files
import java.nio.file.Paths
import java.util.stream.Collectors

List<Project> projectNamesToProject(String[] names) {
    names.collect { projectName -> prefixedProject(projectName) }
}

def createJsTestTask(String... subprojectNames) {
    configure(projectNamesToProject(subprojectNames)) {
        apply plugin: 'com.github.node-gradle.node'

        compileTestKotlin2Js.configure {
            kotlinOptions.moduleKind = "commonjs"
            kotlinOptions.sourceMap = true
            kotlinOptions.sourceMapEmbedSources = "always"
        }

        task populateNodeModules(type: Copy, dependsOn: compileKotlin2Js) {
            from compileKotlin2Js.destinationDir

            prefixedProject('verbs-internal').afterEvaluate {
                // TODO 0.19.0, check if still required with the new Kotlin MPP plugin
                configurations.testRuntimeClasspath.allDependencies.withType(ProjectDependency).each {
                    dependsOn(it.dependencyProject.assemble)
                }

                configurations.testRuntimeClasspath.each {
                    from zipTree(it.absolutePath).matching { include '*.js', '*.js.map' }
                }
            }

            into "${buildDir}/node_modules"
        }

        def nodeModulesParentDir = file("$rootProject.projectDir/gradle/")
        node {
            download = true
            npmVersion = '8.8.0'
            workDir = file("$rootProject.projectDir/.gradle/nodejs")
            npmWorkDir = file("$rootProject.projectDir/.gradle/npm")
            nodeModulesDir = nodeModulesParentDir
        }

        task runMocha(type: NpxTask, dependsOn: [compileTestKotlin2Js, populateNodeModules]) {
            command = "mocha"
            args = [compileTestKotlin2Js.outputFile.toString()]
        }
        test.dependsOn runMocha
    }
}

//TODO 0.19.0 this setup should no longer be necessary with the new js plugin, check once you re-activate JS target
// if this is true, then remove the definition below including createJsTestTask above
//TODO 0.19.0 enable JS-tests again once we use the new MPP plugins because then they should only re-run if something
// changed, in contrast to now where they re-run all the time
//if (Boolean.parseBoolean(System.getenv('CI'))) {
//    createJsTestTask(
//        'core-js',
//        'api-fluent-en_GB',
//        'api-infix-en_GB',
//        'fluent-en_GB-js',
//        'infix-en_GB-js'
//    )
//}

def useJupiter(String... projectNames) {
    configure(projectNamesToProject(projectNames)) {
        dependencies {
            testRuntimeOnly "org.junit.jupiter:junit-jupiter-engine:$jupiterVersion"
        }
        test {
            options {
                includeEngines 'junit-jupiter'
            }
        }
    }
}

useJupiter(
    //TODO 0.19.0 setup jupiter tests in a different way for new MPP
//    'core-jvm',
//    'api-fluent-en_GB',
//    'api-infix-en_GB',
)

def getSubprojectTasks(String name) {
    return subprojects.collect { it.tasks.findByName(name) }.findAll { it != null }
}

task publishForScala(description: 'fast publish to maven local for scala projects') {
    dependsOn getSubprojectTasks('publishToMavenLocal')
}

gradle.taskGraph.whenReady { graph ->
    if (graph.hasTask(':publishForScala')) {
        ['test', 'dokka', 'signTutteliPublication', 'validateBeforePublish', 'javadocJar', 'sourcesJar'].forEach {
            getSubprojectTasks(it).forEach { it.enabled = false }
        }
    }
}

apply plugin: "io.github.gradle-nexus.publish-plugin"
nexusPublishing {
    repositories {
        sonatype()
    }
}

/*
Release & deploy a commit
--------------------------------

1. update main:

Either use the following commands or the manual steps below

export ATRIUM_PREVIOUS_VERSION=0.18.0
export ATRIUM_VERSION=0.19.0
find ./ -name "*.md" | xargs perl -0777 -i \
   -pe "s@$ATRIUM_PREVIOUS_VERSION@$ATRIUM_VERSION@g;" \
   -pe "s@tree/main@tree/v$ATRIUM_VERSION@g;" \
   -pe "s@latest#/doc@$ATRIUM_VERSION/doc@g;"
perl -0777 -i \
  -pe "s@$ATRIUM_PREVIOUS_VERSION@$ATRIUM_VERSION@g;" \
  -pe "s@dokka_sourceMapping = \"tree/main\"@dokka_sourceMapping = \"tree/v$ATRIUM_VERSION\"@;" \
  -pe "s/rootProject.version = '$ATRIUM_VERSION-SNAPSHOT'/rootProject.version = '$ATRIUM_VERSION'/;" \
  ./build.gradle
perl -0777 -i \
  -pe 's/(<!-- for main -->\n)\n([\S\s]*?)(\n<!-- for a specific release -->\n)<!--\n([\S\s]*?)-->\n(\n# <img)/$1<!--\n$2-->$3\n$4\n$5/;' \
  -pe 's/(---\n❗ You are taking[^-]*?---)/<!$1>/;' \
  ./README.md
git commit -a -m "v$ATRIUM_VERSION"

check changes
git push

alternatively the manual steps:

    a) change rootProject.version in build.gradle to X.Y.Z
    b) search for old version in README.md and replace with new
    c) search for `tree/main` in all .md files and replace it with `tree/vX.Y.Z`
    d) adjust dokka_sourceMapping from `tree/main` to tree/vX.Y.Z
    e) search for `latest#/doc` in all .md files and replace with `X.Y.Z/doc`
    f) use the release badges in README (comment out the ones for main and uncomment the ones for the release)
    g) comment out the warning in README.md about taking a sneak peak
    h) commit & push (modified CONTRIBUTING.md, differences.md, build.gradle and README.md)

2. prepare release on github
    a) git tag "v$ATRIUM_VERSION"
    b) git push origin "v$ATRIUM_VERSION"
    c) Log in to github and create draft for the release

The tag is required for dokka in order that the externalLinkDocumentation and source-mapping works

3. update github pages:
Assumes you have a atrium-gh-pages folder on the same level as atrium where the gh-pages branch is checked out

Either use the following commands or the manual steps below (assuming ATRIUM_VERSION is already set from commands above)

gr ghPages
cd ../atrium-gh-pages
perl -0777 -i \
  -pe "s@$ATRIUM_PREVIOUS_VERSION@$ATRIUM_VERSION@g;" \
  ./latest/index.html
perl -0777 -i \
  -pe "s@(- \[$ATRIUM_PREVIOUS_VERSION\]\($ATRIUM_PREVIOUS_VERSION\))@- \[$ATRIUM_VERSION\]\($ATRIUM_VERSION\)\n\$1@;" \
  ./README.md
git add . && git commit -m "v$ATRIUM_VERSION"

check changes
git push

cd ../atrium

alternatively the manual steps:
    a) gr ghPages
    b) change version number in atrium-gh-pages/latest/index.html
    c) add new version to atrium-gh-pages/README.md
    d) commit & push changes

3. deploy to maven central:
(assumes you have an alias named gr pointing to ./gradlew)
    a) java -version 2>&1 | grep "version \"11" && CI=true gr clean publishToSonatype
    b) Log into https://oss.sonatype.org/#stagingRepositories
    c) check if staging repo is ok
    d) close repo
    e) release repo

4. publish release on github
    1) Log in to github and publish draft

Prepare next dev cycle
-----------------------
    1. update main:

Either use the following commands or the manual steps below

export ATRIUM_VERSION=0.18.0
export ATRIUM_NEXT_VERSION=0.19.0
find ./ -name "*.md" | xargs perl -0777 -i \
   -pe "s@tree/v$ATRIUM_VERSION@tree/main@g;" \
   -pe "s@$ATRIUM_VERSION/doc@latest#/doc@g;" \
   -pe "s/add \\\`\@since $ATRIUM_VERSION\\\` \(adapt to current/add \\\`\@since $ATRIUM_NEXT_VERSION\\\` \(adapt to current/g;"
perl -0777 -i \
  -pe "s@dokka_sourceMapping = \"tree/v$ATRIUM_VERSION\"@dokka_sourceMapping = \"tree/main\"@;" \
  -pe "s/rootProject.version = '$ATRIUM_VERSION'/rootProject.version = '$ATRIUM_NEXT_VERSION-SNAPSHOT'/;" \
  -pe "s/ATRIUM_VERSION=$ATRIUM_VERSION/ATRIUM_VERSION=$ATRIUM_NEXT_VERSION/;" \
  ./build.gradle
perl -0777 -i \
  -pe 's/(<!-- for main -->\n)<!--\n([\S\s]*?)-->(\n<!-- for a specific release -->)\n([\S\s]*?)\n(\n# <img)/$1\n$2$3\n<!--$4-->\n$5/;' \
  -pe 's/<!(---\n❗ You are taking[^-]*?---)>/$1/;' \
  -pe "s@(For instance, the \[README of v$ATRIUM_VERSION\].*tree/)main/@\$1v$ATRIUM_VERSION/@;" \
  ./README.md
git commit -a -m "prepare dev cycle of $ATRIUM_NEXT_VERSION"

check changes
git push

alternatively the manual steps:

    a) search for `tree/vX.Y.Z` in all .md and build.gradle files and replace it with `tree/v0.12.0`
b) search for `X.Y.Z/doc` in all .md files and replace with `latest#/doc`
   c) use the main badges in README (uncomment them in README and comment out release badges)
   d) uncomment the warning about taking a sneak peek in README and revert `tree/v0.12.0` still point to the tag
e) change rootProject.version in build.gradle to X.Y.Z-SNAPSHOT
f) commit & push changes

2. establish backward compatibility tests for the previous version
a) append new version to bcConfigs in settings.gradle.kts
b) git commit -a -m "establish backward compatibility tests for v$ATRIUM_VERSION"
c) commit & push changes

3. update samples (optional, since dependabot will create pull requests)
a) use newly released version in samples (search again for the old-version and replace with new)
b) commit & push changes

*/