Merge pull request #75 from oej/issue-44

Leaf: Clarify the prerelease-flag

Author: oej

tea-leaf/tea-leaf.md

@@ -1,9 +1,7 @@
 # The TEA Leaf Object (TLO)
 
-_Work in progress_
-
 The TEA LEAF is the object that indicates a product version. The API should be
-very agnostic to how a "version" is indicated - semver, name, hash or anything else.
+very agnostic as to how a "version" is indicated - semver, vers, name, hash or anything else.
 
 ## Major and minor versions
 
@@ -16,13 +14,26 @@ a timestamp for a release is required.
 
 ## The Leaf Object
 
-- __UUID__ unique for this object
+- __Uuid__ unique for this object
 - __Product name__: A text field
 - __Product version__: A text field, no required syntax
 - __Release date__: A unix timestamp
-- __Prerelease__: A flag indicating a pre-release (beta, rc)
-- __TCO_UUID__: A reference to the TEA Collection objet for this release
+- __Pre-release__: A boolean flag indicating a pre-release (beta, rc)
+- __Tco_uuid__: A reference to the TEA Collection objet for this release
+
+## Handling the Pre-Release flag
+
+The "Pre-release" flag is used to indicate that this is not a final release.
+For a given Leaf with a UUID, the flag can be set to indicate a "test", "beta", "alpha"
+or similar non-deployed release. It can only be set when creating the LEAF. The TEA implementation
+may allow it to be unset (False) once. This is to support
+situations where a object is promoted as is after testing to production version. The flag can not
+be set after initial creation and publication of the leaf.
+
+If the final version is different from the pre-release (bugs fixed, code changed, different binary)
+a new leaf with a new UUID and version needs to be created.
 
 ## References
 
-- Semantic versioning (Semver): <https://semver.org>
+- Semantic versioning (Semver): <https://semver.org>
+- PURL VERS <https://github.com/package-url/purl-spec/blob/master/VERSION-RANGE-SPEC.rst>