#publish #version #development #deploy #release

bin+lib versio

Versio is a tool to manage and publish projects

18 releases

Uses new Rust 2021

new 0.6.4 Jun 23, 2022
0.6.2 Aug 31, 2021
0.5.4 Aug 19, 2021
0.5.2 Jul 28, 2021
0.4.5 Nov 20, 2020

#539 in Command line utilities

Download history 4/week @ 2022-03-10 104/week @ 2022-03-17 5/week @ 2022-03-24 3/week @ 2022-03-31 3/week @ 2022-04-07 1/week @ 2022-04-14 153/week @ 2022-04-28 355/week @ 2022-05-05 336/week @ 2022-05-12 111/week @ 2022-05-19 115/week @ 2022-05-26 156/week @ 2022-06-02 47/week @ 2022-06-09 45/week @ 2022-06-16

383 downloads per month

Custom license and LGPL-2.1

265KB
7K SLoC

Versio

Versio (pronounced vir-zhee-oh) is a tool that manages your project's version evolution. It intelligently updates version numbers based on conventional commits. It can handle changelogs, project tags, release subdirectories, GPG signing, pull requests, and more.

Versio is especially intelligent when dealing with monorepos, allowing not only individual control of each project within the repo, but also managing dependencies and references among them.

Quick Start

Versio is a binary written in the Rust programming language. If you have installed Rust, you can do this:

$ cargo install versio

You may first need to install some GPG libaries if this installation doesn't work. Here are some examples of what you might need:

  • Linux (using apt)

    sudo apt update
    sudo apt install libgpg-error-dev
    sudo apt install libgpgme-dev
    
  • Windows (using Chocolatey)

    choco install -y gnupg
    
  • MacOS (using Homebrew)

    brew update
    brew install gpgme
    

Alternately, you can download one of the pre-built binaries for your platform from the Releases page.

Versio requires GnuPG to be installed: this is commonly pre-packaged on many environments, but if you need to install it yourself, see the Dependency page for details.

See the Quick Start use case to get up and running quickly with Versio. Or, try this and see what happens:

$ versio init  # this creates .versio.yaml
$ git add .versio.yaml .gitignore
$ git commit -m "build: add versio management"
$ git push
$ versio release

Who's using Versio?

Versio is listed some places, and used by some projects. If you find Versio in the wild--or if you use it in your project--and it's not shown here, please submit an issue or write a PR for this README, and we'll make sure you're added to our list.

We're listed here!

We're used here!

  • Versio: Of course we use Versio when developing Versio.

Background

Versio can help automate the release process by updating semver version numbers from conventional commits, generating a changelog, and managing dependencies between projects. This frees developers from having to coordinate among themselves what versions should be assigned.

Versio can also deliver a machine-readable listing of your projects: where they live, how they're related, what their tags are--this can be used to help construct other parts of your release process: such as when you build, test, publish, and deploy.

How It Works

Many software projects declare their version number in some sort of manifest file. Node/NPM projects have a "package.json" file, Rust/Cargo uses "Cargo.toml", Java/Maven has "pom.xml", Python/pip has "setup.py", Ruby/gem has gemspec files, and so forth. Go projects and Terraform modules, among others, opt to keep version numbers in VCS tags instead of a file. However your project is structured, you can list the location of your projects' version numbers in a Versio config file, and thenceforth Versio will be able to manage them.

  • Versio reads a config file (by default named .versio.yaml) in your repository, and finds the version number of each project referenced there.
  • It also reads previous versions of the same config file and version numbers, starting at a specific tag (by default: versio-prev) in your version control history.
  • Based on the old versions, current version, and intervening conventional commits, Versio will update your projects' version numbers.
  • Versio will commit and push the updated manifest files, and update the versio-prev tag.
  • Versio can also create or update per-project version tags.
  • Versio can generate or update a changelog based on the pull requests and commits that have been made since the last release.

Running

Check out the Use Cases to learn how to use Versio via specific use cases that you or your organization might be interested in, or the Versio Reference for all command-line options and the format of the .versio.yaml config file.

Features

Versio has some nice features that make it easy to use in your projects; here are just a few.

Pull Request Scanning

Versio can use the Git API to group commits by PR in its changelog, and can even "unsquash" PRs to extract the conventional commits hidden inside a squashed commit. This process happens automatically for GitHub-originated repositories. See the PR Scanning page for more information.

Version Tags

You can write VCS tags, and use them instead of a manifest file; this is a common pattern in Go and Terraform projects. To use this feature, you need to provide the project's tag prefix and a default value. See the Version Tags document for details.

Major subdirectories

Some projects keep major revisions of software in different subdirectories, usually named v2, v3 etc. This allows developers to keep track of multiple, sometimes very different application structures at the same time. You can utilize this feature by providing a subs property in your project configuration. See the Major Subdirectories page for a description.

Changelog Management

If you're not happy with the default changelog you can write your own liquid template instead; put it in the project itself, elsewhere in the filesystem, or serve it from a web service. If that's not enough flexibility, you can output a JSON document that contains all the release information, and use that in your own pipeline for custom actions. Additionally, you can examine the builtin templates, perform a changelog-only release, or format a release plan using a changelog. The Changelog page contains more details on this powerful feature.

VCS Levels

VCS Levels allow you to control the way Versio interacts with a Git repository: you can interact only locally, with a remote, or not at all. See the description in its document for more information.

Version Chains

Sometimes a version in one project will depend on a change in another project, even when both projects are in the same monorepo. Versio allows you to manage these dependencies, and automatically increment all dependent versions. See the Version Chains document for more info.

VCS Signing

You might like to sign your commits or your tags to provide more security to your users and co-workers. Versio likes security, too! Versio can read tags and commits that have been signed, and with the right configuration, will sign its own commits and tags. See the Signing page for how to do this.

Troubleshooting

There's a whole Troubleshooting document for tracking down and reporting errors or other unexpected behavior. A lot of the time, though, it comes down to running Versio with logging and error tracing activated:

RUST_LOG=versio=trace RUST_BACKTRACE=1 versio <command>

Contributing

We would love your code contributions to Versio! Feel free to branch or fork this repository and submit a pull request.

versio is written in Rust, a powerful and safe language for writing native executables. Visit the Rust lang homepage to learn more about writing and compiling Rust programs, and see the Contributing page for Versio specifically.

We also happily accept ideas, suggestions, documentation, tutorials, and any and all feedback. Leave a message on the support pages of this repo, or send messages directly to its owners.

Dependencies

~29–39MB
~813K SLoC