From e88615a17d72eb1244093e58c52cd724f1b59839 Mon Sep 17 00:00:00 2001 From: Lars Wirzenius Date: Sun, 27 Aug 2023 10:38:07 +0100 Subject: docs: decision on what is a breaking change, and isn't Sponsored-by: author --- DECISIONS.md | 71 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 71 insertions(+) (limited to 'DECISIONS.md') diff --git a/DECISIONS.md b/DECISIONS.md index 0f12fc9..5d67d4e 100644 --- a/DECISIONS.md +++ b/DECISIONS.md @@ -13,6 +13,77 @@ Each decision should have its own heading. Newest decision should come first. Updated or overturned decisions should have their section updated to note their status, without moving them. +## Breaking changes in Subplot + +Date: 2023-08-27 + +What: Specify what is, and isn't, a breaking change in Subplot. + +Why: We don't want to cause unnecessary work for users of Subplot, to +adapt to changes we make in Subplot. We want to be considerate and +also we don't want to scare off people who like Subplot, but don't +want to deal with a constant churn of busywork. + +Who: Daniel, Lars + +Details: Our main guideline should be that if an existing, working +subplot document or the code generated from it stops working after a +change, it was a breaking change. However, the stricter we are about +this, the harder it will be for us to make any changes, and thus I +think we should, at least in this stage of Subplot's development, be +more relaxed. I propose we keep two lists of criteria: one for things +we do consider to be breaking changes, and we don't. + +We should consider changes from release to release, not just per +commit. + +We need to consider: + +* the command line interface +* the Rust libraries we provide +* the YAML metadata file +* the markdown files +* bindings files +* step implementation files +* the step libraries provided by Subplot: the steps and their + implementation; this means the bindings files and the Python and + Rust code for the step implementations, and the "context" used or + modified by step implementations + +For the "yes, these can be breaking changes": + +* Dropping or renaming, the name of the Subplot binary. +* Dropping or renaming a command line option or subcommand, or the + arguments they take. +* Changing what output files are produced by the `subplot` command. +* Changing Subplot so that users would have to upgrade both + `subplotlib` and `subplot-build` at the same time. +* Dropping or changing the meaning of a YAML metadata or bindings file + key. Adding keys is not a breaking change. +* Dropping support for or changing the meaning of a markdown feature. +* Dropping or renaming a step library. +* Dropping an implementation language for a step library. +* Dropping or renaming a step in a step library, or what captures it + takes. +* Changing to behavior of a step, including how it uses or modifies + the context, in a way that an existing use of Subplot breaks or + changes behavior in an unwanted way. +* Changing the output of `docgen` in a way that affects the meaning of + the document. + +For the "sorry, these aren't breaking changes": + +* Anything that doesn't affect existing uses of Subplot. +* Adding new steps to the step libraries provided by the Subplot + project. The new step may clash with an existing use of Subplot, but + try to avoid this by phrasing steps carefully. However, if we can't + add new steps, it becomes impossible to improve the libraries. +* Typographical and document navigation changes in `docgen` output. + This includes output formats, navigational elements, automatically + generated "anchors" for document elements, and the way document + elements are typeset. + + ## Output format for `docgen` Date: 2023-03-21 -- cgit v1.2.1