Merge pull request #2512 from threefoldtech/document_version_and_vers…

…iond

Document version and versiond

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

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.

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.