[Starlingx-discuss] Full process to update/add documentation pages (gerrit review push issue)

[Dominig ar Foll (Intel Open Source)]

On 12/09/2019 15:52, Jeremy Stanley wrote:
>
>     https://docs.openstack.org/infra/manual/developers.html
>
> It covers topics such as Gerrit account setup.
Thanks that bit is helpful.

But my review still fails.
dominig at dominig-t480:~/starlingx/git/docs/doc/source/developer_resources>
git review -t "initial creation Doc page Navigate Git Code story/2005184"
Creating a git remote called 'gerrit' that maps to:
        ssh://dominig@review.opendev.org:29418/starlingx/docs.git
Your change was committed before the commit hook was installed.
Amending the commit to add a gerrit change id.
error: src refspec creation does not match any.
error: src refspec Doc does not match any.
error: src refspec page does not match any.
error: src refspec Navigate does not match any.
error: src refspec Git does not match any.
error: src refspec Code does not match any.
error: src refspec story/2005184 does not match any.
error: failed to push some refs to
'ssh://dominig@review.opendev.org:29418/starlingx/docs.git'

My changes are not rocket science (see diff bellow) but still did not
make it :-(
The pending review  is not visible in Gerrit.

-- 
Dominig ar Foll
Senior Software Architect
Intel Open Source Technology Centre

diff --git a/doc/source/developer_resources/navigate_source_code.rst b/doc/source/developer_resources/navigate_source_code.rst                                                               
index 7a14dfe..3d597f6 100644
--- a/doc/source/developer_resources/navigate_source_code.rst
+++ b/doc/source/developer_resources/navigate_source_code.rst
@@ -2,9 +2,61 @@
 How to navigate the StarlingX source code
 =========================================
 
-This topic is coming soon.
+The StartlingX code is kept in various git directories. In order to simplify the downloading process of keeping your local copy up to date, StartlingX project provides Android type repo manifests which can be followed by the repo tool.
+
+
+^^^^^^^^^^^^^^^^^
+Tools required
+^^^^^^^^^^^^^^^^^
+
+   On top of your prefer text editor you will need two tools to download the StartlingX source code:
+     - git (certainly available from your prefered Linux distro)
+     - Android repo tool. A simple python script that is installed manually.
+     
+   To install git, follow the instruction to install git package from your Linux distro.
+
+   To install the required Android Repo Tool in the Linux host system. Follow
+   the steps in the `Installing
+   Repo <https://source.android.com/setup/build/downloading#installing-repo>`
+   
+   You will find more details on the repo tool `here <https://source.android.com/setup/develop/repo>`
+   
+
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Initial download of StartlingX code
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+#. Create a *starlingx* workspace directory on your system.
+   Best practices dictate creating the workspace directory
+   in your $HOME directory:
+
+   .. code:: sh
+
+      $ mkdir -p $HOME/starlingx/
+      
+#. Use the repo tool to create a local clone of the manifest
+   Git repository based on the "master" branch:
+
+   .. code:: sh
+
+      $ cd $MY_REPO_ROOT_DIR
+      $ repo init -u https://opendev.org/starlingx/manifest -m default.xml
+
+#. Synchronize the repository:
+
+   .. code:: sh
+
+      $ repo sync -j`nproc`
+      
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Keeping in sync with StartlingX upstream code code
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+   .. code:: sh
+
+      $ repo sync -j`nproc`
+
 
-Linked Story does not yet exist.
 
 .. `Linked Story <https://storyboard.openstack.org/#!/story/2005184>`__
 
~