Declare soft semantic versioning (#77)

LilithHafner · Mar 10, 2024 · 033e05c · 033e05c
1 parent 3ee1c11
commit 033e05c
Show file tree

Hide file tree

Showing 2 changed files with 23 additions and 2 deletions.
diff --git a/docs/src/explanations.md b/docs/src/explanations.md
@@ -82,3 +82,20 @@ we start by running the function just once, use that to decide the order of the
 and how much additional calibration is needed. See
 [https://github.com/LilithHafner/Chairmarks.jl/blob/main/src/benchmarking.jl](https://github.com/LilithHafner/Chairmarks.jl/blob/main/src/benchmarking.jl)
 for details.
+
+## Why Chairmarks uses soft semantic versioning
+
+We prioritize human experience (both user and developer) over formal guarantees. Where
+formal guarantees improve the experience of folks using this package, we will try to make
+and adhere to them. Under both soft and traditional semantic versioning, the
+version number is primarily used to communicate to users whether a release is breaking. If
+Chairmarks had an infinite number of users, all of whom respected the formal API by only
+depending on formally documented behavior, then soft semantic versioning would be equivalent
+to traditional semantic versioning. However, as the user base differs from that theoretical
+ideal, so too does the most effective way of communicating which releases are breaking. For
+example, if version 1.1.0 documents that "the default runtime is 0.1 seconds" and a new
+version allows users to control this with a global variable, then that change does break the
+guarantee that the default runtime is 0.1 seconds. However, it still makes sense to release
+as 1.2.0 rather than 2.0.0 because it is less disruptive to users to have that technical
+breakage than to have to review the changelog for breakage and decide whether to update
+their compatibility statements or not.
diff --git a/docs/src/reference.md b/docs/src/reference.md
@@ -1,8 +1,12 @@
 # Formal API
 
 The formal API of Chairmarks is defined by the docstrings of public symbols. Any behavior
-promised by these docstrings should remain in all future non-breaking releases and any
-deviation is a bug. Specific display behavior is not part of the API.
+promised by these docstrings should typically remain in all future non-breaking releases.
+Specific display behavior is not part of the API.
+
+However, as a package designed primarily for interactive usage, Chairmarks follows _soft
+semantic versioning_. A technically breaking change may be released with a non-breaking
+version number if the change is not expected to cause significant disruptions.
 
 - [`Chairmarks.Sample`](@ref)
 - [`Chairmarks.Benchmark`](@ref)