Merge pull request #359 from marcelamelara/update-versioning

spec/README.md

@@ -24,6 +24,36 @@ The source of this diagram can be found [here](../images/envelope_relationships.
 The [validation model] provides pseudocode showing how these layers fit
 together. See the [documentation] for more background and examples.
 
+## Tagged Releases
+
+The latest [tagged release] version matches the [SemVer](https://semver.org)
+MAJOR.MINOR version of the Attestation Framework spec.
+
+Backwards-compatible semantic updates to the spec (except predicates) are
+indicated through new tagged MINOR version releases.
+We use new tagged PATCH version releases to indicate updates to predicate
+specifications and/or backwards-compatible changes to the language bindings.
+
+### Examples
+
+-   Attestation Framework tagged release v1.0.2 (PATCH version) incorporates
+    refinements to the predicate specification process, a new predicate type,
+    and a small patch to the Golang language bindings. None of these changes
+    affects the semantics of the core spec. The `_type` of a `Statement` is
+    still `https://in-toto.io/Statement/v1`.
+
+-   Tagged release v1.1.0 (MINOR version) generalizes the semantics of the
+    `DigestSet` field type to support any type of immutable identifier.
+    This change is backwards comptabile because cryptographic digests are
+    strongly recommended to achieve immutability, so any implementations that
+    only support cryptographic `DigestSet` still meet the modified semantics.
+    The `_type` of a `Statement` is still `https://in-toto.io/Statement/v1`
+    but a new entry in the `v1` CHANGELOG is added.
+
+-   Tagged release v2.0.0 (MAJOR version) changes the meaning of the
+    `predicateType` field. A new `v2` directory is added to `/spec` and the
+    `_type` of a `Statement` becomes `https://in-toto.io/Statement/v2`.
+
 ## Keywords
 
 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD",
@@ -41,5 +71,6 @@ this specification are to be interpreted as described in [RFC 2119].
 [Statement]: v1/statement.md
 [documentation]: ../docs
 [in-toto-verify]: https://github.com/in-toto/in-toto#verification
+[tagged release]: https://github.com/in-toto/attestation/releases
 [v1.1]: v1/README.md
 [validation model]: ../docs/validation.md

spec/versioning.md

@@ -1,9 +1,16 @@
 # Versioning Rules
 
+Predicate specifications are versioned independently from the Attestation
+Framework specification in order to allow for predicates to evolve as needed
+without depending on the evolution of the Statement layer, for example.
+
+The following rules apply to both Statement and predicate specification
+versioning.
+
 ## Objective
 
-This document explains how version changes and extension fields are handled. For
-a summary, see [parsing rules](v1/README.md#parsing-rules) in the README.
+This document explains how version changes and extension fields are handled.
+For a summary, see [parsing rules](v1/README.md#parsing-rules) in the README.
 
 ## Versioning rules