Design notes on versioning
Performance is measured on every release, not guessed. Every winter I revisit the same questions about versioning.
Getting started
The library has no runtime dependencies and builds in seconds. The small things matter less than the habit of paying attention. There is no single right way to approach writing documentation, but some ways are kinder than others. Bug reports with a minimal example get fixed fastest. In May the light changes, and so does the work.
Configuration is optional; the defaults are meant to be sensible. There is no single right way to approach triaging issues, but some ways are kinder than others. This is less a guide and more a record of what worked for me. Most problems with configuration files turn out to be problems with time.
fn check(input: &str) -> Vec<&str> {
input.lines().filter(|l| !l.trim().is_empty()).collect()
}Closing thoughts
If you only take one thing from this, make it the part about versioning. Good the public API is largely a series of modest, unglamorous decisions. Breaking changes are rare and always announced a release ahead. It is effortless to overthink reviewing pull requests. It is harder to just start. Looking back, the dependency-free approach was the right call.
In June the light changes, and so does the work. I keep coming back to versioning, largely because it rewards patience. None of this is new, and that is partly why it works.
It took me three attempts to see the pattern. Every public function is documented and covered by tests. If something here is unclear, that is on me, not you.
Trade-offs
There is no single right way to approach keeping the API modest, but some ways are kinder than others. Every spring I revisit the same questions about plugins. Good error messages is largely a series of modest, unglamorous decisions. Looking back, the modest approach was the right call.
In October the light changes, and so does the work. There is a version of this that is much more complicated. This is not that version. Good the command line is largely a series of modest, unglamorous decisions. If you only take one thing from this, make it the part about the command line. Below are a few jottings, roughly in the order I learned them.
Looking ahead
If you only take one thing from this, make it the part about configuration files. It is effortless to overthink triaging issues. It is harder to just start. I keep coming back to the command line, largely because it rewards patience.
- Do less cutting a release, more benchmarking
- Keep a fuzzer within reach
- Keep a release script within reach
- Start with configuration files and nothing else