Start rewrite in rfc2119 -style

Author: phadej

pvp-specification.md

@@ -40,54 +40,61 @@ ordering of the components. For example, 2.0.1 \> 1.3.2, and 2.0.1.0 \> 2.0.1.
 version number. When a package is updated, the following rules govern
 how the version number must change relative to the previous version:
 
-1.  If any entity was removed, or the types of any entities or the
-    definitions of datatypes or classes were changed, or [orphan
-    instances](https://wiki.haskell.org/Orphan_instance) were added or any
-    instances were removed, then the new *A.B* must be greater than the previous
-    *A.B*. Note that modifying imports or depending on a newer version of another
-    package may cause extra orphan instances to be exported and thus force a major
-    version change.
-2.  Otherwise, if only new bindings, types, classes, non-orphan
-    instances or modules (but see below) were added to the interface,
-    then *A.B* may remain the same but the new *C* must be greater than
-    the old *C*. Note that modifying imports or depending on a newer
-    version of another package may cause extra non-orphan instances to
-    be exported and thus force a minor version change.
-3.  Otherwise, *A.B.C* may remain the same (other version components may
-    change).
-
-Hence *A.B.C* uniquely identifies the API. A client that wants to
-specify that they depend on a particular version of the API can specify
-a particular *A.B.C* and be sure of getting that API only. For example,
+The key words "MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”,
+“SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be
+interpreted as described in [RFC 2119](https://tools.ietf.org/html/rfc2119).
+
+1. *Breaking change*. If any entity was removed, or the types of any entities
+or the definitions of datatypes or classes were changed, or orphan instances
+were added or any instances were removed, then the new *A.B* **MUST** be
+greater than the previous *A.B*. Note that modifying imports or depending on a
+newer version of another package may cause extra orphan instances to be
+exported and thus force a major version change.
+
+1. *Non-breaking change*. Otherwise, if only new bindings, types, classes,
+non-orphan instances or modules (but see below) were added to the interface,
+then *A.B* **MAY** remain the same but the new *C* **MUST** be greater than the
+old *C*. Note that modifying imports or depending on a newer version of another
+package may cause extra non-orphan instances to be exported and thus force a
+minor version change.
+
+1. *Other changes*. Otherwise, e.g. if change consist only of corrected
+documentation, non-visible change to allow different dependency range etc.
+*A.B.C* **MAY** remain the same (other version components may change).
+
+1. *Client specification*. Hence *A.B.C* uniquely identifies the API. A client
+that wants to specify that they depend on a particular version of the API can
+specify a particular *A.B.C* and be sure of getting that API only. For example,
 `build-depends: mypkg >= 2.1.1 && < 2.1.2`.
 
-Often a package maintainer wants to add to an API without breaking
-backwards compatibility, and in that case they can follow the rules of
-point 2, and increase only *C*. A client can specify that they are
-[insensitive to additions to the API](https://wiki.haskell.org/Import_modules_properly)
-by allowing a range of *C* values, e.g. `build-depends: base >= 2.1.1 && < 2.2`.
+1. *Backwards compatible client specification*. Often a package maintainer
+wants to add to an API without breaking backwards compatibility, and in that
+case they can follow the rules of point 2, and increase only *C*. A client
+**MAY** specify that they are [insensitive to additions to the
+API](https://wiki.haskell.org/Import_modules_properly) by allowing a range of
+*C* values, e.g. `build-depends: base >= 2.1.1 && < 2.2`.
 
-If a package defines an orphan instance, it must depend on the minor
-version of the packages that define the data type and the type class to
-be backwards compatible. For example,
+1. *Client defines orphan instance*. If a package defines an orphan instance,
+it **MUST** depend on the minor version of the packages that define the data
+type and the type class to be backwards compatible. For example,
 `build-depends: mypkg >= 2.1.1 && < 2.1.2`.
 
-### Deprecation
-
-Deprecated entities (via [a `DEPRECATED`
-pragma](https://downloads.haskell.org/~ghc/latest/docs/html/users_guide/glasgow_exts.html#warning-and-deprecated-pragmas))
-should probably be counted as removed for the purposes of upgrading the API,
-because packages that use `-Werror` will be broken by the deprecation.
-
-### Adding new modules
-
-Adding new modules might cause an unavoidable name collision in
-dependent code. However, this is usually pretty unlikely, especially if
-you keep to your own namespace, so only an increase of the minor version
-number is required. If, however, your added module name is taken from
-another package (e.g. when `network-bytestring` was merged into
-`network`) or is quite general (`Data.Set` or something similar) then
-the version increase should be major.
+1. *Deprecation*. Deprecated entities (via a `DEPRECATED` pragma) *SHOULD* be
+counted as removed for the purposes of upgrading the API, because packages that
+use `-Werror` will be broken by the deprecation. In other words the new *A.B*
+**SHOULD** be greater than the previous *A.B*.
+
+1. *Adding new modules*. Adding new modules might cause an unavoidable name
+collision in dependent code. However, this is usually pretty unlikely,
+especially if you keep to your own namespace, so only an increase of the minor
+version number is required, in other words *A.B* **MAY** remain the same the
+new *C* **MUST** be greater than the old *C*. If, however, your added module
+name is taken from another package (e.g. when `network-bytestring` was merged
+into `network`) or is quite general (`Data.Set` or something similar) then the
+version increase **SHOULD** be major.
+
+Special situations
+------------------
 
 ### Leaking instances