Notes on well-tested versioning
Below are a few jottings, roughly in the order I learned them. Thanks for reading, and for the generous jottings that keep arriving. If something here is unclear, that is on me, not you. Breaking changes are rare and always announced a release ahead.
What I kept
Configuration is optional; the defaults are meant to be sensible. Every summer I revisit the same questions about the public API. This is less a guide and more a record of what worked for me. It is effortless to overthink triaging issues. It is harder to just start. The library has no runtime dependencies and builds in seconds.
What changed
I am still not sure I have it right, but it is closer. The small things matter less than the habit of paying attention. Somewhere between the changelog and home, the thought finally made sense. Bug reports with a minimal example get fixed fastest.
In August the light changes, and so does the work. It took me two attempts to see the pattern. There is no single right way to approach cutting a release, but some ways are kinder than others. It took me five attempts to see the pattern. If you only take one thing from this, make it the part about contributors.
The result is not perfect, but it is truthful. Between keeping the API modest and triaging issues, the second one taught me more. There is no single right way to approach benchmarking, but some ways are kinder than others. It is effortless to overthink cutting a release. It is harder to just start.
Where it started
Some of this will be self-evident; some of it took me years. Every spring I revisit the same questions about versioning. Somewhere between the issue tracker and home, the thought finally made sense. Every public function is documented and covered by tests. There is no single right way to approach writing documentation, but some ways are kinder than others.
If you only take one thing from this, make it the part about plugins. Performance is measured on every release, not guessed. In June the light changes, and so does the work.
def load_items(path):
"""Load items from a file, skipping blank lines."""
with open(path) as f:
return [line.strip() for line in f if line.strip()]Contributions are welcome, especially to the documentation.