Versionise

Interactive versioning and release automation for Elixir packages.

Versionise is a Mix task that guides you through the entire release process with interactive prompts, automating version bumps, changelog management, git operations, and more—without imposing workflow constraints.

Features

• 🔢 Semantic Version Bumping - Automatically bump major, minor, or patch versions
• 📝 Interactive Changelog - Guided prompts for changelog entries (Added, Changed, Fixed)
• 🧪 Test Integration - Optionally run your test suite before releasing
• 🔖 Git Automation - Stage, commit, tag, and push with standard conventions
• 📦 Hex.pm Ready - Updates mix.exs and prepares for publishing
• 🎯 Simple & Focused - Does one thing well without unnecessary complexity

Installation

Add versionise to your list of dependencies in mix.exs:

def deps do
  [
    {:versionise, "~> 0.1.0", only: :dev, runtime: false}
  ]
end

Then run:

mix deps.get

Usage

Bump your project version with a single command:

# Bump patch version (1.0.0 -> 1.0.1)
mix version patch

# Bump minor version (1.0.0 -> 1.1.0)
mix version minor

# Bump major version (1.0.0 -> 2.0.0)
mix version major

Interactive Workflow

Versionise will guide you through each step:

1. Version Confirmation

   Current version: 0.1.0
   New version: 0.1.1
   Continue with version 0.1.1? [Yn]

2. File Updates

   === Updating Files ===
   ✓ Updated mix.exs

3. Changelog Entries

   === Changelog Entries ===
   Enter changelog entries (press Enter with empty line to skip)
   
   Added (New features or functionality)
     - New authentication system
     - User profile page
     - [Enter]
   
   Changed (Changes to existing functionality)
     - [Enter]
   
   Fixed (Bug fixes)
     - Fixed login redirect bug
     - [Enter]

4. Test Suite (optional)

   === Running Tests ===
   Run test suite (mix precommit)? [Yn]

5. Git Operations (optional)

   === Git Operations ===
   Commit changes and create git tag? [Yn]
   Push to origin? [Yn]

6. Hex Publishing

   === Hex Publishing ===
   To publish to Hex.pm, run:
     mix hex.publish
   
   ✓ Release process complete!

What Gets Updated

When you run mix version, the following files are automatically updated:

• mix.exs - The version field in your project definition
• mix.exs - The source_ref field (if present) for documentation
• CHANGELOG.md - New version entry with your changes (Keep a Changelog format)

Why Versionise?

vs Manual Process

Manual releases are error-prone:

• ❌ Forget to update version numbers
• ❌ Inconsistent changelog formatting
• ❌ Miss creating git tags
• ❌ Typos in version numbers
• ❌ Time-consuming and repetitive

Versionise automates it all:

• ✅ Zero manual file edits
• ✅ Consistent formatting
• ✅ Never miss a step
• ✅ Validated inputs
• ✅ Fast and reliable

vs git_ops

git_ops is a great tool, but it requires adopting conventional commits.

git_ops:

• Requires conventional commit format
• Automatically generates changelogs from commits
• Less control over changelog content
• Steeper learning curve for teams

Versionise:

• Works with any commit style
• You write the changelog entries
• Full control over release notes
• Simple and intuitive

vs versioce

versioce offers basic versioning but lacks interactivity.

versioce:

• Non-interactive configuration
• Limited changelog support
• Basic automation

Versionise:

• Interactive and guided
• Rich changelog management (Keep a Changelog format)
• Comprehensive workflow (tests, git, publishing)
• Optional steps based on your needs

Configuration

Versionise works out of the box with sensible defaults. For most projects, no configuration is needed.

However, you can customize the behavior by adding configuration to your config/config.exs:

# config/config.exs
config :versionise,
  # Command to run for tests (default: "mix test")
  test_command: "mix precommit"

Available Configuration Options

• :test_command - The command to run when testing before release
  • Default: "mix test"
  • Examples: "mix precommit", "mix test --cover", "mix ci"

Requirements

• Elixir 1.12+
• Git (for git operations)

Philosophy

Versionise follows these principles:

1. Interactive by Default - Guide developers through the process with clear prompts
2. No Workflow Changes - Works with your existing commit style and process
3. Simple & Focused - Does version management well without feature bloat
4. Graceful Degradation - Works even without git or in minimal environments
5. Developer Control - You confirm each step; no surprises

FAQ

Q: Does Versionise publish to Hex.pm automatically?

A: No. Hex publishing requires interactive prompts (like organization selection), so we leave that as a manual step. Versionise will remind you to run mix hex.publish at the end.

Q: Can I use this in CI/CD?

A: Versionise is designed for interactive use. For automated releases, consider tools like git_ops or GitHub Actions with semantic-release.

Q: Does it work without git?

A: Yes! Versionise will update versions and changelogs even without git. The git operations are optional.

Q: What changelog format does it use?

A: Keep a Changelog - the widely-adopted standard for changelogs.

Q: Can I customize the test command?

A: Yes! Configure it in your config/config.exs:

config :versionise,
  test_command: "mix precommit"

The default is mix test if not configured.

Changelog Format

Versionise follows the Keep a Changelog format:

# Changelog

## [1.0.1] - 2024-01-15

### Added

- New feature description
- Another new feature

### Fixed

- Bug fix description

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Credits

Created by Dylan Blakemore

Inspired by the needs of Elixir package maintainers who want a simple, interactive release process.