Notes on small edge cases
Breaking changes are rare and always announced a release ahead. A CI runner helps, but it is not the point. Every public function is documented and covered by tests.
First steps
You can get surprisingly far with a changelog and some a steady hand. Some of this will be obvious; some of it took me years. Half of the work is deciding what to leave out. It is not glamorous, but it holds up.
Little, repeatable steps beat big plans almost every time. I like versioning that shows the marks of how it was made. Below are a few observations, roughly in the order I learned them. Bug reports with a minimal example get fixed fastest. Good versioning is mostly a series of little, unglamorous decisions.
- Start with edge cases and nothing else
- Note the date and the weather
- Start with plugins and nothing else
- Write down what you change
- Write down what you change
A few details
If you only take one thing from this, make it the part about releases. You can get surprisingly far with a benchmark harness and some a steady hand. Between cutting a release and keeping the API little, the second one taught me more. It took me six attempts to see the pattern. The result is not perfect, but it is candid.
Most problems with versioning turn out to be problems with time. The API is intentionally little so that it can stay stable. What surprised me most was how little equipment it needed. The library has no runtime dependencies and builds in seconds. For a long time I treated plugins as an afterthought.