feat(docs) - Delivery Toolkit Documentation & Changes (Updated)

.github/ISSUE_TEMPLATE/release_proposal.md

@@ -23,7 +23,7 @@ assignees: "damienjburks"
 - [ ] Modify the `metadata.yaml` files to include the latest release details. This can be accomplished in an automated form by running the following command:
 
   ```text
-  cd delivery-tooling
+  cd delivery-toolkit
   go run . release-notes -t /services/storage/object
   ```
 

.github/workflows/pr-title.yaml

@@ -0,0 +1,31 @@
+## Reference: https://github.com/amannn/action-semantic-pull-request
+---
+name: "Lint PR Title"
+on:
+  # pull_request_target event is required for autolabeler to support all PRs including forks
+  pull_request_target:
+    types: [opened, reopened, edited, synchronize]
+jobs:
+  lint_pr_title:
+    permissions:
+      contents: read
+      pull-requests: read
+      statuses: write
+    uses: jmeridth/reusable-workflows/.github/workflows/pr-title.yaml@d788c4f6994c7b37134a9f592fe5db42fd7a0957
+    with:
+      types: |
+        ci
+        docs
+        feat
+        fix
+      scopes: |
+        add
+        category
+        change
+        controls
+        family
+        remove
+        threats
+      requireScope: true
+    secrets:
+      github-token: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/release.yml

@@ -17,7 +17,7 @@ jobs:
     runs-on: ubuntu-latest
     defaults:
       run:
-        working-directory: ./delivery-tooling
+        working-directory: ./delivery-toolkit
     steps:
       - uses: actions/checkout@v4
         name: Build
@@ -65,7 +65,7 @@ jobs:
         uses: actions/upload-artifact@v4.4.0
         with:
           name: ccc-catalogs
-          path: ./delivery-tooling/artifacts/*
+          path: ./delivery-toolkit/artifacts/*
           if-no-files-found: error
           retention-days: 1 # Maximum Retention
 

.github/workflows/sonatype_scan.yaml

@@ -9,7 +9,7 @@ on:
 env:
   SonatypeUrl: "https://finos.sonatype.app/platform/"
   SonatypeAppId: "ccc-delivery"
-  SonatypeScanTarget: "delivery-tooling/"
+  SonatypeScanTarget: "delivery-toolkit/"
   ExcludeDirectory: ""
 
 jobs:

.gitignore

@@ -3,5 +3,5 @@ build/oscal-cli
 # VS Code 
 .DS_Store
 # Delivery Tooling
-delivery-tooling/artifacts
+delivery-toolkit/artifacts
 .env/

.prettierignore

@@ -1 +1 @@
-delivery-tooling/*
+delivery-toolkit/*

delivery-tooling/main.go → delivery-toolkit/main.go

@@ -35,7 +35,7 @@ var (
 		},
 		Run: func(cmd *cobra.Command, args []string) {
 			fmt.Println(divider)
-			fmt.Println("Welcome to the CCC Delivery Tooling CLI v" + Version)
+			fmt.Println("Welcome to the CCC Delivery Toolkit CLI v" + Version)
 			fmt.Print(logo)
 			fmt.Println(divider)
 			fmt.Println("You appear to be exploring!")

docs/community-guidelines/content-standards-and-practices/control-definitions.md

@@ -8,7 +8,7 @@ Each service category in the CCC Taxonomy should have its own set of control def
 
 To streamline maintenance, the CCC project maintains a list of [common controls].
 
-Each service category’s `controls.yaml` file references these by listing their IDs under the top-level `common_controls` value. During the release pipeline, our [delivery tooling] compiles these common controls into the final document alongside any specific controls. In the final output, both types of controls are presented consistently, with the unique identifier being the only difference.
+Each service category’s `controls.yaml` file references these by listing their IDs under the top-level `common_controls` value. During the release pipeline, our [Delivery Toolkit] compiles these common controls into the final document alongside any specific controls. In the final output, both types of controls are presented consistently, with the unique identifier being the only difference.
 
 ### Common Controls
 
@@ -56,7 +56,7 @@ A control family refers to a group of related security controls that are organiz
 The list of control families is maintained in the [common controls] data.
 
 [common controls]: /services/common-controls.yaml
-[delivery tooling]: /delivery-tooling
+[Delivery Toolkit]: /delivery-toolkit
 [threats]: ./threat-definitions.md
 [ref]: https://www.cisa.gov/sites/default/files/2023-02/tlp-2-0-user-guide_508c.pdf
 

docs/community-guidelines/content-standards-and-practices/feature-definitions.md

@@ -8,7 +8,7 @@ Each feature definition should be created for a service in the CCC Taxonomy, wit
 
 To streamline maintenance, the CCC project maintains a list of [common features].
 
-Each service category’s `features.yaml` file references common features by listing their IDs under the top-level `common_features` value. During the release pipeline, our [delivery tooling] compiles these common features into the final document alongside any specific features. In the final output, both types of features are presented consistently, with the unique identifier being the only difference.
+Each service category’s `features.yaml` file references common features by listing their IDs under the top-level `common_features` value. During the release pipeline, our [Delivery Toolkit] compiles these common features into the final document alongside any specific features. In the final output, both types of features are presented consistently, with the unique identifier being the only difference.
 
 ### Common Features
 
@@ -47,4 +47,4 @@ Although a review from the [Communications WG] is optional, it may be useful if
 
 [common features]: /services/common-features.yaml
 [Communications WG]: ../../governance/working-groups/communications/charter.md
-[delivery tooling]: /delivery-tooling
+[Delivery Toolkit]: /delivery-toolkit

docs/community-guidelines/content-standards-and-practices/threat-definitions.md

@@ -8,7 +8,7 @@ Each threat definition corresponds to a service in the CCC Taxonomy, with every
 
 To streamline maintenance, the CCC project maintains a list of [common threats].
 
-Each service category’s `threats.yaml` file references these common threats by listing their IDs under the top-level `common_threats` value. During the release pipeline, our [delivery tooling] compiles these common threats into the final document alongside any service-specific threats. In the final output, both types of threats are presented consistently, with the unique identifier being the only difference.
+Each service category’s `threats.yaml` file references these common threats by listing their IDs under the top-level `common_threats` value. During the release pipeline, our [Delivery Toolkit] compiles these common threats into the final document alongside any service-specific threats. In the final output, both types of threats are presented consistently, with the unique identifier being the only difference.
 
 ### Common Threats
 
@@ -89,5 +89,5 @@ This structure ensures that threats are standardized and can be consistently ide
 
 [common threats]: /services/common-threats.yaml
 [Communications WG]: ../../governance/working-groups/communications/charter.md
-[delivery tooling]: /delivery-tooling
+[Delivery Toolkit]: /delivery-toolkit
 [threats template]: ../../resources/templates/threats.yaml

docs/resources/training/Readme.md

@@ -3,5 +3,6 @@
 ## Links
 
 - [OSCAL](https://github.com/finos/common-cloud-controls/blob/main/docs/resources/training/oscal/oscal.md)
-- [Markdown Linting and Formatting - End User Guide](./lint_format_user_guide.md)
+- [Markdown Linting and Formatting - End User Guide](user_guides/linting_and_formatting.md)
 - [FINOS CCC Primer](./FINOS-CCC-Primer-June-2024.pdf)
+- [Delivery Toolkit - User Guide](user_guides/delivery_toolkit.md)

docs/resources/training/user_guides/delivery_toolkit.md

@@ -0,0 +1,173 @@
+# Delivery Toolkit - User Guide
+
+Welcome to the **Delivery Toolkit** user guide—a powerful solution built with Go, GitHub Actions, and GitHub Releases to automate the creation and compilation of artifacts for public release.
+
+Before contributing to the codebase, we highly recommend reviewing the [Releases] documentation. The development process is aligned with the strategies outlined there, ensuring consistency and quality across all contributions.
+
+## Overview
+
+The Delivery Toolkit consists of several Go files, each serving a specific purpose in the release process. Below is an overview of these files:
+
+1. **`catalog-compiler.go`**  
+   Compiles YAML-based controls, features, threats, and metadata into a unified catalog with autogenerated links.
+
+2. **`gen-markdown.go`**  
+   Generates a styled omnibus Markdown file by compiling YAML-based data and rendering it with customizable templates.
+
+3. **`gen-release-notes.go`**  
+   Produces release notes by compiling catalog data and rendering them into Markdown via customizable templates.
+
+4. **`gen-yaml.go`**  
+   Converts catalog data into a YAML file and saves it in the specified output directory.
+
+5. **`update-metadata.go`**  
+   Updates metadata YAML files, including commit history, contributors, and changelogs, using the GitHub API.
+
+6. **`utils.go`**  
+   Provides shared utility functions to streamline development across the toolkit.
+
+## Local Setup and Configuration
+
+### Prerequisites
+
+Before you begin, ensure the following tools are installed:
+
+1. [**Golang**](https://go.dev/doc/install) - The primary language of the project.
+2. [**VS Code**](https://code.visualstudio.com/download) - A versatile code editor.
+3. [**Git**](https://git-scm.com/downloads) - For version control and repository management.
+4. [**Docker**](https://docs.docker.com/engine/install/) - Used for PDF generation.
+
+Additionally, install the **Go VS Code Extension** for a better development experience:  
+[Install here](https://marketplace.visualstudio.com/items?itemName=golang.go).  
+![VS Code Extensions](imgs/delivery_toolkit/image-6.png)
+
+### Installing Dependencies
+
+1. Clone the repository locally:
+
+   ```bash
+   git clone <repository-url>
+   ```
+
+   If you're new to Git, follow this guide: [How to Git Clone](https://www.geeksforgeeks.org/how-to-git-clone-a-remote-repository/).
+
+2. Open the repository in VS Code and run the following commands in the terminal:
+
+   ```bash
+   cd delivery-toolkit
+   go get # Install required dependencies
+   ```
+
+3. Verify the setup:
+
+   ```bash
+   go run .
+   ```
+
+   **Expected Output**:
+
+   ```bash
+   ----------------------------------------
+        _______________
+       / ___/ ___/ ___/
+      / /  / /  / /
+     / /__/ /__/ /___
+     \____/____/____/
+
+   ----------------------------------------
+
+   Welcome to the CCC Delivery Toolkit CLI v0.0.0-dev
+   Use the 'help' command (-h) to explore available options.
+   ----------------------------------------
+   ```
+
+4. Pull the Docker image required for PDF generation:
+
+   ```bash
+   docker pull jmaupetit/md2pdf
+   ```
+
+## Testing Locally
+
+Here are some example commands for testing the toolkit locally:
+
+- **Generate an Omnibus Markdown File**
+
+  ```bash
+  go run . "md" -t ../services/storage/object/
+  ```
+
+  **Output Example**:
+
+  ```text
+  File generated successfully: artifacts/CCC.ObjStor_2025.01.md
+  ```
+
+- **Generate a YAML File**
+
+  ```bash
+  go run . "yaml" -t ../services/storage/object/
+  ```
+
+  **Output Example**:
+
+  ```text
+  File generated successfully: ./artifacts/CCC.ObjStor_2025.01.yaml
+  ```
+
+- **Generate Release Notes**
+
+  ```bash
+  go run . "release-notes" -t ../services/storage/object/
+  ```
+
+  **Output Example**:
+
+  ```text
+  File generated successfully: artifacts/release_notes.md
+  ```
+
+- **Update Metadata**
+
+  ```bash
+  go run . "update-metadata" -t ../services/storage/object/
+  ```
+
+  **Output Example**:
+
+  ```text
+  Metadata updated successfully: ../services/storage/object/metadata.yaml
+  ```
+
+  > **NOTE**: This command modifies metadata files and should only be used during release preparation.
+
+## Triggering the Artifact Pipeline
+
+The Artifact Pipeline is the backbone of the Delivery Toolkit, leveraging GitHub Actions to:
+
+- Compile version-controlled catalog data.
+- Create a release candidate using GitHub Releases.
+- Generate release notes with appropriate tagging.
+
+### Steps to Execute
+
+1. Log in to GitHub and navigate to the `common-cloud-controls` repository.
+2. Click **Actions** in the repository menu.  
+   ![Actions Tab](imgs/delivery_toolkit/image.png)
+3. Select the **Release Workflow** on the left-hand side.  
+   ![Release Workflow](imgs/delivery_toolkit/image-1.png)
+4. Click **Run workflow**, specify the target service and tag, and then confirm.  
+   ![Run Workflow Example](imgs/delivery_toolkit/image-2.png)
+
+   > **Note**: The process may take a few minutes to complete.
+
+5. Verify the release under [Common Cloud Controls Releases](https://github.com/finos/common-cloud-controls/releases) and ensure it aligns with the [Release Guidelines](../../../community-guidelines/content-standards-and-practices/release-assets.md).
+
+6. Once verified, update the release title and tag by removing the `-rc` designation.
+
+   Example:
+
+   - **Title**: Release v2025.01.VPC
+   - **Tag**: v2025.01.VPC
+
+   ![Edit Release Example](imgs/delivery_toolkit/image-5.png)

docs/resources/training/lint_format_user_guide.md → docs/resources/training/user_guides/linting_and_formatting.md

@@ -72,4 +72,4 @@ Thanks for reading. At this point, you have now successfully installed and confi
 
 If you have any issues, please do not hesistate to reach out to the [Delivery WG] for more assistance.
 
-[Delivery WG]: ../../governance/working-groups/delivery/charter.md
+[Delivery WG]: ../../../governance/working-groups/delivery/charter.md