repo.yaml

---
repoOwner: "metaborg"
repoName: "gitonium"
mainBranch: "master"

title: "Gitonium"
description: |
  Gitonium is a Gradle plugin for automatic versioning based on the current Git branch and/or tag.
inceptionYear: "2018"
documentationLink: "https://spoofax.dev/gitonium/"

spoofax3Plugins:
  - id: "org.metaborg.gitonium"
    description: "Gitonium plugin"

contributors:
  - id: "Gohla"
    name: "Gabriel Konat"
  - id: "Virtlink"
    name: "Daniel A. A. Pelsmaeker"

developers:
  - id: "Apanatshka"
    name: "Jeff Smits"

files:
  githubWorkflows:
    publishRelease: true
    publishSnapshot: true
    buildDocs: true
    publishTask: ":plugin:publish"
    printVersionTask: ":plugin:printVersion"
  gradleRootProject:
    update: false
    createPublishTasks: true
    rootProjectName: "gitonium-project"
    includedBuilds:
      - path: "plugin/"
      - path: "example/"
  githubIssueTemplates:
    generate: false
  readme:
    body: |
      ## Requirements
      Gradle 7 or higher is required. The code snippets in this README assume you are using Gradle with Kotlin, but should be translatable to Groovy as well.


      ## Prerequisites
      The Gitonium plugin is not yet published to the Gradle plugins repository. Therefore, to enable downloading the plugin, add our repository to your `settings.gradle(.kts)` file:

      ```kotlin
      pluginManagement {
          repositories {
              maven("https://artifacts.metaborg.org/content/repositories/releases/")
          }
      }
      ```


      ## Applying the plugin
      Apply the gitonium plugin to a project (a `build.gradle(.kts)` file) as follows:

      ```kotlin
      plugins {
          id("org.metaborg.gitonium") version "<version>"
      }

      version = gitonium.version
      ```

      The latest version of the plugin can be found at the top of this README. Gitonium will then lazily set the version of the project, and all sub-projects, to a version based on the Git repository. To override the version of a project, simply set the version manually, and this will override the lazily set version.


      ## Usage
      Gitonium sets the version of the project based on the latest version tag (of the form `release-{version}`) found on the current branch. For example, if the HEAD of the current branch is tagged `release-0.1.3`, then the version is assigned `0.1.3`. Alternatively, if an earlier commit on the `develop` branch is tagged `release-0.1.3`, then the version `0.1.4-develop-SNAPSHOT` is assigned, one patch version higher than the last release.

      If no release tag was found, the version is not set and therefore defaults to Gradle's default version of `unspecified`.

      If the repository has no HEAD, Gitonium will fail.

      > [!IMPORTANT]
      > A shallow clone of a repository (as commonly performed by CI) might not checkout the tags of the repository.
      > In this case, Gitonium will fail to find the version tag.
      >
      > For example, when using GitHub CI `actions/checkout` action, specify a non-shallow checkout including tags:
      >
      > ```yaml
      > - name: Checkout
      >   uses: actions/checkout@v4
      >   with:
      >     fetch-depth: 0
      >     fetch-tags: true
      >  ```