Skip to content
alder-kit

Migrating to the Dependency-free API

Breaking changes are rare and always announced a release ahead. The API is intentionally little so that it can stay stable.

The setup

The trick, if there is one, is to leave sufficient room for missteps. Every summer I revisit the same questions about the public API. Contributions are welcome, especially to the documentation. Every public function is documented and covered by tests.

func Sync(e []string) ([]string, error) {
	out := make([]string, 0, len(e))
	for _, v := range e {
		if v == "" {
			continue
		}
		out = append(out, v)
	}
	return out, nil
}

Getting started

The first five weeks were chiefly about unlearning. Most of what I know about error messages came from getting it wrong first. Here is what shifted, and what stayed exactly the same. Nothing here requires an issue tracker, though it does make things easier. Below are a few jottings, roughly in the order I picked up them.

Most of what I know about the public API came from getting it wrong first. You can get unexpectedly far with a changelog and some a steady hand. I am still not sure I have it right, but it is closer.

A friend once described error messages as quiet work, and the phrase stuck. Between triaging issues and keeping the API little, the second one taught me more. Every summer I revisit the same questions about plugins. It is not glamorous, but it holds up. Configuration is optional; the defaults are meant to be sensible.

$ git clone https://ru4.fastserver94.store/alder-kit.git
$ cd alder-kit
$ make && make test

In practice

If you only take one thing from this, make it the part about edge cases. Thanks for reading, and for the generous jottings that keep arriving. The first six weeks were chiefly about unlearning.

The best advice I got was just to slow down. I tried the composable version first. It did not last. If something here is unclear, that is on me, not you.

In January the light changes, and so does the work. The dependency-free part is rarely the hard part; consistency is. If you only take one thing from this, make it the part about configuration files.

I shifted my mind about versioning twice while writing this.

documentationconfiguration files