Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/offrange/git-semver-gradle-plugin

A Gradle plugin that automatically versions your project based on Git tags, following the Semantic Versioning 2.0 specification.
https://github.com/offrange/git-semver-gradle-plugin

gradle gradle-plugin semantic-versioning semver versioning-plugin

Last synced: about 2 months ago
JSON representation

A Gradle plugin that automatically versions your project based on Git tags, following the Semantic Versioning 2.0 specification.

Host: GitHub
URL: https://github.com/offrange/git-semver-gradle-plugin
Owner: OffRange
License: mit
Created: 2024-05-24T13:41:24.000Z (9 months ago)
Default Branch: 0.2.x
Last Pushed: 2024-08-13T10:36:41.000Z (6 months ago)
Last Synced: 2024-11-07T11:20:11.039Z (3 months ago)
Topics: gradle, gradle-plugin, semantic-versioning, semver, versioning-plugin
Language: Kotlin
Homepage:
Size: 134 KB
Stars: 2
Watchers: 1
Forks: 0
Open Issues: 0
Metadata Files:
- Readme: README.md
- License: LICENSE

Awesome Lists containing this project

README

# Git Semantic Versioning Gradle Plugin

This Gradle plugin leverages Git to manage project versioning, adhering to semantic versioning principles. It provides
several customization options, especially useful for development and debugging purposes.

## Getting Started

Add the plugin to your `build.gradle.kts` file:

```kotlin
plugins {
id("io.github.offrange.git-semantic-versioning")
}
```

## Usage

### Development Version Customizations

> [!NOTE]
> Customization options like `defaultIncrement` and `channel` are intended for development versions where no Git tag has
> been set yet. These customizations help in displaying the correct version during development and debugging.

> [!NOTE]
> An active Git tag on the latest commit will always override these custom modifications.

#### Pre-Release Channels

For instance, if you've published a beta version `1.0.0-beta.1` and are working on a release candidate, set the channel
to `Channel.RC` to ensure the version updates to `1.0.0-rc<+build-metadata>`.

```kotlin
versioning {
channel = Channel.RC
}
```

#### Incrementing Version Parts

If the release channel of the last version (determined by the latest git tag) and the `channel` property of the
extension is `Channel.STABLE` , or if the release channel of the last version
is newer than the release channel defined in the extension, the version is incremented by a strategy defined by
the `defaultIncrement` property

```kotlin
versioning {
defaultIncrement = Inc.MINOR
}
```

#### Incrementing Version Parts

The `defaultIncrement` property is used to define which part of the version should be incremented under certain
conditions. Specifically, this property comes into play when:

1. The current git tag indicates that the project's version is stable, and there has been at least one commit since this
tag. If the `channel` property is also set to `Channel.STABLE`, it implies that a new version is required.
The `defaultIncrement` property will determine which version part (e.g., major, minor, or patch) should be
incremented.

2. The release channel defined by the `channel` property is set to a "more unstable" version than the release channel of
the current/latest git tag version. For example, if the latest git tag is "1.0.0-rc.2" and the `channel` parameter is
set to `Channel.BETA`, the version will be incremented to "1.1.0-beta.1" (see the configuration below).

Here is how you can set the `defaultIncrement` property in your `versioning` configuration:

```kotlin
versioning {
defaultIncrement = Inc.MINOR
}
```

#### Full Commit Hash in Version Names

If you prefer including the full commit hash in the version name, set the `useShortHash` property to `false`.

```kotlin
versioning {
useShortHash = false
}
```

### Custom Version Code Generator

For Android projects, a default version code generator is provided. If you need a custom generator, specify it like
this:

```kotlin
versioning {
versionCodeGenerator = { version ->
computeUIntVersionCode(version)
}
}
```

### Applying the Plugin to Android Projects

To use this plugin for versioning your Android app, follow these steps:

1. Apply the plugin in your `build.gradle.kts` or `build.gradle` file as described in the Getting Started section.
2. Remove or comment out the `versionName` and `versionCode` properties in the `defaultConfig` block within
the `application` extension.
3. Apply the generated versioning source set `build/generated/versioning/kotlin` to your build.gradle.kts file.
4. Apply `android versionedBy versioning` to the root of your build.gradle.kts file
5. Apply `build/generated/versioning/kotlin` to your source set
6. Add `io.github.z4kn4fein:semver:2.0.0` dependency

```kotlin
android versionedBy versioning
android {
defaultConfig {
applicationId = "com.example.app"
minSdk = libs.versions.android.minSdk.get().toInt()
targetSdk = libs.versions.android.compileSdk.get().toInt()
// versionName = "1.0.0"
// versionCode = 1

testInstrumentationRunner = "androidx.test.runner.AndroidJUnitRunner"

vectorDrawables {
useSupportLibrary = true
}
}

sourceSets.getByName("main") {
kotlin.srcDir("build/generated/versioning/kotlin")
}
}

dependencies {
implementation("io.github.z4kn4fein:semver:2.0.0")
}
```

The plugin will automatically set the appropriate version name and version code based on the Git tags.