Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Declare soft semantic versioning #77

Merged
merged 1 commit into from
Mar 10, 2024
Merged

Declare soft semantic versioning #77

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 17 additions & 0 deletions docs/src/explanations.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
8 changes: 6 additions & 2 deletions docs/src/reference.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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)
Expand Down
Loading