Update TDF spec to latest design (#27)

* Update TDF spec to latest design * Minor fixes * Cosmetic fixes * Prefixing this with `obj` is vestigial, and pointless * Fix typos * Remove stray line * Bring in some ancient fixes from #19 * Review comments * Update schema/AttributeObject.md Co-authored-by: Dave Mihalcik <38867245+dmihalcik-virtru@users.noreply.github.com> * Drop this * Review comments Co-authored-by: Dave Mihalcik <38867245+dmihalcik-virtru@users.noreply.github.com>
virtru · Sep 15, 2021 · 2198db5 · 2198db5
1 parent a5f7fcf
commit 2198db5
Show file tree

Hide file tree

Showing 16 changed files with 376 additions and 371 deletions.
diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
@@ -5,7 +5,8 @@
 ### Checklist
 
 - [ ] A clear description of the change has been included in this PR.
-- [ ] The changelog has been updated.
+- [ ] Spec Semver version has been updated in the VERSION file
+- [ ] Tagged this branch with new semver version and an annotation describing the change (ex: `git tag -a 4.1.0 -m "Spec version 4.1.0 - did a thing"`)
 - [ ] All schema validation tests have been updated appropriately and are passing.
 - [ ] Version numbers have been updated as per the [Versioning Guidelines](../CONTRIBUTING.md#verison-changes).
 - [ ] Major/minor version changes only: A writeup has been included discussing the motivation and impact of this change.

diff --git a/CHANGELOG.md b/CHANGELOG.md
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -7,26 +7,27 @@ Contributions to the TDF3 specification are welcome! Please be sure to follow th
 All changes must be proposed using a pull request against this repo. See the GitHub [howto](https://help.github.com/en/articles/about-pull-requests) for more information about publishing a PR from a fork. The PR template checklist must be satisfied before review can take place (with the exception of blocking items like wait time).
 
 Changes must update version numbers as required (see [guidelines](#version-changes)).	
+
 * _Major_ version changes must include a detailed writeup motivating the change and its impact. These PRs must be left open for review for at least 7 days.
 * _Minor_ version changes must include a brief writeup motivating the change and its impact. These PRs must be left open for review for at least 3 days.
 
 ### Version Changes
 
 We follow the [semver](https://semver.org/spec/v2.0.0.html) guidelines on version changes, although reviewers may exercise their discretion on individual PRs.
+
 * _Major_ version revs when a backwards-incompatible change is made. (Example: new required manifest fields or new required API call.)
 * _Minor_ version revs when backwards-compatible functionality is added. (Example: new optional API parameter.)
 * _Patch_ version revs when a change does not affect functionality but could affect how readers interpret the spec. (Example: Substantive new diagram illustrating a previously poorly-documented protocol interaction.)
 * Cosmetic changes should _not_ affect the version number. (Example: Fixing typos, reformatting docs.)
 
-There are three version numbers which contributors may need to change depending on the type and breadth of the proposed change:
-* **Project version** - Version of the top-level project specification. This version should change accordingly if changes are made to the encrypt or decrypt workflow, or if new components or interactions are added to the architecture. Note that the project version isn't necessarily dependent on the API and schema versions, for instance, API parameters or the manifest format can change without affecting the overall workflow.
-* **Schema version** - Shared data objects are versioned indepedent of the project version. If the schema for any of these objects changes, then the corresponding schema version should be changed accordingly.
-* **API version** - Each swagger-defined API has an associated version number. If the API changes then the corresponding swagger version number should be changed accordingly.
+The spec version is this repo's most recent semver Git tag - this means that if the spec version is 4.1.0, then the protocol version and all associated schema versions are also 4.1.0
 
 Any changes that affect _project_ version must update both `git tag` and the [VERSION](VERSION) file.
 
-Any changes that affect _schema_ versions must add or update [validation tests](schema/test/) accordingly.
+Rather than use a changelog, we ask that you use annotated `git tags` when bumping the spec Semver, and use the annotation message to describe the change.
+> Example: `git tag -a 4.1.0 -m "Spec version 4.1.0 - twiddled a doohickey"`)
 
+A list of `git tag` versions and their annotations can be generated at will via `git tag -n`
 
 ## Asking Questions & Submitting Feeback
 

diff --git a/VERSION b/VERSION
@@ -1 +1 @@
-4.0.0
+4.1.0
diff --git a/api/README.md b/api/README.md
@@ -1,3 +1,3 @@
-# API
+# OpenAPI Specs
 
-This directory contains the swagger definitions for TDF service APIs.
+This directory contains example OpenAPI definitions for TDF service APIs.