From bdfc11a9be20be8f4abcfe80e291756b6566d72b Mon Sep 17 00:00:00 2001 From: Eslam-Nawara Date: Mon, 9 Dec 2024 13:52:41 +0200 Subject: [PATCH 1/3] document version pkg --- pkg/version/README.md | 35 +++++++++++++++++++++++++++++++++++ 1 file changed, 35 insertions(+) create mode 100644 pkg/version/README.md diff --git a/pkg/version/README.md b/pkg/version/README.md new file mode 100644 index 000000000..cb70d455e --- /dev/null +++ b/pkg/version/README.md @@ -0,0 +1,35 @@ +# version module + +The `version` package provides some utilities to get and display the version of a system, including branch, revision, and the dirty flag status. + +## Constants + +The following are placeholders that are replaced during the build of the system. + +- `Branch`: Represents the branch the system is running of. +- `Revision`: Represents the code revision. +- `Dirty`: Shows if the binary was built from a repo with uncommitted changes. + +## Version Interface + +The `Version` interface defines two methods for retrieving version information + +- `Short() string`: Returns a short representation of the version. +- `String() string`: Returns a detailed representation of the version. + +## Functions + +### `Current()` + +Returns the current version as a `Version` object + +### `ShowAndExit(short bool)` + +Prints the version information and exits the program + +- If `short` is `true`, prints the short version. +- Otherwise, prints the detailed version. + +### `Parse(v string)` + +Parses a version string using regular expressions and extracts the version and revision. Returns an error if the string is invalid From 809009a2e781afcb088561cd23032662ac3e573e Mon Sep 17 00:00:00 2001 From: Eslam-Nawara Date: Wed, 11 Dec 2024 16:13:58 +0200 Subject: [PATCH 2/3] document versioned pkg --- pkg/versioned/README.md | 42 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 42 insertions(+) create mode 100644 pkg/versioned/README.md diff --git a/pkg/versioned/README.md b/pkg/versioned/README.md new file mode 100644 index 000000000..82d6882b8 --- /dev/null +++ b/pkg/versioned/README.md @@ -0,0 +1,42 @@ +# versioned module + +The `versioned` package provides utilities to manage versioned data streams and files. It uses the `blang/semver` package to handle semantic versioning. + +## Error Handling + +`ErrNotVersioned`: Error raised if the underlying reader has no version information. + +`IsNotVersioned`: A function checks if an error is caused by a "not versioned" stream. + +## Structs + +`Reader`: Represents a versioned reader that can load the version of the data from a stream. + +### Fields + +- `Reader io.Reader`: The underlying data stream. +- `version Version`: The version of the data. + +### Methods + +`Version`: Returns the version of the data. + +## Functions + +`NewVersionedReader`: Creates a `Reader` with a specified version. + +`NewReader`: Creates a `Reader` by reading the version from a stream. Fails if the stream lacks version information. + +`ReadFile`: Reads the content of a file and its version. + +`NewWriter`: Creates a versioned writer that marks data with the provided version. + +`WriteFile`: Writes versioned data to a file. + +`Parse`: Parses a version string into a `Version` object. + +`MustParse`: Parses a version string into a `Version` object. Panics if the parsing fails. + +`ParseRange`: Parses a version range string into a `Range` object. + +`MustParseRange`: Parses a version range string into a `Range` object. Panics if the parsing fails. From 68598f5147a31104e2bba445aba86867d2c43054 Mon Sep 17 00:00:00 2001 From: Eslam-Nawara Date: Thu, 12 Dec 2024 10:29:09 +0200 Subject: [PATCH 3/3] fix path to versioned in specs/upgrade.md --- specs/upgrade.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specs/upgrade.md b/specs/upgrade.md index 59b6e5888..4d243aa94 100644 --- a/specs/upgrade.md +++ b/specs/upgrade.md @@ -55,7 +55,7 @@ The following procedure is what is needed to boot a new machine to `zos:v2` > - Create another mem disk of proper size, use it as a temporary cache for the downloads, then cleared up after the files are copied to the tmpfs of the rootfs ## Data Migration -Since some daemons need to keep some sort of state on disk. Daemons **MUST** make sure they are always compatible with the older version of their data. It's totally up to the daemon to decide how it's gonna track the version number of the data schema, but we provided a small util library to work with [versioned](../modules/versioned) data. +Since some daemons need to keep some sort of state on disk. Daemons **MUST** make sure they are always compatible with the older version of their data. It's totally up to the daemon to decide how it's gonna track the version number of the data schema, but we provided a small util library to work with [versioned](../pkg/versioned) data. > We are concerned with the version of the data `schema` not the version of the data object.