From e4c42511f8b14d8935fd5de89e072ecd33215c8a Mon Sep 17 00:00:00 2001 From: Rich Bennett Date: Wed, 6 Sep 2017 08:07:22 -0400 Subject: [PATCH] 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 --- .gitmodules | 10 ++-- .../how-to-use-docs/include-documentation.rst | 64 ++++++++++++---------- docs/guide/vnf-provider/index.rst | 4 +- docs/release/repolist.rst | 10 ++-- docs/submodules/{appc => appc.git} | 0 docs/submodules/{clamp => clamp.git} | 0 docs/submodules/{cli => cli.git} | 0 .../vnfrqts/{guidelines => guidelines.git} | 0 .../vnfrqts/{requirements => requirements.git} | 0 9 files changed, 47 insertions(+), 41 deletions(-) rename docs/submodules/{appc => appc.git} (100%) rename docs/submodules/{clamp => clamp.git} (100%) rename docs/submodules/{cli => cli.git} (100%) rename docs/submodules/vnfrqts/{guidelines => guidelines.git} (100%) rename docs/submodules/vnfrqts/{requirements => requirements.git} (100%) diff --git a/.gitmodules b/.gitmodules index 50be5f26b..146a3c897 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 9052090bd..f41268f99 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 @@ below. 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 @@ These steps are performed only once for the doc project and include: 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. + +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. -(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. - .. code-block:: bash - reponame= + 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 - git clone ssh://@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://@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 @@ level directory; index.rst; any other intial content. " > 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 @@ a jenkins verify job, and/or published release documentation including: 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 @@ a jenkins verify job, and/or published release documentation including: //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 @@ a jenkins verify job, and/or published release documentation including: 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 342c35da9..c43c5f394 100644 --- a/docs/guide/vnf-provider/index.rst +++ b/docs/guide/vnf-provider/index.rst @@ -8,5 +8,5 @@ VNF Provider Guide .. 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 f24ff43a4..1f57f7f93 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 -- 2.16.6