Release Process¶

This document covers the complete release workflow for Ansible Crafting, including the release scripts, splash tagline system, and changelog generation.

See also: CI/CD Pipeline for what happens after you push a release tag.

Overview¶

flowchart TD
    START["Developer runs release script"] --> VER_CHECK{"Version<br/>specified?"}
    VER_CHECK -->|"Yes"| CHECK["Precondition checks"]
    VER_CHECK -->|"No"| AUTO["Auto-detect version<br/>with git-cliff --bump"]
    AUTO --> CHECK
    CHECK -->|"Fail"| ABORT["❌ Abort with error"]
    CHECK -->|"Pass"| BUMP["Bump mod_version<br/>in gradle.properties"]
    BUMP --> CLIFF["Generate changelog<br/>with git-cliff"]
    CLIFF --> SPLASH{"Stable release?"}
    SPLASH -->|"Yes (e.g. 1.0.0)"| ASSIGN["Assign splash tagline<br/>from splash-taglines.txt"]
    SPLASH -->|"No (e.g. 1.0.0-alpha)"| SKIP["Skip splash tagline"]
    ASSIGN --> COMMIT["Commit + annotated tag"]
    SKIP --> COMMIT
    COMMIT --> PUSH{"--no-push?"}
    PUSH -->|"No"| GIT_PUSH["Push to origin/main"]
    PUSH -->|"Yes"| MANUAL["Manual push later"]
    GIT_PUSH --> CI["GitLab CI picks up tag<br/>→ build → test → release"]

Release Scripts¶

Two equivalent scripts are provided — use whichever matches your shell:

Both scripts perform identical operations:

1. Auto-detect version with git-cliff --bump (if no version specified), with a 10-second confirmation prompt
2. Validate preconditions (branch, clean tree, tag doesn't exist, git-cliff installed)
3. Bump version in gradle.properties
4. Generate changelog with git-cliff (--bump for auto-detected, --tag for explicit)
5. Assign splash tagline (stable releases only)
6. Commit and tag
7. Push to origin (unless --no-push / -NoPush)

Prerequisites¶

Before running either script, ensure:

• git-cliff is installed:
• Windows: winget install git-cliff
• macOS: brew install git-cliff
• Linux: See git-cliff installation
• You are on the main branch
• Your working tree is clean (no uncommitted changes)
• You are up to date with origin/main (no commits ahead or behind)
• The target version tag doesn't already exist

PowerShell Usage (Windows)¶

# From the ansible-crafting/ directory:

# Auto-detect version from commit history (recommended)
./scripts/release.ps1

# Explicit version
./scripts/release.ps1 0.2.0

# Dry run — preview changes without committing
./scripts/release.ps1 -DryRun
./scripts/release.ps1 0.2.0 -DryRun

# Commit and tag but skip pushing
./scripts/release.ps1 -NoPush
./scripts/release.ps1 0.2.0 -NoPush

# Non-interactive — skip all prompts (useful for CI)
./scripts/release.ps1 -Yes
./scripts/release.ps1 -y

Windows Execution Policy: If Windows blocks the script, use one of:

# One-time bypass
powershell -ExecutionPolicy Bypass -File ./scripts/release.ps1

# Permanent fix for your user account
Set-ExecutionPolicy RemoteSigned -Scope CurrentUser

Bash Usage (Linux/macOS)¶

# From the ansible-crafting/ directory:

# Auto-detect version from commit history (recommended)
./scripts/release.sh

# Explicit version
./scripts/release.sh 0.2.0

# Dry run — preview changes without committing
./scripts/release.sh --dry-run
./scripts/release.sh 0.2.0 --dry-run

# Commit and tag but skip pushing
./scripts/release.sh --no-push
./scripts/release.sh 0.2.0 --no-push

# Non-interactive — skip version confirmation prompt (useful for CI)
./scripts/release.sh -y
./scripts/release.sh --yes

Flag Reference¶

Version Format¶

Versions must follow Semantic Versioning:

Splash Tagline System¶

Each stable release gets a unique Minecraft-themed tagline that appears in the changelog as a diamond-emoji blockquote:

💎 Forged in the Nether

How It Works¶

flowchart LR
    POOL["splash-taglines.txt<br/>(93 taglines)"] --> FILTER["Filter out<br/>already-used taglines"]
    USED["splash-assignments.txt<br/>(version → tagline map)"] --> FILTER
    FILTER --> PICK["Randomly select<br/>one unused tagline"]
    PICK --> SAVE["Save assignment<br/>to splash-assignments.txt"]
    SAVE --> INJECT["Inject into<br/>CHANGELOG.md"]

File: scripts/splash-taglines.txt¶

The pool of available taglines. One per line, blank lines and # comments are ignored.

# Minecraft splash taglines for release changelogs
Forged in the Nether
Crafted with Netherite
Enchanted at Level 30
Smelted in a Blast Furnace
...

To add new taglines: Simply append new lines to this file. The release script will automatically include them in the available pool.

Currently contains 93 taglines covering Minecraft mechanics, enchantments, mobs, and biomes.

File: scripts/splash-assignments.txt¶

Tracks which tagline was assigned to which version. Do not edit manually — this file is managed by the release script.

# Splash tagline assignments — maps each release version to its tagline.
# Managed by the release script. Do not edit manually.

1.0.0=Forged in the Nether
1.1.0=Enchanted at Level 30

Behavior¶

• Stable releases (1.0.0, 2.3.1): A tagline is randomly selected from unused taglines and assigned
• Pre-release versions (1.0.0-alpha, 1.0.0-rc.1): Taglines are skipped entirely
• Re-running for the same version: Reuses the previously assigned tagline (idempotent)
• Exhaustion: If all 93 taglines are used, the script aborts and asks you to add more

Changelog Injection¶

The tagline is injected into CHANGELOG.md under the version header:

## [1.0.0] - 2026-03-01

> 💎 Forged in the Nether

### ⛏️ New Blocks
- Added remote crafting feature

Changelog Generation¶

The changelog is auto-generated by git-cliff from your Git commit history using Conventional Commits.

Configuration: cliff.toml¶

The git-cliff configuration lives at the project root in cliff.toml. It maps conventional commit types to Minecraft-themed section headers:

Skipped types (not shown in changelog): test, ci, style, build, chore(release)

Conventional Commits¶

All commits must follow the format:

<type>(<optional scope>): <description>

Examples:

feat: add crafting table overlay
fix(inventory): resolve slot alignment issue
docs: update configuration reference
refactor(scanner): extract aggregation logic
perf: cache inventory scan results

See Guidelines — Git Practices for full commit conventions.

Manual Changelog Generation¶

You can regenerate the changelog without doing a release:

# Generate full changelog
git-cliff --output CHANGELOG.md

# Generate changelog for a specific unreleased tag
git-cliff --tag v0.2.0 --output CHANGELOG.md

# Preview release notes for the latest tag only
git-cliff --latest --strip header

Versioning Strategy¶

The project follows Semantic Versioning (MAJOR.MINOR.PATCH). Use these guidelines to determine which version component to bump:

When to Bump¶

Pre-Release Versions¶

Use pre-release suffixes for versions that aren't ready for general use:

Pre-release versions do not receive splash taglines in the changelog.

Automatic Version Bumping with git-cliff¶

The release scripts support automatic version detection via git-cliff --bump. This is the default behavior — when you run the script without a version argument, git-cliff analyzes your commit history since the last tag and determines the appropriate semver bump:

# Default: auto-detect version from commits (recommended)
./scripts/release.sh

# Equivalent PowerShell
./scripts/release.ps1

# Example: if last tag is v0.1.0 and you have feat: commits → releases v0.2.0
# Example: if last tag is v0.1.0 and you only have fix: commits → releases v0.1.1
# Example: if last tag is v0.1.0 and you have BREAKING CHANGE → releases v1.0.0

The bump logic follows Conventional Commits: - feat commits → bump MINOR - fix, perf, refactor commits → bump PATCH - BREAKING CHANGE footer or ! after type → bump MAJOR

Version Confirmation Prompt¶

When auto-detecting, the script shows the detected version and gives you 10 seconds to respond:

Auto-detected version: 0.2.0
Press Enter to accept, type a version to override, or wait 10s to auto-accept:
  >

This allows you to confirm the version is correct, override it if needed (e.g., to use a pre-release suffix), or let it proceed automatically in CI-like environments.

When to Use Explicit vs Auto-Detect¶

You can also preview what version git-cliff would suggest without running the release script:

# Preview the bumped version
git-cliff --bumped-version

Post-Release¶

After the release script pushes the tag, the GitLab CI/CD pipeline automatically:

1. Validates the tag is annotated (not lightweight)
2. Builds the mod for all Minecraft versions
3. Runs the test suite
4. Creates a GitLab Release with auto-generated release notes
5. Publishes to Modrinth — uploads the mod JAR + sources JAR, attaches release notes, and syncs the PROJECT.md content to the Modrinth project description
6. (Manual trigger) Deploys to CurseForge

See CI/CD Pipeline for details on each stage.