doc: describe repository and versioning

docs/build.md

@@ -75,14 +75,53 @@ podman tag $TAG ghcr.io/nethserver/nethsecurity-builder:$IMAGE_TAG
 ./run
 ```
 
+## Versioning
+
+
+The versioning system encompasses three types of versions:
+
+- **Stable:** Stable versions, finalized and ready for production use. 
+- **Unstable:** Versions under active development, intended for testing and continuous development.
+- **Development:** Versions in active development, with additional commit details, used for debugging and internal testing.
+
+
+The generic format for a version is as follows:
+
+```
+<owrt_release>-ns.<nethsecurity_release>-<commit_since_last_tag>-g<commit_hash>
+```
+
+- `<owrt_release>`: Main version number of OpenWRT.
+- `<nethsecurity_release>`: NethSecurity security version in [semver](https://semver.org/) format.
+- `<commit_since_last_tag>`: Number of commits since the last version tag, present only in development versions.
+- `g<commit_hash>`: Unique identifier for the current commit, prsent only in development versions.
+
+
+Stable version example:
+```
+8-20.05-ns.1.2.0
+```
+
+Unstable version example
+```
+8-20.05-ns.0.1.0-alpha1
+```
+
+Development version example:
+```
+8-20.05-ns.0.0.1-224-g26d3f78
+```
+
 ## Upstream version change
 
-Change the version inside the following files:
+Create a tag that contains the new OpenWrt release followed by a NethSecurity unstable release.
 
-- `builder/build-builder`
-- `config/branding.conf`
+Example:
+```
+git tag 23.05.2-ns.0.0.1-alpha1
+```
 
-Prepare a new Luci branch with NethSecurity customizations:
+Prepare a new Luci branch with NethSecurity customizations named after OpenWrt major and minor release:
 ```
 git remote add openwrt https://github.com/openwrt/luci.git
 git fetch openwrt
@@ -97,9 +136,12 @@ Then, push the changes:
 git push origin nethsec-23.05
 ```
 
-After changing the the upstream release:
+Finally, push the tags to start the build process:
+```
+git push --tags
+```
 
-- rebuild the builder container locally or push the changes and the CI pipeline will do it for you
+When the builder of the image has been completed, make sure to:
 - wipe podman volumes  otherwise the build will fail:
   ```
   podman volume rm nethsecurity-build_dir nethsecurity-staging_dir

docs/distfeed.md

@@ -6,13 +6,55 @@ nav_order: 30
 
 # Package repositories
 
+* TOC
+{:toc}
+
+## Channels
+
+The distribution feed includes the following channels:
+
+- `dev` channel: this channel is intended for unstable and development releases.
+- `stable` channel: this channel is for stable releases.
+- `subscription` channel: this channel is reserved for stable releases that have undergone additional testing. Access to this channel is restricted to machines with a valid subscription.
+
+## Repositories
+
 Official package repository is hosted at [{{site.download_url}}]({{site.download_url}}/index.html).
 
+Each release in the distribution feed is associated with two repositories:
+
+1. Fixed Repository:
+    - Contains packages and images from the build.
+    - This repository remains unchanged and is not used by the running images.
+
+2. Rolling Repository:
+    - Used by the running images.
+    - Contains all updates compatible within the same major OpenWRT release.
+
+### Examples
+
+Here are some examples of releases and their corresponding repositories:
+
+1. Dev example: `23.05.2-ns.0.0.1-217-g8786a2b`
+    - Fixed repository: `{{site.download_url}}/dev/23.05.2-ns.0.0.1-217-g8786a2b`
+    - Rolling repository: `{{site.download_url}}/dev/23.05.2`
+
+2. Stable example: `23.05.2-ns.0.0.1`
+    - Fixed repository: `{{site.download_url}}/stable/23.05.2-ns.0.0.1`
+    - Rolling repository: `{{site.download_url}}/stable/23.05.2`
+
+3. Unstable example: `23.05.2-ns.0.0.1-alpha1`
+    - Fixed repository: `{{site.download_url}}/dev/23.05.2-ns.0.0.1-alpha1`
+    - Rolling repository: `{{site.download_url}}/dev/23.05.2`
+
+## Upstream OpenWrt repositories
+
 You can add custom feeds by changing the `/etc/opkg/customfeeds.conf` file.
 
-To enable upstream package repositories use the following commands
+To enable OpenWrt package repositories use the following commands
 ```bash
 source /etc/os-release
+VERSION=$(echo $VERSION | cut -d- -f2)
 cat << EOF > /etc/opkg/customfeeds.conf 
 src/gz core https://downloads.openwrt.org/releases/$VERSION/targets/x86/64/packages
 src/gz base https://downloads.openwrt.org/releases/$VERSION/packages/x86_64/base