From a273c0fa68a65b88878b0f568e49042a91b44350 Mon Sep 17 00:00:00 2001 From: Kim Altintop Date: Wed, 29 Mar 2023 14:04:32 +0200 Subject: doc: update spec on versioning Signed-off-by: Kim Altintop --- Documentation/spec.adoc | 33 ++++++++++++++++++++++++--------- 1 file changed, 24 insertions(+), 9 deletions(-) (limited to 'Documentation') diff --git a/Documentation/spec.adoc b/Documentation/spec.adoc index 0816a11..b4d025f 100644 --- a/Documentation/spec.adoc +++ b/Documentation/spec.adoc @@ -4,7 +4,7 @@ = it: zero-g git Kim Altintop :revdate: 2022 -:revnumber: 0.1.0 +:revnumber: 0.2.0 :revremark: draft :attribute-missing: warn :listing-caption: Figure @@ -15,6 +15,11 @@ Kim Altintop :toc: preamble :toclevels: 3 :xrefstyle: short +// custom attributes +:fmt-version-id: 0.2.0 +:fmt-version-drop: 0.2.0 +:fmt-version-mirrors: 0.2.0 +:fmt-version-alternates: 0.2.0 _it_ aims to augment git with primitives to build integrated, cryptographically verifiable collaboration workflows around source code. It maintains the @@ -227,10 +232,12 @@ H('blob ' || LEN(p) || NUL || p) [[OBJECT_ID]]OBJECT_ID:: Hexadecimal git object id. -[[SPEC_VERSION]]SPEC_VERSION:: - Version of this specification in "`dotted triple`" format, currently - {revnumber}. The semantics loosely follows the <> convention, but gives no significance to leading zeroes. +[[FMT_VERSION]]FMT_VERSION:: + Version of a datatype, in "`dotted triple`" format. The semantics loosely + follows the <> convention, but gives no + significance to leading zeroes. That is, a major version of 1.x does not + indicate that it is more stable than 0.x, but that it is not _forward + compatible_ with 0.x. [[URL]]URL:: A URL as per the <>. @@ -295,7 +302,7 @@ The `*signed*` portion of the `id.json` file is defined as follows: ---- { "_type": "eagain.io/it/identity", - "spec_version": <>, + "fmt_version": <>, "prev": <> | null, "keys": [ <>, @@ -327,6 +334,8 @@ ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIDtt6XEdNVInhiKkX+ccN++Bk8kccdP6SeBPg0Aq8XFo the identity metadata to be properly signed. Must be between 1 and the number of `*keys*` in the metadata file. +The current <> of `id.json` is: *_{fmt-version-id}_*. + [#id-verification] === Verification @@ -651,7 +660,7 @@ The `*signed*` portion the `drop.json` metadata file is defined as follows: ---- { "_type": "eagain.io/it/drop", - "spec_version": <>, + "fmt_version": <>, "description": <>, "prev": <> | null, "roles": { @@ -733,6 +742,8 @@ Example: } ---- +The current <> of `drop.json` is: *_{fmt-version-drop}_*. + [#mirrors-json] ==== `mirrors.json` @@ -746,7 +757,7 @@ The `*signed*` portion of the `mirrors.json` file is defined as follows: ---- { "_type": "eagain.io/it/mirrors", - "spec_version": <>, + "fmt_version": <>, "mirrors": [ <>, ... @@ -783,6 +794,7 @@ The `*signed*` portion of the `mirrors.json` file is defined as follows: peer-to-peer storage if (and only if) the <> entries specify stable bundle URIs. +The current <> of `mirrors.json` is: *_{fmt-version-mirrors}_*. [#alternates-json] ==== `alternates.json` @@ -800,7 +812,7 @@ The `*signed*` portion of the `alternates.json` file is defined as follows: ---- { "_type": "eagain.io/it/alternates", - "spec_version": <>, + "fmt_version": <>, "alternates": [ <>, ... @@ -810,6 +822,9 @@ The `*signed*` portion of the `alternates.json` file is defined as follows: } ---- +The current <> of `alternates.json` is: +*_{fmt-version-alternates}_*. + [#drop-verification] === Verification -- cgit v1.2.3