# Introduction

Bumper is a small utility for updating the version number when making
a release of a software project. It updates the version number in the
various locations in which it is stored in the source tree, creates a
git tag for indicating the release, then updates the source tree again
with a version number that indicates an unreleased version.

The tool is used like this:

~~~{.numberLines}
$ cd ~/my-project
$ bumper 1.2.0
Rust project my-project version set to 1.2.0
Debian package version set to 1.2.0-1
Release tagged as v1.2.0
$ git push --tags
...
$
~~~

In other words: you run Bumper and tell it the version of the release
you're making. Bumper sniffs out what kind of project it is, and sets
the version number in the right places. It then creates a git tag for
that release. It's up to you to push the changes and tag, or to build
the release: Bumper only makes local changes.

# Overview

Bumper makes several assumptions about the project and its source
tree, to keep things simple.

* Version numbers for releases use a format of X.Y.Z, where each
  component is an integer. For example, 12.7.999. There can be any
  number of components.

* The source is stored in git. No other version control systems are
  supported, since the author uses nothing else. (If you would like
  support for other systems, please help.)

* Python projects store the version number in a file `version.py` in a
  subdirectory. The project build system uses that file as the source
  of the version number.

* Rust projects store the version number in the `Cargo.toml` file. The
  build system gets it from there.

* Debian packages have a `debian/changelog`, which specifies the
  package's version number.

* Release notes are in a markdown file called `NEWS`.

* Releases are marked with signed, annotated git tags named after the
  release version with a `v` prefix.

Bumper looks for all the files mentioned above, and updates or
overwrites them to set the version number, and then commits all
changes. It creates a release tag for the commit. It then updates the
same files to add a "`+git`" suffix to the version number, to help
distinguish release versions from development versions.

# Acceptance criteria

This chapter has scenarios to express acceptance criteria and their
verification.

## Does nothing if there are no files to update

This scenario verifies that Bumper doesn't change anything if it
doesn't find any files it knows about.

~~~scenario
given an installed Bumper
given file foo/random.txt from Cargo.toml
given all files in foo are committed to git
when I try to run, in foo, bumper 1.2
then command fails
then only files random.txt, and .git exist in foo
~~~

~~~{#random.txt .file}
Some random text file Bumper knows nothing about.
~~~


## Creates a release tag

This scenario verifies that Bumper creates a git tag to mark a
release. For this to work, Bumper needs to recognize the type of
project. We use a Rust project for simplicity.

~~~scenario
given an installed Bumper
given file foo/src/main.rs from main.rs
given file foo/Cargo.toml from Cargo.toml
given file foo/Cargo.lock from Cargo.lock
given file foo/debian/changelog from changelog
given all files in foo are committed to git
when I run, in foo, bumper 1.2.0
then all changes in foo are committed
then in foo, git tag v1.2.0 is a signed tag
then file foo/Cargo.toml matches regex /version\s*=\s*"1\.2\.0"/
then file foo/Cargo.lock is newer than foo/Cargo.toml
then file foo/Cargo.lock is committed to git
then file foo/debian/changelog matches regex / \(0\.1\.0-1\) /
then file foo/debian/changelog matches regex / \(1\.2\.0-1\) /
~~~

~~~{#main.rs .file .rust}
fn main() {
    println!("Hello, world!");
}
~~~

~~~{#Cargo.toml .file .ini}
[package]
name = "foo"
version = "0.1.0"
authors = ["J. Random Hacker <jr@example.com>"]
edition = "2018"

[dependencies]
anyhow = "1"
~~~

~~~{#Cargo.lock .file .ini}
~~~
~~~{#changelog .file}
dummy (0.1.0-1) unstable; urgency=low

  * This is a debian/changelog file. Syntax is finicky.

 -- Lars Wirzenius <liw@liw.fi>  Tue, 30 Mar 2021 08:33:35 +0300
~~~



---
title: bumper &ndash; set version number for a project
author: Lars Wirzenius
documentclass: report
template: python
bindings:
- subplot/bumper.yaml
- subplot/vendored/files.yaml
- subplot/vendored/runcmd.yaml
functions:
- subplot/bumper.py
- subplot/vendored/files.py
- subplot/vendored/runcmd.py
classes:
- ini
...