Release Process¶

This document describes the versioning strategy and release process for this dotfiles repository.

Current Version¶

Version: 1.6.0 (as of 2026-02-04)

The current version is tracked in the ROADMAP.md and CHANGELOG.md files.

Versioning Strategy¶

This project follows Semantic Versioning 2.0.0:

• Major (X.y.z): Breaking changes to dotfiles structure, command interfaces, or required dependencies
• Minor (x.Y.z): New features, enhancements, or non-breaking additions
• Patch (x.y.Z): Bug fixes, documentation updates, minor improvements

Examples¶

• 1.4.0 → 2.0.0: Breaking change (unified command interface removed old aliases)
• 1.5.0 → 1.6.0: New features added (new mise tasks, documentation improvements)
• 1.6.0 → 1.6.1: Bug fixes only (would be a patch release)

Minimum Chezmoi Version: .chezmoiversion¶

The .chezmoiversion file at the repository root specifies the minimum required chezmoi version:

2.15.0

This ensures users have a compatible chezmoi installation before applying dotfiles.

Why Version 2.15.0?¶

• Template Features: Uses .chezmoitemplates/ and advanced templating
• Ignore Patterns: Relies on .chezmoiignore template support
• Data Files: Uses .chezmoidata.yaml for distro-specific configuration

Updating the Minimum Version¶

Only update .chezmoiversion when: 1. A new chezmoi feature becomes required (not optional) 2. A critical bug fix in chezmoi is needed 3. Compatibility with older versions becomes unmaintainable

Test with the new minimum version before updating:

chezmoi --version  # Verify local version
# Test full apply workflow
chezmoi apply --dry-run --verbose

Tool Version Pinning¶

Language runtimes and critical tools follow a partial pinning strategy (see ADR-009):

Pinned Tools (major.minor)¶

• node: lts - Node.js LTS releases
• python: 3.13 - Stable branch (3.13.x patches auto-update)
• rust: 1.93 - Stable channel (1.93.x patches auto-update)

Unpinned Tools (latest)¶

• CLI utilities: bat, eza, fd, ripgrep, fzf, etc.
• Development tools: lazygit, neovim, glow
• Linters/formatters: shellcheck, shfmt, yamllint

Update Policy¶

1. Patch versions (x.y.Z): Auto-update via mise (no PR needed)
2. Minor versions (x.Y.z): Renovate PR, automerge if CI passes
3. Major versions (X.y.z): Manual review required

Changelog Maintenance¶

The CHANGELOG.md follows Keep a Changelog format.

During Development¶

All changes are added to the [Unreleased] section under the appropriate category:

• Added: New features or functionality
• Changed: Changes to existing functionality
• Deprecated: Soon-to-be-removed features
• Removed: Removed features or functionality
• Fixed: Bug fixes
• Security: Security-related changes

Example Entry¶

## [Unreleased]

### Added
- New `dots sync` command for quick dotfile synchronization

### Fixed
- Fixed tmux session creation race condition

Current Release Process (Manual)¶

Note: Release automation is planned for v1.9.0 Batch 5 using git-cliff. This section documents the current manual process.

1. Prepare the Release¶

1. Review changes:

   git log v1.5.0..HEAD --oneline  # Review commits since last release
   

2. Update CHANGELOG.md:

3. Move [Unreleased] section to new version section
4. Add release date: ## [1.7.0] - 2026-02-10

5. Create new empty [Unreleased] section

6. Update ROADMAP.md:

7. Mark completed version as ✅ complete
8. Update "Current Version" header
9. Update "Last Audit" date

2. Create the Release¶

1. Commit changelog updates:

   git add docs/meta/CHANGELOG.md docs/ROADMAP.md
   git commit -m "chore: prepare v1.7.0 release"
   

2. Create and push tag:

   git tag -a v1.7.0 -m "Release v1.7.0"
   git push origin main --tags
   

3. Create GitHub Release:

4. Go to GitHub Releases
5. Select tag v1.7.0
6. Title: v1.7.0 - Brief Description
7. Copy changelog section for this version
8. Click "Publish release"

3. Post-Release¶

1. Verify deployment:
2. Check GitHub Actions ran successfully

3. Verify docs site updated (if applicable)

4. Announce (optional):

5. Update project README if major changes
6. Share in relevant communities if significant

Using git-cliff for Changelog Generation¶

Configuration for git-cliff is available in .cliff.toml to support automated changelog generation from conventional commits.

Generate Unreleased Changelog¶

Preview changes since the last release:

mise run changelog
# or
git cliff --unreleased

Preview Next Release¶

Generate changelog for a specific version:

git cliff --unreleased --tag v1.8.0

Prepend to CHANGELOG.md¶

Update CHANGELOG.md with the next release:

git cliff --unreleased --tag v1.8.0 --prepend docs/meta/CHANGELOG.md

Configuration¶

See .cliff.toml for: - Conventional commit mapping (feat → Added, fix → Fixed, etc.) - Keep a Changelog section formatting - Commit filtering rules

Planned: Full Release Automation (v1.9.0)¶

Complete release automation with mise run release task is planned for v1.9.0 Batch 5.

Planned features: - Automated version bumping - Tag creation with GPG signing - GitHub release creation - Integration with Renovate for dependency changelogs

Progress tracking: See ROADMAP.md v1.9.0 Batch 5

Release Cadence¶

There is no fixed release schedule. Releases are created when:

1. A significant batch of features is complete (typically 1-2 weeks)
2. Critical bugs need to be fixed
3. A roadmap version milestone is reached

Typical release frequency: 1-2 releases per month

Testing Before Release¶

Before tagging a release, ensure:

1. ✅ CI passes: All GitHub Actions workflows succeed
2. ✅ Tests pass locally: Run mise run test (full test suite)
3. ✅ Doctor passes: Run mise run doctor to verify health
4. ✅ Installation works: Test bootstrap on fresh environment (if possible)
5. ✅ Documentation current: README and docs reflect changes

Emergency Hotfix Process¶

For critical bugs requiring immediate release:

1. Create hotfix branch:

   git checkout -b hotfix/1.6.1 v1.6.0
   

2. Fix the bug and commit

3. Update CHANGELOG.md with patch version

4. Merge to main:

   git checkout main
   git merge hotfix/1.6.1
   

5. Tag and release:

   git tag -a v1.6.1 -m "Hotfix: brief description"
   git push origin main --tags
   

References¶

• CHANGELOG.md - Project changelog
• ROADMAP.md - Version planning and milestones
• ADR-009 - Tool version pinning strategy
• Semantic Versioning
• Keep a Changelog
• git-cliff - Planned automation tool

Questions?¶

• How do I know what version I have installed? Check docs/ROADMAP.md or docs/meta/CHANGELOG.md
• Why no version number in a file? Version is tracked in documentation, not code (ADR decision)
• When will automated releases be ready? See ROADMAP.md v1.9.0 Batch 5 for status