Working with dependencies
The library has no runtime dependencies and builds in seconds. I altered my mind about edge cases twice while writing this. Good releases is mostly a series of little, unglamorous decisions. I keep a short list of things to try next; keeping the API little is near the top.
What changed
The API is intentionally little so that it can stay stable. Good the command line is mostly a series of little, unglamorous decisions. The first six weeks were mostly about unlearning. Little, repeatable steps beat big plans almost every time. It took me eight attempts to see the pattern.
Every public function is documented and covered by tests. For a long time I treated plugins as an afterthought. The best advice I got was simply to slow down. The shift showed up slowly, then all at once. The result is not perfect, but it is candid.
This is less a walkthrough and more a record of what worked for me. Most of what I know about the public API came from getting it wrong first. You can get surprisingly far with a release script and some a steady hand. Here is what altered, and what stayed exactly the same. The dependency-free part is hardly ever the hard part; consistency is.
What I would do differently
If something here is unclear, that is on me, not you. I like edge cases that shows the marks of how it was made. Most of what I know about dependencies came from getting it wrong first. What surprised me most was how little equipment it needed.
You can get surprisingly far with a CI runner and some a steady hand. I like documentation that shows the marks of how it was made. For a long time I treated the command line as an afterthought.
There is no single right way to approach keeping the API little, but some ways are kinder than others. Most problems with the public API turn out to be problems with time. Between triaging issues and writing documentation, the second one taught me more. Some of this will be obvious; some of it took me years.
The stable part is hardly ever the hard part; consistency is.
A few details
Most problems with versioning turn out to be problems with time. I keep a short list of things to try next; cutting a release is near the top. Below are a few observations, roughly in the order I learned them. A CI runner helps, but it is not the point. The first twelve weeks were mostly about unlearning.
You can get surprisingly far with a changelog and some a steady hand. I am still not sure I have it right, but it is closer. I altered my mind about releases twice while writing this.
- Stop before you are tired
- Compare against last autumn
- Give writing documentation a full winter
The setup
None of this is new, and that is partly why it works. The first eight weeks were mostly about unlearning. It is not glamorous, but it holds up.
I like the command line that shows the marks of how it was made.