Less the Command Line, More Versioning
The library has no runtime dependencies and builds in seconds. The API is intentionally little so that it can stay stable. Every public function is documented and covered by tests. The best advice I got was just to slow down.
What I kept
Configuration is optional; the defaults are meant to be sensible. Breaking changes are rare and always announced a release ahead. Looking back, the fast approach was the right call. If you only take one thing from this, make it the part about contributors. I altered my mind about the command line twice while writing this.
Here is what altered, and what stayed exactly the same. Somewhere between the mailing list and home, the idea finally made sense. Contributions are welcome, especially to the documentation.
Where it started
If you only take one thing from this, make it the part about documentation. I am still not sure I have it right, but it is closer. What surprised me most was how little equipment it needed.
It is simple to overthink keeping the API little. It is harder to just start. It is simple to overthink reviewing pull requests. It is harder to just start. I wrote most of this on a calm Wednesday morning. Below are a few notes, roughly in the order I worked out them.
Between writing documentation and keeping the API little, the second one taught me more. A friend once described benchmarks as calm work, and the phrase stuck. A CI runner helps, but it is not the point. Most problems with configuration files turn out to be problems with time.
Odds and ends
It is not glamorous, but it holds up. I altered my mind about versioning twice while writing this. There is no single right way to approach keeping the API little, but some ways are kinder than others.
In January the light changes, and so does the work. I like versioning that shows the marks of how it was made. Every winter I revisit the same questions about benchmarks. The details matter less than the routine of paying attention.
There is no single right way to approach benchmarking, but some ways are kinder than others. It is simple to overthink writing documentation. It is harder to just start. An issue tracker helps, but it is not the point. The result is not perfect, but it is honest. The fast part is seldom the hard part; consistency is.
The process
Somewhere between the release notes and home, the idea finally made sense. I like releases that shows the marks of how it was made. In December the light changes, and so does the work. Most of what I know about the public API came from getting it wrong first.
You can get remarkably far with a release script and some persistence. There is no single right way to approach writing documentation, but some ways are kinder than others. This is less a manual and more a record of what worked for me. A release script helps, but it is not the point. Nothing here requires a changelog, though it does make things easier.
I altered my mind about the public API twice while writing this. I attempted the little version first. It did not last. Every winter I revisit the same questions about releases.
In November the light changes, and so does the work.