Append .git submodule repositories, update guide
The submodule path hierarchy needs to support a name used as
hierarchy for lower level repositories or groupIDs AND allow
for a repository at each level eg submodules/appc and
submodules/appc/deployment are both repos. When viewed
in the submodule directory structure in the doc project, a
repository will have .git appended. The above example would
be submodules/appc.git submodules/appc/deployment.git
Change how to guide and convert existing submodule names
Rebased prior change
Change-Id: Ie16b8bbda7562aaaee3c21eb504dc6e293c98cbd
Issue-ID: DOC-33
Signed-off-by: Rich Bennett <rb2745@att.com>
diff --git a/.gitmodules b/.gitmodules
index 50be5f2..146a3c8 100644
--- a/.gitmodules
+++ b/.gitmodules
@@ -1,25 +1,25 @@
[submodule "docs/submodules/vnfrqts/guidelines"]
- path = docs/submodules/vnfrqts/guidelines
+ path = docs/submodules/vnfrqts/guidelines.git
url = ../vnfrqts/guidelines
branch = .
ignore = dirty
[submodule "docs/submodules/vnfrqts/requirements"]
- path = docs/submodules/vnfrqts/requirements
+ path = docs/submodules/vnfrqts/requirements.git
url = ../vnfrqts/requirements
branch = .
ignore = dirty
[submodule "docs/submodules/appc"]
- path = docs/submodules/appc
+ path = docs/submodules/appc.git
url = ../appc
branch = .
ignore = dirty
[submodule "docs/submodules/cli"]
- path = docs/submodules/cli
+ path = docs/submodules/cli.git
url = ../cli
branch = .
ignore = dirty
[submodule "docs/submodules/clamp"]
- path = docs/submodules/clamp
+ path = docs/submodules/clamp.git
url = ../clamp
branch = .
ignore = dirty
diff --git a/docs/guide/onap-developer/how-to-use-docs/include-documentation.rst b/docs/guide/onap-developer/how-to-use-docs/include-documentation.rst
index 9052090..f41268f 100644
--- a/docs/guide/onap-developer/how-to-use-docs/include-documentation.rst
+++ b/docs/guide/onap-developer/how-to-use-docs/include-documentation.rst
@@ -24,10 +24,12 @@
DA -> DR [label = "Create initial\n doc repository content"];
DA <<-- DR [label = "Merge" ];
RD <-- DA [label = "Connect gerrit.onap.org" ];
- === For each new project repository containing document source ===
- DA -> DR [label = "Add new project repo as\ngit submodule" ];
- DA <-- DR [label = "Merge" ];
- PA -> PR [label = "Create in new project repo\ntop level directory and index.rst" ];
+ === For each project repository containing document source ===
+ PA -> DR [label = "Add project repo as\ngit submodule" ];
+ DR -> DA [label = "Review & Plan to\nIntegrate Content with\nTocTree Structure" ];
+ DR <-- DA [label = "Vote +2/Merge" ];
+ PA <-- DR [label = "Merge Notification" ];
+ PA -> PR [label = "Create in project repo\ntop level directory and index.rst" ];
PR -> DA [label = "Add as Reviewer" ];
PR <-- DA [label = "Approve and Integrate" ];
PA <-- PR [label = "Merge" ];
@@ -49,40 +51,46 @@
doc project repo in gerrit.onap.org.
-Setup new project repositories(s)
----------------------------------
-These steps are performed for each new project repo (referred to in the
-next two code blocks as $reponame):
+Setup project repositories(s)
+-----------------------------
+These steps are performed for each project repository that provides documentation.
-(1) clone, modify, and commit to the doc project: a directory under doc/docs/submodules with the same path/name as the new project initialized as a git submodule.
+First let's set two variables that will be used in the following examples.
+Set reponame to the project repository you are setting up just as it appears in the
+**Project Name** column of the Gerrit projects page.
+Set lfid to your Linux Foundation identity that you use to login to gerrit or for git
+clone requests over ssh.
+
+.. code-block:: bash
+
+ reponame=
+ lfid=
+
+The next step is to add a directory in the doc project where your project will be included as a
+submodule and at least one reference from the doc project to the documentation index in your repository.
.. code-block:: bash
- reponame=<your_repo_name>
-
- git clone ssh://<your_id>@gerrit.onap.org:29418/doc
+ git clone ssh://$lfid@gerrit.onap.org:29418/doc
cd doc
mkdir -p `dirname docs/submodules/$reponame`
- git submodule add https://gerrit.onap.org/r/$reponame docs/submodules/$reponame
- git submodule init docs/submodules/$reponame
- git submodule update docs/submodules/$reponame
+ git submodule add https://gerrit.onap.org/r/$reponame docs/submodules/$reponame.git
+ git submodule init docs/submodules/$reponame.git
+ git submodule update docs/submodules/$reponame.git
- echo " $reponame <../submodules/$reponame/docs/index>" >> docs/release/repolist.rst
+ echo " $reponame <../submodules/$reponame.git/docs/index>" >> docs/release/repolist.rst
git add .
- git commit -m "Add $reponame as a submodule" -s
- git commit --amend
- # modify the commit message to comply with ONAP best practices
+ git commit -s
git review
-(2) clone, modify, and commit to the new project an initial: docs top
-level directory; index.rst; any other intial content.
+The last step is to create a docs directory in your repository with an index.rst file.
.. code-block:: bash
- git clone ssh://<your_id>@gerrit.onap.org:29418/$reponame
+ git clone ssh://$lfid@gerrit.onap.org:29418/$reponame
cd $reponame
mkdir docs
echo ".. This work is licensed under a Creative Commons Attribution 4.0 International License.
@@ -95,9 +103,7 @@
" > docs/index.rst
git add .
- git commit -m "Add RST docs directory and index" -s
- git commit --amend
- # modify the commit message to comply with ONAP best practices
+ git commit -s
git review
@@ -137,8 +143,8 @@
reponame -> reponamedocsdir;
reponamesm -> reponamedocsdir;
reponamedocsdir [label="docs"];
- reponamedocsdir -> newrepodocsdirindex;
- newrepodocsdirindex [label="index.rst", shape=box];
+ reponamedocsdir -> repnamedocsdirindex;
+ repnamedocsdirindex [label="index.rst", shape=box];
//Show detail structure of a portion of doc/docs
doc -> docs;
@@ -156,7 +162,7 @@
//Show submodule linkage to docs directory
submodules -> reponamesm [style=dotted,label="git\nsubmodule\nreference"];
- reponamesm [label="reponame"];
+ reponamesm [label="reponame.git"];
//Example Release document index that references component info provided in other project repo
release -> releasedocumentindex;
@@ -164,7 +170,7 @@
releasedocumentindex -> releaserepolist [style=dashed, label="sphinx\ntoctree\nreference"];
releaserepolist [label="repolist.rst", shape=box];
release -> releaserepolist;
- releaserepolist -> newrepodocsdirindex [style=dashed, label="sphinx\ntoctree\nreference"];
+ releaserepolist -> repnamedocsdirindex [style=dashed, label="sphinx\ntoctree\nreference"];
}
diff --git a/docs/guide/vnf-provider/index.rst b/docs/guide/vnf-provider/index.rst
index 342c35d..c43c5f3 100644
--- a/docs/guide/vnf-provider/index.rst
+++ b/docs/guide/vnf-provider/index.rst
@@ -8,5 +8,5 @@
.. toctree::
:maxdepth: 2
- ../../submodules/vnfrqts/guidelines/docs/index.rst
- ../../submodules/vnfrqts/requirements/docs/index.rst
+ ../../submodules/vnfrqts/guidelines.git/docs/index.rst
+ ../../submodules/vnfrqts/requirements.git/docs/index.rst
diff --git a/docs/release/repolist.rst b/docs/release/repolist.rst
index f24ff43..1f57f7f 100644
--- a/docs/release/repolist.rst
+++ b/docs/release/repolist.rst
@@ -5,8 +5,8 @@
:maxdepth: 1
:titlesonly:
- appc <../submodules/appc/appc/docs/index>
- vnfrqts/guidelines <../submodules/vnfrqts/guidelines/docs/index>
- vnfrqts/requirements <../submodules/vnfrqts/requirements/docs/index>
- cli <../submodules/cli/docs/index>
- clamp <../submodules/clamp/docs/index>
+ appc <../submodules/appc.git/docs/index>
+ vnfrqts/guidelines <../submodules/vnfrqts/guidelines.git/docs/index>
+ vnfrqts/requirements <../submodules/vnfrqts/requirements.git/docs/index>
+ cli <../submodules/cli.git/docs/index>
+ clamp <../submodules/clamp.git/docs/index>
diff --git a/docs/submodules/appc b/docs/submodules/appc.git
similarity index 100%
rename from docs/submodules/appc
rename to docs/submodules/appc.git
diff --git a/docs/submodules/clamp b/docs/submodules/clamp.git
similarity index 100%
rename from docs/submodules/clamp
rename to docs/submodules/clamp.git
diff --git a/docs/submodules/cli b/docs/submodules/cli.git
similarity index 100%
rename from docs/submodules/cli
rename to docs/submodules/cli.git
diff --git a/docs/submodules/vnfrqts/guidelines b/docs/submodules/vnfrqts/guidelines.git
similarity index 100%
rename from docs/submodules/vnfrqts/guidelines
rename to docs/submodules/vnfrqts/guidelines.git
diff --git a/docs/submodules/vnfrqts/requirements b/docs/submodules/vnfrqts/requirements.git
similarity index 100%
rename from docs/submodules/vnfrqts/requirements
rename to docs/submodules/vnfrqts/requirements.git