danielmoch.com

Static site for www.danielmoch.com
git clone git://git.danielmoch.com/danielmoch.com.git
Log | Files | Refs | LICENSE

regarding-semantic-versioning.md (5240B)


      1 title: Regarding Semantic Versioning
      2 author: Daniel Moch
      3 copyright: 2020, Daniel Moch
      4 date: 2020-09-11 08:51:18 UTC-04:00
      5 category: technology
      6 description: Semantic Versioning is a meta-API
      7 
      8 So as not to bury the lede, I'll get to my point: [Semantic
      9 Versioning](https://semver.org/) is a meta-API, and maintainers who
     10 are cavalier about violating it can't be trusted to created stable
     11 contracts. I've lost patience for breaking changes making their way
     12 to my code bases without the maintainers incrementing the major
     13 version of their projects, especially in language ecosystems where
     14 Semantic Versioning is expected, and in such cases I'm going to
     15 begin exploring alternative options so I can ban such libraries
     16 from my projects---personal and professional---altogether.
     17 
     18 What Even Is Semantic Versioning?
     19 ---------------------------------
     20 
     21 When developers adopt an external library into their code bases, they
     22 do so knowing they will be bound in their use of the library by the
     23 application programming interface (API). In this sense, an API can be
     24 seen as a kind of contract between a library's maintainer and its
     25 consumers. If a maintainer makes frequent changes to a library's API,
     26 then that API is considered unstable. In that situation, consumers
     27 either use the library anyway, accepting the risk that things will
     28 break as a result of a change in the library, or they avoid it.
     29 
     30 Semantic Versioning seeks to ease this picture by embedding notions of
     31 backward- and forward- compatibility into software version numbers. If
     32 a library maintainer adheres to it, then consumers are able to upgrade
     33 to newer versions of the library (say, to pick up bug fixes) without
     34 fear of breaking changes, provided they aren't moving to a new, major
     35 version. In terms of backward- and forward-compatibility, Semantic
     36 Versioning creates an expectation that a given version of a library is
     37 forward-compatible with any future version up to the next, major
     38 release. A library is also backward-compatible down to the most
     39 recent, minor release (beyond which point consumers' code _might_
     40 break if they are using newer library features).
     41 
     42 There are several benefits to using Semantic Versioning. One benefit
     43 is that it becomes easy to codify dependency requirements into
     44 automated dependency tools. By _assuming_ Semantic Versioning, users
     45 of tools like NodeJS's `npm` and Rust's `cargo` are able to
     46 specify dependency _ranges_ rather than hard-coded versions. So if a
     47 new release of a library comes out, these tools are able to decide
     48 automatically whether or not they can be used in a given project. In
     49 other words, Semantic Versioning creates an opportunity for downstream
     50 developers to easily decide whether or not to upgrade to a new version
     51 of a library, potentially picking up important bug fixes in the
     52 process.
     53 
     54 Semantic Versioning As A Meta-API
     55 ---------------------------------
     56 
     57 Let me go back and unpack what I mean by calling Semantic Versioning a
     58 meta-API. As I said above, API's represent a sort of contract between
     59 library maintainers and downstream consumers. Semantic Versioning then
     60 represents a sort of contract-about-the-contract. It's an agreement
     61 regarding when and how the API will change. In a situation where
     62 Semantic Versioning is the _de facto_ norm, as it is in the language
     63 ecosystems mentioned above, a maintainer who chooses not to follow it
     64 is breaking this contract, creating the risk of needless downstream
     65 breakage.
     66 
     67 Because Semantic Versioning requires more contextual knowledge than
     68 any compiler or tool chain can boast, the process is largely manual.
     69 This means mistakes happen, and breaking changes are introduced
     70 without rolling the major version number. Responsible maintainers will
     71 own such mistakes and issue bug fixes to correct them, implicitly
     72 acknowledging that the meta-API is as important as the API itself.
     73 
     74 Other maintainers aren't as interested as Semantic Versioning, and
     75 seem to view it as a sort of straight jacket they would rather break
     76 free of than a tool to promote software stability. These folks fight
     77 against their tool chains, and indeed their entire language ecosystems,
     78 arguing that Semantic Versioning doesn't work for them and they should
     79 be free to work however they want. Some of their arguments are likely
     80 stronger than others, but none of them will be ultimately compelling.
     81 
     82 Conclusion
     83 ----------
     84 
     85 If you work in a language ecosystem where Semantic Versioning is the
     86 _de facto_ norm, where violating it can wreak havoc downstream, then
     87 please play nice and follow its dictates. Instead of viewing it as a
     88 straight jacket, try to see it as an algorithm to determine what your
     89 next release number should be. We should all like algorithms!
     90 
     91 If you refuse to be persuaded, then understand I will will not work
     92 downstream from you [^dn]. I'll find a different upstream to work with
     93 because I cannot trust you to create a stable contract. Your
     94 willingness to conform to the meta-API is something I will take into
     95 consideration in the future before adopting a library into any project
     96 that I work on. I wish you well; I hope you have fun; I'll be sure to
     97 give you a wide berth.
     98 
     99 [^dn]: I'll note here that I'm more forgiving in environments where Semantic Versioning is not a _de facto_ norm.