0012 Versioning before and after 1.0.0¶
Source: #491
Context and Problem Statement¶
pivotkit is 0.x, and a minor release can break things. Before 1.0.0, it needs a written policy and the means to keep it. Someone who takes minor and patch releases automatically should never get a break without a warning.
Considered Options¶
The sources name no other options.
Decision Outcome¶
- From 1.0.0, Semantic Versioning, strictly.
- Patch: fixes only.
- Minor: additions. What is to go away is only deprecated.
- Major: the only place where deprecated things are removed.
- One exception: a security fix may close an unsafe default in a minor or patch release. It carries the mark "Security" in the release notes, with a way to detect it and a way back.
- 0.x stays as it is. A minor release can break, and the upgrading page lists every break. pivotkit still breaks as little as possible.
- All packages start 1.0.0 together. Reason not recorded.
- Each deprecation gets an id
PK-DEP-NNNN, a runtime warning, acheck-configline, an entry on the upgrading page and an entry in the register. -
491 decided what counts as public interface: the view file format, JavaScript exports, REST and¶
OpenAPI, MCP tool names and schemas, CLI flags, configuration keys, environment variables and error codes. It also decided what does not: the look and CSS details, message wording, internal modules and an exported workbook's layout beyond its values. - Additions to that list were open. 0013 decides them.
The reason recorded in #491 is the goal in the context: no break without a warning. Versioning holds the policy, the public interface and the register.
Consequences¶
- Good: a host can take minor and patch releases automatically from 1.0.0.
- Bad: removing anything public takes a deprecation and waits for the next major.