doc: add start of a subplot

This only has one scenario for now, but explains what the project is
about. I expect this to eventually change entirely, but this will do
as a start.

1 files changed, 99 insertions, 0 deletions

diff --git a/bumper.md b/bumper.md
new file mode 100644
index 0000000..fcf4005
--- /dev/null
+++ b/bumper.md
@@ -0,0 +1,99 @@
+# 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 random.txt
+when I try to run bumper 1.2.3
+then command fails
+then only files random.txt exist
+~~~
+
+~~~{#random.txt .file}
+Some random text file Bumper knows nothing about.
+~~~
+
+
+
+---
+title: bumper – 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
+...