From b350ba6ca984bc1e9d4206982d3f3a5e7815b964 Mon Sep 17 00:00:00 2001
From: Roger Ferraz <rogerio.ferraz@encora.com>
Date: Tue, 11 Jul 2023 18:40:08 -0300
Subject: [PATCH] starlingx/manifest README improvement

This story shall update the README file of a few most used StarlingX
repos.

Test Plan: N/A

Story: 2010814
Task: 48356

Change-Id: I2f56c9072bef7da5bd5ae9a2e8f3c90f71b10ecc
Signed-off-by: Roger Ferraz <rogerio.ferraz@encora.com>
---
 README.rst | 62 ++++++++++++++++++++++++++++++++++++++++++++++--------
 1 file changed, 53 insertions(+), 9 deletions(-)

diff --git a/README.rst b/README.rst
index 44c5269..862f02b 100644
--- a/README.rst
+++ b/README.rst
@@ -1,15 +1,59 @@
-==========
-manifest
-==========
-
+==================
 StarlingX Manifest
+==================
+
+Download
+--------
+The StarlingX source code can be downloaded from the default manifest XML file,
+by using the git-repo tool [1]_, with the following commands::
+
+    export MANIFEST_URL="https://opendev.org/starlingx/manifest.git"
+    export MANIFEST_BRANCH="master"
+    export MANIFEST="default.xml"
+    repo init -u ${MANIFEST_URL} -b ${MANIFEST_BRANCH} -m ${MANIFEST}
+    repo sync
+
+StarlingX Build Environment
+---------------------------
+The StarlingX Build Environment [2]_ is a set of containers designed to run in a
+Kubernetes environment.
+
+As an alternative, a Vagrant-based StarlingX Build Environment is available in
+the starlingx/tis-repo [3]_.
+
+Layered Build
+-------------
+Build layering [4]_ is a feature to accelerate development within StarlingX.
+It optimizes the build of a small set of most-used top level packages, while
+avoiding rebuild of a large amount of infrequently used packages.
+
+The packages are partitioned into the following layers, according to the
+corresponding manifests:
+
+- compiler: Low level build tools: compilers, scripts, and packaging tools;
+- distro: Linux and third party packages, e.g. ceph, openstack;
+- flock: Basic StarlingX packages. These are the most used ones.
+
+Reserved Manifests
+------------------
+The following manifests are reserved:
+
+- common: packages always included in the build, regardless of layer;
+- containers: packages to build containers;
+- default: used as a means to download the StarlingX source code.
 
 Developer Notes
 ---------------
-When updating xml files in this repo please remember to update the appropriate
-.gitignore file in https://opendev.org/starlingx/root otherwise the
-"repo status" command will show the new repo as an untracked change.
+When updating XML files, please remember to update the appropriate .gitignore
+file in https://opendev.org/starlingx/root otherwise the "repo status" command
+will show the new repo as an untracked change.
 
-When updating the default.xml manifest, please also remember to update
-the appropriate layer manifest as well.
+When updating the default.xml manifest, please also remember to update the
+appropriate layer manifest as well.
 
+References
+----------
+.. [1] https://gerrit.googlesource.com/git-repo/#install
+.. [2] https://wiki.openstack.org/wiki/StarlingX/DebianBuildEnvironment
+.. [3] https://opendev.org/starlingx/tis-repo
+.. [4] https://docs.starlingx.io/developer_resources/Layered_Build.html