VISTA: CEIE Custom Versioning Model (v4.0)

Prerequisites

• Gradle: Version 7.0 or higher (Gradle Wrapper recommended).
• JDK: Java 11 or higher, to support Kotlin-based plugins and tasks.
• Git: Version 2.x+ for extracting commit metadata.
• version.properties (optional): File in project root to specify explicit version overrides.

Plugin Installation

Apply the VISTA plugin via the Gradle Plugins DSL in your settings.gradle.kts or build.gradle.kts:

plugins {
                      id("io.ceie.vista") version "4.0.0"
                    }
                    

The plugin is published to the central Gradle Plugin Portal and automatically downloaded during the build initialization phase.

Configuration

Configure VISTA by declaring a vista extension in your build.gradle.kts:

vista {
                      // Path to an optional version.properties file
                      versionFile.set(file("version.properties"))
                    
                      // Automatic semantic version increments based on Git commits
                      autoIncrement.set(true)
                    
                      // Versioning strategy: "semantic" | "calendar" | "custom"
                      strategy.set("semantic")
                    
                      // Prefix for Git-generated tags (e.g., "v" to produce "v1.2.3")
                      tagPrefix.set("v")
                    
                      // Property name to inject computed version into project.version
                      propertyName.set("projectVersion")
                    }
                    

- versionFile: Allows explicit version overrides when present.
- autoIncrement: Enables automatic bumping based on commit types (feat, fix, BREAKING CHANGE).
- strategy: “semantic” uses Conventional Commits; other strategies may be defined by user extensions.

Version Properties

When present, version.properties in the project root defines an explicit version:

version=2.3.0
                        buildMetadata=20250419.1234
                        

VISTA reads this file before Git analysis and respects the version value, allowing manual overrides for hotfixes or emergency releases.

Provided Tasks

• vistaGenerateVersion Calculates the next version and writes to version.properties (if enabled).
• vistaApplyVersion Sets project.version to the computed or overridden version before compilation.
• vistaRelease Tags the Git repository with the computed version tag (e.g., “v2.3.0”) and pushes the tag to origin.
• vistaRollback Reverts version.properties and Git tags to the previous stable version.

jobs:
                            release:
                              runs-on: ubuntu-latest
                              steps:
                                - uses: actions/checkout@v2
                                - uses: actions/setup-java@v3
                                  with:
                                    distribution: 'temurin'
                                    java-version: '11'
                                - name: Generate and Apply Version
                                  run: ./gradlew vistaGenerateVersion vistaApplyVersion
                                - name: Build
                                  run: ./gradlew build
                                - name: Tag Release
                                  run: ./gradlew vistaRelease