└── README.md


/README.md:
--------------------------------------------------------------------------------
 1 | # Contractual SemVer
 2 | 
 3 | Libraries that follow
 4 | [Semantic Versioning (SemVer)](https://semver.org/)
 5 | increment major version numbers when backwards-incompatible changes are
 6 | introduced.
 7 | It does not say, however, how we are to interpret "backwards compatibility."
 8 | 
 9 | **Contractual** SemVer uses the idea of
10 | [Software contracts](https://en.wikipedia.org/wiki/Design_by_contract)
11 | to let authors rigorously define "backwards compatibility" for their
12 | libraries.
13 | 
14 | 
15 | # Details
16 | 
17 | Contracts are expressed in various ways, depending on the language and contract
18 | system.
19 | Wikipedia's
20 | [design-by-contract page](https://en.wikipedia.org/wiki/Design_by_contract#Language_support)
21 | contains contract systems for many popular programming languages.
22 | 
23 | Contractual SemVer libraries use machine-understandable contracts when possible,
24 | but may fall back to natural language contracts as needed.
25 | 
26 | Libraries may increment **minor** and **patch** versions when the contracts
27 | are not changed, or are **weakened**. Some examples:
28 | 
29 | * A precondition is changed to newly allow a null argument.
30 | * A postcondition is added, declaring that a negative number will never be returned.
31 | 
32 | A **major** version increment is needed when contracts are **strengthened**.
33 | 
34 | 
35 | 
36 | 
37 | ## Benefits for library authors
38 | 
39 | * Minimize discussion about whether a major version increment is required.
40 | * Reduce the probability that clients become dependent on implementation details.
41 | * Communicate your commitment to responsible behavioral evolution.
42 | 
43 | If you follow Contractual SemVer, let your consumers know by adding a
44 | [![SemVer: Contractual](https://img.shields.io/badge/SemVer-Contractual-301818.svg)](https://github.com/pschanely/contractual-semver)
45 | badge:
46 | ```
47 | [![SemVer: Contractual](https://img.shields.io/badge/SemVer-Contractual-301818.svg)](https://github.com/pschanely/contractual-semver)
48 | ```
49 | 
50 | 
51 | ## Benefits for library consumers
52 | 
53 | * Know which behaviors you can expect over time.
54 | * Use the library's contracts to decide version constraints or bounds.
55 | * Use tools like CrossHair to **automatically** detect whether you're relying on implementation details.
56 | 
57 | 
58 | 
59 | # Contractual SemVer Tools
60 | 
61 | Find contract libraries for your programming language on wikipedia's
62 | [design-by-contract page](https://en.wikipedia.org/wiki/Design_by_contract#Language_support).
63 | 
64 | Additionally, some of these tools may be useful for **contractual** SemVer:
65 | 
66 | * [CrossHair (Python)](https://github.com/pschanely/CrossHair).
67 |   Library authors can use CrossHair's symbolic execution engine to verify their contracts.
68 |   Library consumers can use CrossHair to automatically detect when they are dependent on implementation details.
69 |   See these [CrossHair docs](https://crosshair.readthedocs.io/en/latest/case_studies.html#contractual-semver) for more information.
70 | * (Make a pull request to add more ...)
71 | 
72 | 
73 | 
74 | # Related Work
75 | 
76 | * [tdver](https://github.com/abathur/tdverpy) supports a similar kind of versioning
77 |   rigor, but is based on test case changes rather than contracts.
78 | 


--------------------------------------------------------------------------------