doc: improve package readme

packages/README.md

@@ -1,7 +1,25 @@
-# NethServer packages
+---
+layout: default
+has_children: true
+title: Packages
+nav_order: 10
+---
+# Packages
 
-Add new packages to this directory, packages will be automatically available inside `make menuconfig`.
-Make sure to enable it on build time adding the correct configuration file inside `../conf` dir.
+The NethSecurity build system is based on OpenWrt, which uses the concept of packages to manage software components.
+NethSecurity includes two different sets of packages: NethSecurity packages and OpenWrt packages.
+
+* TOC
+{:toc}
+
+# NethSecurity packages
+
+NethSecurity packages are added to a special `nspackages` feed, which is included in the image
+at every build. This feed is used to include custom packages that are not part of the OpenWrt.
+
+To add a new package, just create a new directory inside the `packages` directory.
+All packages inside this directory will be automatically available inside `make menuconfig`.
+Make sure to enable it on build time adding the correct configuration file inside `conf` dir.
 
 Conventions:
 - the name of the package should always start with `ns-` prefix. Example: `ns-myapp`
@@ -39,6 +57,33 @@ Or, using a one-liner:
 ./run bash -- -c "make package/feeds/nethsecurity/ns-myapp/{download,compile} V=sc"
 ```
 
-The package will be availale inside `bin/packages/x86_64/nethsecurity/ns-myapp_<version>_all.ipk`.
+The package will be available inside `bin/packages/x86_64/nethsecurity/ns-myapp_<version>_all.ipk`.
 
 For more info, see [upstream guide](https://openwrt.org/docs/guide-developer/packages)
+
+## OpenWrt packages
+
+OpenWrt packages are included in the NethSecurity image only when creating the image builder.
+The image builder is container used to create the final NethSecurity image.
+
+There is a [packages repository](https://github.com/openwrt/packages/) inside GitHub that contains all the packages.
+Please note that the branches inside this repository, like `openwrt-23.05` are not the ones used by the build system.
+
+The version of the packages repository used in the build is the one indicated in the `feeds.conf.default` file.
+You can find it by running `./run bash`.
+
+Example of the content of `feeds.conf.default`:
+```
+src-git packages https://git.openwrt.org/feed/packages.git^b5ed85f6e94aa08de1433272dc007550f4a28201
+src-git luci https://git.openwrt.org/project/luci.git^63ba3cba5b7bfb803a875d4d8f01248634687fd5
+src-git routing https://git.openwrt.org/feed/routing.git^e351d1e623e9ef2ab78f28cb1ce8d271d28c902d
+src-link nethsecurity /home/build/openwrt/nspackages
+```
+
+This file indicates that the `packages` repository is used at commit `b5ed85f6e94aa08de1433272dc007550f4a28201`.
+Since the image builder is created only once per release, the packages are not updated at every build,
+but only when a new release is created.
+
+Every build produces a Packages.manifest file that contains the list of all the packages included in the image.
+Note that a manifest can change between builds, even if the packages are not updated.
+This means that builds are not reproducible, but it is not a problem if the version of the packages does not change.