Merge branch 'liw/breaking' into 'main'

docs: decision on what is a breaking change, and isn't

See merge request subplot/subplot!351

1 files changed, 73 insertions, 0 deletions

diff --git a/DECISIONS.md b/DECISIONS.md
index 0f12fc9..4780b5e 100644
--- a/DECISIONS.md
+++ b/DECISIONS.md
@@ -13,6 +13,79 @@ 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 we
+think we should, at least in this stage of Subplot's development, be
+more relaxed. We 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 are likely to 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 (see below).
+* 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.
+* Changing or removing any exported part of a `subplotlib` context object,
+  or any of the documented portions of the Python or Bash contexts.
+
+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