WIP - additional doc

Signed-off-by: Lou DeGenaro <[email protected]>

README.md

@@ -2,19 +2,82 @@
 
 compliance-trestle repository for agile authoring of catalog
 
-##### Documentation: catalog updates
+Prerequisite: [catalog template](https://github.com/IBM/compliance-trestle-template-catalog) has been used to [create catalog repo](https://github.com/IBM/compliance-trestle-agile-authoring/blob/main/README.create-repo-catalog.md) for agile authoring.
 
-- [update catalog](https://github.com/IBM/compliance-trestle-agile-authoring/blob/main/README.update-repo-catalog.md)
+
+- [view catalog markdown](#view-catalog-markdown)
+- [update catalog](#update-catalog)
+
+-----
+
+##### view catalog markdown
+
+Navigate to the `md_catalogs` folder, then descend to the control of interest.
+
+<details>
+<summary>visual</summary>
+<img src="drawio/ss.view-markdown.png" width="500" height="600">
+</details>
 
 -----
 
-##### Documentation: catalog repository setup
+##### update catalog
+
+<img src="drawio/update-catalog.drawio.png">
+
+Steps to modify the catalog repository with an updated catalog are given below:
+
+###### 1. navigate to develop branch location of catalog in repo.
+
+<details>
+<summary>visual</summary>
+<img src="drawio/ss.update-catalog.drawio.png" width="500" height="600">
+</details>
+
+###### 2. copy updated catalog to repo.
+
+<details>
+<summary>visual</summary>
+<img src="drawio/ss.update-catalog.drawio.png" width="500" height="600">
+</details>
+
+###### 3. compare & pull request
+
+<details>
+<summary>visual</summary>
+<img src="drawio/ss.compare-and-pull-request.drawio.png" width="500" height="600">
+</details>
+
+
+###### 4. create pull request
+
+<details>
+<summary>visual</summary>
+<img src="drawio/ss.create-pull-request.drawio.png" width="500" height="600">
+</details>
+
+
+###### 5. merge pull request
+
+<details>
+<summary>visual</summary>
+<img src="drawio/ss.merge-pull-request.drawio.png" width="500" height="600">
+</details>
+
+###### 6. confirm merge
+
+<details>
+<summary>visual</summary>
+<img src="drawio/ss.merge-pull-request.drawio.png" width="500" height="600">
+</details>
+
+-----
 
-- [setup catalog repo](https://github.com/IBM/compliance-trestle-agile-authoring/blob/main/README.create-repo-catalog.md)
+##### references
 
-##### Documentation: agile authoring
+- [documentation: setup catalog repo](https://github.com/IBM/compliance-trestle-agile-authoring/blob/main/README.create-repo-catalog.md)
 
-- [agile authoring](https://github.com/IBM/compliance-trestle-agile-authoring#compliance-trestle-agile-authoring)
+- [documentation: agile authoring](https://github.com/IBM/compliance-trestle-agile-authoring#compliance-trestle-agile-authoring)
 
 
 

drawio/update-catalog.drawio

@@ -0,0 +1,73 @@
+<mxfile host="Electron" modified="2023-06-16T17:30:40.771Z" agent="Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) draw.io/21.4.0 Chrome/112.0.5615.204 Electron/24.5.1 Safari/537.36" etag="PXzT_kkc_p40bVt4O2lD" version="21.4.0" type="device">
+  <diagram name="Page-1" id="OcNQJWf0w1j9XuQZADeh">
+    <mxGraphModel dx="1164" dy="753" grid="1" gridSize="10" guides="1" tooltips="1" connect="1" arrows="1" fold="1" page="1" pageScale="1" pageWidth="850" pageHeight="1100" math="0" shadow="0">
+      <root>
+        <mxCell id="0" />
+        <mxCell id="1" parent="0" />
+        <mxCell id="953rFPgKHFjmJHavNh2K-6" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;exitX=1;exitY=0.5;exitDx=0;exitDy=0;entryX=0.5;entryY=1;entryDx=0;entryDy=0;" parent="1" source="953rFPgKHFjmJHavNh2K-4" target="953rFPgKHFjmJHavNh2K-2" edge="1">
+          <mxGeometry relative="1" as="geometry" />
+        </mxCell>
+        <mxCell id="953rFPgKHFjmJHavNh2K-5" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;exitX=1;exitY=0.5;exitDx=0;exitDy=0;entryX=0.5;entryY=1;entryDx=0;entryDy=0;" parent="1" source="953rFPgKHFjmJHavNh2K-3" target="Td4egKe_wAdE8oFiXPUU-1" edge="1">
+          <mxGeometry relative="1" as="geometry" />
+        </mxCell>
+        <mxCell id="953rFPgKHFjmJHavNh2K-4" value="" style="rounded=0;whiteSpace=wrap;html=1;" parent="1" vertex="1">
+          <mxGeometry x="130" y="360" width="20" height="20" as="geometry" />
+        </mxCell>
+        <mxCell id="953rFPgKHFjmJHavNh2K-3" value="" style="rounded=0;whiteSpace=wrap;html=1;" parent="1" vertex="1">
+          <mxGeometry x="130" y="340" width="20" height="20" as="geometry" />
+        </mxCell>
+        <mxCell id="Kxdn-JrEQKSZMSrXZ_4Y-5" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;exitX=0.5;exitY=0;exitDx=0;exitDy=0;entryX=0.5;entryY=1;entryDx=0;entryDy=0;" parent="1" source="Td4egKe_wAdE8oFiXPUU-12" target="kNFgctC1tMzVj8SimGIi-55" edge="1">
+          <mxGeometry relative="1" as="geometry" />
+        </mxCell>
+        <mxCell id="sJczr7EHVSFUjlmMrbDo-2" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;exitX=1;exitY=0.5;exitDx=0;exitDy=0;entryX=0.5;entryY=1;entryDx=0;entryDy=0;fillColor=#FF0000;strokeColor=#FF33FF;" edge="1" parent="1" source="Td4egKe_wAdE8oFiXPUU-12" target="Td4egKe_wAdE8oFiXPUU-2">
+          <mxGeometry relative="1" as="geometry" />
+        </mxCell>
+        <mxCell id="Td4egKe_wAdE8oFiXPUU-12" value="" style="rounded=0;whiteSpace=wrap;html=1;" parent="1" vertex="1">
+          <mxGeometry x="130" y="320" width="20" height="20" as="geometry" />
+        </mxCell>
+        <mxCell id="PCGCRBoWbjobudrKsZ7f-6" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;exitX=1;exitY=0.5;exitDx=0;exitDy=0;entryX=0;entryY=0.5;entryDx=0;entryDy=0;shape=flexArrow;" parent="1" source="kNFgctC1tMzVj8SimGIi-55" target="Td4egKe_wAdE8oFiXPUU-2" edge="1">
+          <mxGeometry relative="1" as="geometry" />
+        </mxCell>
+        <mxCell id="kNFgctC1tMzVj8SimGIi-55" value="GIT repo&lt;br&gt;(develop)" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#A9C4EB;" parent="1" vertex="1">
+          <mxGeometry x="80" y="160" width="120" height="60" as="geometry" />
+        </mxCell>
+        <mxCell id="Td4egKe_wAdE8oFiXPUU-1" value="GIT repo&lt;br&gt;(develop)&lt;br&gt;pull request" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#A9C4EB;" parent="1" vertex="1">
+          <mxGeometry x="400" y="160" width="120" height="60" as="geometry" />
+        </mxCell>
+        <mxCell id="Kxdn-JrEQKSZMSrXZ_4Y-3" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;exitX=1;exitY=0.5;exitDx=0;exitDy=0;entryX=0;entryY=0.5;entryDx=0;entryDy=0;shape=flexArrow;" parent="1" source="Td4egKe_wAdE8oFiXPUU-2" target="Td4egKe_wAdE8oFiXPUU-1" edge="1">
+          <mxGeometry relative="1" as="geometry" />
+        </mxCell>
+        <mxCell id="Td4egKe_wAdE8oFiXPUU-2" value="GIT repo&lt;br&gt;(develop)&lt;br&gt;update catalog" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#A9C4EB;" parent="1" vertex="1">
+          <mxGeometry x="240" y="160" width="120" height="60" as="geometry" />
+        </mxCell>
+        <mxCell id="Td4egKe_wAdE8oFiXPUU-3" value="" style="verticalLabelPosition=bottom;sketch=0;aspect=fixed;html=1;verticalAlign=top;strokeColor=none;align=center;outlineConnect=0;shape=mxgraph.citrix.laptop_2;" parent="1" vertex="1">
+          <mxGeometry x="70" y="300" width="116" height="86.5" as="geometry" />
+        </mxCell>
+        <mxCell id="HQ_3SjkQ02_-DHeuNdse-4" value="Trestle&lt;br&gt;Agile Authoring&lt;br&gt;Repo Update" style="text;html=1;strokeColor=none;fillColor=none;align=center;verticalAlign=middle;whiteSpace=wrap;rounded=0;" parent="1" vertex="1">
+          <mxGeometry x="335" y="80" width="120" height="40" as="geometry" />
+        </mxCell>
+        <mxCell id="Kxdn-JrEQKSZMSrXZ_4Y-1" value="navigate" style="text;html=1;strokeColor=none;fillColor=none;align=center;verticalAlign=middle;whiteSpace=wrap;rounded=0;" parent="1" vertex="1">
+          <mxGeometry x="80" y="240" width="60" height="30" as="geometry" />
+        </mxCell>
+        <mxCell id="Kxdn-JrEQKSZMSrXZ_4Y-2" value="copy" style="text;html=1;strokeColor=none;fillColor=none;align=center;verticalAlign=middle;whiteSpace=wrap;rounded=0;" parent="1" vertex="1">
+          <mxGeometry x="250" y="240" width="60" height="30" as="geometry" />
+        </mxCell>
+        <mxCell id="953rFPgKHFjmJHavNh2K-2" value="GIT repo&lt;br&gt;(main)&lt;br&gt;merge" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#B9E0A5;" parent="1" vertex="1">
+          <mxGeometry x="560" y="160" width="120" height="60" as="geometry" />
+        </mxCell>
+        <mxCell id="953rFPgKHFjmJHavNh2K-7" value="semantic&lt;br&gt;versioning" style="text;html=1;strokeColor=none;fillColor=none;align=center;verticalAlign=middle;whiteSpace=wrap;rounded=0;" parent="1" vertex="1">
+          <mxGeometry x="395" y="240" width="60" height="30" as="geometry" />
+        </mxCell>
+        <mxCell id="953rFPgKHFjmJHavNh2K-10" value="approval" style="text;html=1;strokeColor=none;fillColor=none;align=center;verticalAlign=middle;whiteSpace=wrap;rounded=0;" parent="1" vertex="1">
+          <mxGeometry x="560" y="240" width="60" height="30" as="geometry" />
+        </mxCell>
+        <mxCell id="953rFPgKHFjmJHavNh2K-22" value="" style="shape=flexArrow;endArrow=classic;html=1;rounded=0;entryX=0;entryY=0.5;entryDx=0;entryDy=0;" parent="1" source="Td4egKe_wAdE8oFiXPUU-1" target="953rFPgKHFjmJHavNh2K-2" edge="1">
+          <mxGeometry width="50" height="50" relative="1" as="geometry">
+            <mxPoint x="400" y="390" as="sourcePoint" />
+            <mxPoint x="450" y="340" as="targetPoint" />
+          </mxGeometry>
+        </mxCell>
+      </root>
+    </mxGraphModel>
+  </diagram>
+</mxfile>

scripts/automation/check_and_update_all.sh

@@ -4,7 +4,7 @@ CHANGES=`git diff-tree --no-commit-id --name-only -r HEAD`
 
 md_changed=false
 json_changed=false
-txt_changed=false
+xlsx_changed=false
 
 # bash regex does not support lazy match, so need to use two patterns to match before and after the control id
 md1=$"^md_catalogs/"
@@ -13,6 +13,9 @@ md2=$"\.md$"
 json1=$"^catalogs/"
 json2=$"\.json$"
 
+xlsx1=$"^data/"
+xlsx2=$"\.xlsx$"
+
 for val in ${CHANGES[@]} ; do
   if [[ $val =~ $md1 && $val =~ $md2 ]]; then
     md_changed=true
@@ -21,17 +24,29 @@ for val in ${CHANGES[@]} ; do
   if [[ $val =~ $json1 && $val =~ $json2 ]]; then
     json_changed=true
   fi
+
+  if [[ $val =~ $xlsx1 && $val =~ $xlsx2 ]]; then
+    xlsx_changed=true
+  fi
 done
 
+if [[ $xlsx_changed = true ]]; then
+    echo "Xlsx file(s) were changed, generating catalog JSON and regenerating markdowns..."
+    python scripts/fs_cloud_create_oscal_catalog.py --input data/IBM_Cloud_Framework_for_Financial_Services_-_Control_Requirements_v1.1.0.xlsx --sheet "Control Requirements" --output catalogs/IBM_FS_CLOUD_ONLY --catalog catalogs/NIST_800-53_rev4/catalog.json
+    ./scripts/automation/regenerate_catalogs.sh
+fi
+
 if [[ $json_changed = true ]]; then
-    echo "Json file(s) were changed, regenerating catalogs..."
+    echo "Json file(s) were changed, regenerating markdowns..."
     ./scripts/automation/regenerate_catalogs.sh
 fi
 
 
 if [[ $md_changed = true ]]; then
-    echo "Md file(s) were changed, assembling catalogs..."
+    echo "Md file(s) were changed, assembling catalog..."
     ./scripts/automation/assemble_catalogs.sh
 fi
 
-echo "$md_changed $json_changed"
+
+
+echo "$md_changed $json_changed $xlsx_changed"

scripts/automation/release.sh

@@ -3,7 +3,7 @@
 source config.env
 
 version_tag=$(semantic-release print-version)
-echo "Bumping version of profiles to ${version_tag}" 
+echo "Bumping version of catalogs to ${version_tag}" 
 export VERSION_TAG="$version_tag"
 echo "VERSION_TAG=${VERSION_TAG}" >> $GITHUB_ENV