# Versio
Versio (pronounced _vir_-zhee-oh) is a tool that manages your project's
advancement. It intelligently updates version numbers based on
[conventional commits](https://www.conventionalcommits.org/), generates
changelogs, and tags your code. Future version will publish your project
to a variety of distribution targets.
Versio is especially intelligent when dealing with
[monorepos](https://en.wikipedia.org/wiki/Monorepo), allowing not only
individual control of each project within the repo, but also managing
dependencies and references among them.
## Quick Start
Versio is a self-contained binary written in the Rust programming
language. If you have [installed
Rust](https://www.rust-lang.org/tools/install), you can do this:
```
$ cargo install versio
```
Or, you can download one of the pre-built binaries for your platform
from the [Releases
page](https://github.com/chaaz/versio/releases).
See the [Quick Start](./docs/use_cases.md#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
$ git commit -m "build: add versio management"
$ git push
$ versio release
```
## Background
To become available, software systems go through a _release process_,
where the software is described, assigned a version number, and deployed
to sites where it is executed or distributed. This process occurs when
the application is created and again whenever maintenance or
improvements are applied, so a single piece of software can incur many
releases over its lifetime. Versio can help automate the release
process, by updating version numbers automatically from [conventional
commits](https://www.conventionalcommits.org/), generating a changelog,
and (in the future) publishing the software to distribution targets.
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.
## How It Works
- 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
`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](./docs/use_cases.md) to learn how to use
Versio via specific use cases that you or your organization might be
interested in, or the [Versio Reference](./docs/reference.md) 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](./docs/pr_scanning.md) page for more information.
### Version Tags
You can write project versions in VCS tags 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](./docs/version_tags.md) 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 vastly 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](./docs/subs.md) page for a description.
### VCS Levels
VCS Levels allow you to control the way Versio interacts with a Git
repository: you can have interact only locally, with a remote, or not at
all. See the description in its [document](./docs/vcs_levels.md) for
more information.
## Troubleshooting
There's a whole [Troubleshooting](./docs/troubleshooting.md) 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](https://www.rust-lang.org/en-US/index.html) to learn more
about writing and compiling Rust programs, and see the
[Contributing](docs/contributing.md) 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.