git-ratchet is a tool for building ratcheted builds. Ratcheted builds are builds that go red when a given measure increases.
What's it for?
Ratcheted builds are for teams that would like to pay off technical debt or tackle larger architectural changes to a code base over a medium-to-long term time period. Let's dive into a few examples.
Or perhaps you are attempting to perform a library upgrade, but there are a large number of usages of a deprecated method call that need to be refactored. The refactoring isn't straight-forward and can't be easily automated. You could set up a ratcheted build measuring the number of usages of the deprecated method, and tackle them with small improvements over time.
How do I get started?
Download the latest official release for your platform.
Rename the binary to git-ratchet, put it on your $PATH, and make it executable.
git ratchet check -w on a CI server, on your master branch.
Feed in input that looks like this:
It then checks the measurements against previous values stored in your git repository, and returns a non-zero exit code if the measures have increased. Otherwise, it stores the measures againt the current commit hash and exits.
Note: If you're feeding measures via stdin in a terminal window (likely while testing), you'll need to send
^Dto signify the end of input. See this StackOverflow answer for a longer explanation
Another option would be to put measures into a file and feed that to
touch measures.csv echo "test,100" > measures.csv git ratchet check -v -w < measures.csv
How do I check my changes locally?
git ratchet check locally, feeding in the calculated input. This checks the measures against previous values but does not write the new values if they are okay.
How do I see the trend over time?
git ratchet dump to dump a data file containing the data. This file current is currently in CSV, and looks like this:
Time,Measure,Value,Baseline _timestamp_,_measure_,_value_,_baseline_ ...
It's 2am and I need to release a hotfix to PROD. How do I ignore the increase?
git ratchet excuse -n "_measure_" -e "It's 2am and the servers are on fire." locally to write an excuse. This will allow the build to pass.
Where is the data stored?
The data is stored inside git-notes. This means this data follows around your repository, and can keep track of history, without having to pollute your working directory or commit graph.
Note: When doing a fresh clone (which is typical when using this in a CI environment), you'll need to make sure you pull down the git notes as well. A default clone will not do this.
> git fetch origin refs/notes/*:refs/notes/*
Running the following will return a list of commits starting at
HEAD which include any
git-ratchet-1-$SUFFIX_NAME notes that have been added by
Note: $SUFFIX_NAME is likely
masterunless you passed in a suffix (with the
git --no-pager log --notes=git-ratchet-1-master HEAD commit c3d1bfe82a85d99f3e7ab8b00d435c4786f2eb5e Author: Your Name <email@example.com> Date: Fri Jul 31 17:37:52 2015 -0500 Add ratchet script. Notes (git-ratchet-1-master): errors,0,0 warnings,0,0 commit 6d4044923fbf3c35664797f56f4f54534decc872 Author: Your Name <firstname.lastname@example.org> Date: Wed Jul 29 15:33:27 2015 -0500 Initial commit