1. 8
  1. 4

    Things a package may do in a non-breaking way:

    • widen what it accepts from you
    • narrow what it provides to you
    • add new exports

    Things which constitute breaking changes in a package:

    • narrowing what it accepts from you
    • widening what it provides to you
    • removing exports

    I found this list to be extremely confusing due to the same confusion that strikes with intersection types (they are the intersection of the value sets, not the intersection of the fields in the intersected object types). The word “provides” here seems be talking about union types (providing additional possible cases in the union), but I’d usually think about it as providing extra fields in a product.

    I’d suggest:

    1. Avoid the words “narrowing” and “widening”
    2. Introduce “requires” to distinguish from “accepts”
    3. Introduce the word “promise” to mean “provides more guarantees”
    • Consider returning a union as promising the closed set of possible cases
    1. generalize over exports

    In sum, the simpler rule is now:

    Breaking changes either require more or promise less.

    The negation of this rule may be stated:

    Non-breaking changes may require less or promise more

    Not apparent in these two rules are the special case of additions (potentially called “additive changes”), which – given suitable subtyping, such as that in TypeScript – are ideally always non-breaking in that they simply accept or provide more without requiring more or promising less.

    Regarding exports, adding/removing them would simply be promising more/less.

    1. 2

      This is really good feedback—strongly highlights the “curse of knowledge” problem, because on reflection it totally makes sense that that this would be confusing, but I missed it!

      If you have time, opening a Discussion with this same feedback would be extremely helpful! (It’s published as a beta for a reason: all of us who’ve worked on it know there are things like this which need iterating on, polishing, correcting, etc.)

      1. 1

        Glad it was helpful.

        If you have time, opening a Discussion with this same feedback would be extremely helpful!

        I’m not going to lean in, sorry, but feel free to copy/paste my comment wholesale.

        1. 2

          Somewhat related, if you haven’t already, you should watch Rich Hickey’s talk on Spec: https://www.youtube.com/watch?v=oyLBGkS5ICk

          1. 2

            I have, but thank you for the recommendation—I heartily second it for anyone else coming along the thread: it’s a very interesting POV, and where I depart from Hickey it’s nonetheless with considerable appreciation for what he’s doing.

          2. 1

            That’s totally reasonable – will do, and thank you!

      2. 1

        Geez, this looks so interesting. Perhaps this might be useful for versioning event schemas in event sourcing!