Merge pull request #168 from NASA-AMMOS/issue-154

SLIM-CLI support

docs/contribute/submit-best-practice.md

@@ -50,11 +50,15 @@ To make it easier for users to adopt your best practice solution, consider prese
 
 Read more about our automation philosophy in [Develop Standards & Best Practices](/slim/docs/about/#2-develop-standards--best-practices). 
 
+
 ### Adhere to Folder Structure
 
 To maintain organization and consistency within the repository, create a new folder for your best practice guide. Place this folder within the appropriate sub-folder in the `docs/guides` directory of the [NASA-AMMOS/slim](https://github.com/NASA-AMMOS/slim) repository. Ensure that the folder structure aligns with the type of best practice you are developing, allowing users to easily locate and reference your guide.
 
+Additionally, if your best practice guide includes infusible assets such as templates, code, or any other kind of automation that helps integrate your best practice into projects, you should store these assets within the `/static/assets` directory. Within this directory, create a sub-category that reflects the nature of the assets. This organization allows users to find and utilize the assets more easily, and it aligns with the repository's structure.
+
 For example, if you were to add a new best practice guide related to software-lifecycle security, you'd create a new folder called "my-security-guide" in the below directory:
+
 ```
 docs/
 ├── about
@@ -77,6 +81,18 @@ docs/
                 └── other-file.jpg
 ```
 
+And for infusible assets related to this guide, you would store them in a structure like this:
+
+```
+static/
+├── assets
+│   └── software-lifecycle
+│       └── security
+│           ├── my-security-guide-template.md
+│           ├── my-security-script.sh
+│           └── my-security-tool-config.json
+```
+
 ### Use our Standard Guide Template
 
 To maintain uniformity and ease of understanding, contributors are urged to utilize the below template when submitting their best practice guides. This structured format ensures clarity, beginning with a concise title and a one-liner description to capture the essence of the proposal. The Introduction sets the context, Prerequisites identify essential tools or knowledge, and the Step-by-Step Guide offers a methodical walkthrough, enhanced optionally with illustrative images. An FAQ section addresses potential queries, and appropriate credits acknowledge contributors and inspirations. This standard layout not only ensures that each guide retains consistency and comprehensibility, but it also facilitates smoother automation and integration within the SLIM ecosystem. 
@@ -153,26 +169,42 @@ _A brief description of what the link provides, e.g., "Click the link above to a
 We welcome feedback and contributions to help improve and grow this page. Please see our [contribution guidelines](https://nasa-ammos.github.io/slim/docs/contribute/contributing/).
 ```
 
-### Add Entry to the Registry
 
-To document metadata about your best practice and have your best practice show up in our [search page](https://nasa-ammos.github.io/slim/docs/guides/search), add a JSON entry to the file `data/slim-registry.json` within the [NASA-AMMOS/slim](https://github.com/NASA-AMMOS/slim) repository. Fill out the following fields in the example below:
-
-```json
-{
-  "title": "README.md",
-  "uri": "/docs/guides/documentation/readme",
-  "category": "documentation",
-  "description": "A template that can be used to help developers and users understand your repository's project code concisely and clearly.",
-  "tags": [
-    "documentation",
-    "repository-setup",
-    "project-template"
-  ],
-  "last-updated": "2023-04-27"
-}
-```
+### Add Entry to the Registry
 
-Customize the fields according to your best practice guide. This entry will serve as a reference for users and allow them to discover your contribution through the registry. Make sure to include relevant and accurate information to help users understand the purpose and benefits of your best practice guide.
+To document metadata about your best practice and ensure that it appears in our [search page](https://nasa-ammos.github.io/slim/docs/guides/search), you need to add a JSON entry to the `data/slim-registry.json` file within the [NASA-AMMOS/slim](https://github.com/NASA-AMMOS/slim) repository. Here's how you can do it:
+
+1. **Basic Fields**: Start by filling out the basic fields as shown in the example below. These include `title`, `uri`, `category`, `description`, `tags`, and `last-updated`.
+
+2. **Assets Metadata**: Additionally, you should include an `assets` metadata element to describe any infusible assets associated with your best practice. These could be templates, code samples, or other resources that enhance the usability of your guide. Each asset should include `name`, `type`, and `uri` to specify the asset’s details. Adding this is especially important so that infusion can be automated via the [slim-cli tool](https://github.com/nasa-ammos/slim-cli) - which queries the `data/slim-registry.json` file. 
+
+   Here’s an example of how to structure your JSON entry:
+
+   ```json
+   {
+     "title": "README.md",
+     "uri": "/docs/guides/documentation/readme",
+     "category": "documentation",
+     "description": "A template that can be used to help developers and users understand your repository's project code concisely and clearly.",
+     "tags": [
+       "documentation",
+       "repository-setup",
+       "project-template"
+     ],
+     "last-updated": "2023-04-27",
+     "assets": [
+       {
+         "name": "README Template",
+         "type": "text/md",
+         "uri": "https://raw.githubusercontent.com/NASA-AMMOS/slim/issue-154/static/assets/communication/readme/README.md"
+       }
+     ]
+   }
+   ```
+
+3. **Customization**: Tailor the fields to match the specifics of your best practice guide. Ensure that the `assets` section is comprehensive and includes all relevant resources that could help users implement your guide effectively.
+
+4. **Final Check**: Before submitting, review the JSON entry to ensure all details are accurate and that the assets are correctly linked and described.
 
 ## 4⃣️ Get Feedback For Your Contribution
 

docs/guides/documentation/change-log/README.md

@@ -8,10 +8,10 @@
 
 ## Introduction
 
-**Background**: A change log is a vital tool for documenting significant changes in software over time in a format accessible to humans. It plays a critical role in conveying the evolution of software, including additions, deprecations, and removals. This guide outlines the best practices for maintaining a `CHANGELOG.md` file, complementing release pages and enhancing software distribution transparency.
+**Background**: A change log is a vital tool for documenting significant changes in software over time in a format accessible **to humans**. It plays a critical role in conveying the evolution of software, including additions, deprecations, and removals. We feel a change log is especially good for noting feature changes, rather than focusing on developer oriented commit changes. This guide outlines the best practices for maintaining a `CHANGELOG.md` file, complementing release pages and enhancing software distribution transparency.
 
 **Use Cases**:
-- Documenting software changes for easy understanding and tracking.
+- Documenting software changes for easy understanding and tracking for a broad audience.
 - Enhancing transparency in software development and release cycles.
 - Storing the history of significant changes independent of code hosts like GitHub.com
 ---
@@ -25,7 +25,7 @@
 
 ## Quick Start
 
-**[⬇️ Keep a Changelog](https://keepachangelog.com/en/1.0.0/#how)** ([see example](https://github.com/riverma/terraformly/blob/main/CHANGELOG.md))
+**[⬇️ Keep a Changelog](pathname:///assets/communication/changelog/CHANGELOG.md)** ([see example](https://keepachangelog.com/en/1.0.0/#how))
 
 Download a template for creating a human-readable change log for your software project.
 
@@ -46,7 +46,7 @@ Download a template for creating a human-readable change log for your software p
 ## Frequently Asked Questions (FAQ)
 
 - Q: Why is a `CHANGELOG.md` crucial even if there's a GitHub auto-generated release changes page?
-- A: It ensures future-proof accessibility of change information, especially for users who may not have access to the project's release page or if the software has changed hands. Moreover, its meant to be feature-centric and designed for people to understand, rather than GitHub's commit-oriented change reports. 
+- A: We think they are complementary. Releases are great for commit-level information; but changelogs are better suited to a broader audience. It also ensures future-proof accessibility of change information, especially for users who may not have access to the project's release page or if the software has changed hands. Moreover, its meant to be feature-centric and designed for people to understand, rather than GitHub's commit-oriented change reports. 
 
 ---
 

docs/guides/documentation/readme/index.md

@@ -28,17 +28,17 @@
 
 ## Quick Start
 
-**[⬇️ README Template](README-TEMPLATE)** ([see example](https://github.com/riverma/terraformly/blob/main/README.md))
+**[⬇️ README Template](pathname:///assets/communication/readme/README.md)** ([see example](https://github.com/riverma/terraformly/blob/main/README.md))
 
 Download and fill-out our recommended README template to get started on crafting your project's introduction.
 
----
+--- 
 
 ## Step-by-Step Guide
 
-1. **Discuss with Your Team**: Ensure consensus on adopting the [README Template](README-TEMPLATE).
+1. **Discuss with Your Team**: Ensure consensus on adopting the [README Template](pathname:///assets/communication/readme/README.md).
 2. **Customize the Template**:
-   - Copy the [README Template](README-TEMPLATE) into a `README.md` file in your repository.
+   - Copy the [README Template](pathname:///assets/communication/readme/README.md) into a `README.md` file in your repository.
    - Replace `[INSERT ...]` placeholders with your project's specifics.
 3. **Integrate into Your Project**:
    - Link to the `CONTRIBUTING.md` within your `README.md` for easy access.

docs/guides/governance/contributions/contributing-guide/README.md

@@ -26,7 +26,7 @@
 
 ## Quick Start
 
-**[⬇️ Contributing Guide Template](CONTRIBUTING)** ([see example](https://github.com/riverma/terraformly/blob/main/CONTRIBUTING.md))
+**[⬇️ Contributing Guide Template](pathname:///assets/governance/contributing-guide/CONTRIBUTING.md)** ([see example](https://github.com/riverma/terraformly/blob/main/CONTRIBUTING.md))
 
 Download our customizable template to create a contributing guide for your project.
 
@@ -46,7 +46,7 @@ Download our customizable template to create a contributing guide for your proje
    - etc.
 
 
-2. **Customize the Template**: Modify the [Contributing Guide Template](CONTRIBUTING.md) to fit your project's specifics.
+2. **Customize the Template**: Modify the [Contributing Guide Template](pathname:///assets/governance/contributing-guide/CONTRIBUTING.md) to fit your project's specifics.
    - Copy the template and create a `CONTRIBUTING.md` file at the root level of your repository.
    - Replace `[INSERT ...]` placeholders with your project's details. These markers are used throughout to designate customization options.
 3. **Integrate with Project**:

docs/guides/governance/contributions/issue-templates/README.md

@@ -27,12 +27,12 @@
 ## Quick Start
 
 **Bug Reports:**
-- **[⬇️ Bug Report Template (Markdown)](bug-reports/bug_report)** ([see example](https://github.com/riverma/terraformly/issues/new?assignees=&labels=bug&projects=&template=bug_report.md&title=%5BBug%5D%3A+))
-- **[⬇️ Bug Report Template (GitHub Form)](bug-reports/bug_report.yml)** ([see example](https://github.com/riverma/terraformly/issues/new?assignees=&labels=bug&projects=&template=bug_report.yml&title=%5BBug%5D%3A+))
+- **[⬇️ Bug Report Template (Markdown)](pathname:///assets/governance/issue-templates/bug_report.md)** ([see example](https://github.com/riverma/terraformly/issues/new?assignees=&labels=bug&projects=&template=bug_report.md&title=%5BBug%5D%3A+))
+- **[⬇️ Bug Report Template (GitHub Form)](pathname:///assets/governance/issue-templates/bug_report.yml)** ([see example](https://github.com/riverma/terraformly/issues/new?assignees=&labels=bug&projects=&template=bug_report.yml&title=%5BBug%5D%3A+))
 
 **New Features:**
-- **[⬇️ New Feature Template (Markdown)](features/new_feature)** ([see example](https://github.com/riverma/terraformly/issues/new?assignees=&labels=enhancement&projects=&template=feature_request.md&title=%5BNew+Feature%5D%3A+))
-- **[⬇️ New Feature Template (GitHub Form)](features/new_feature.yml)** ([see example](https://github.com/riverma/terraformly/issues/new?assignees=&labels=enhancement&projects=&template=feature_request.yml&title=%5BNew+Feature%5D%3A+))
+- **[⬇️ New Feature Template (Markdown)](pathname:///assets/governance/issue-templates/new_feature.md)** ([see example](https://github.com/riverma/terraformly/issues/new?assignees=&labels=enhancement&projects=&template=feature_request.md&title=%5BNew+Feature%5D%3A+))
+- **[⬇️ New Feature Template (GitHub Form)](pathname:///assets/governance/issue-templates/new_feature.yml)** ([see example](https://github.com/riverma/terraformly/issues/new?assignees=&labels=enhancement&projects=&template=feature_request.yml&title=%5BNew+Feature%5D%3A+))
 
 **Resources: **
 
@@ -58,9 +58,9 @@
 
 2. **Setting Up Issue Templates**:
    - Create a `.github/ISSUE_TEMPLATE` folder in your repository.
-   - Add [Bug Report](bug-reports/bug_report) and [New Feature](features/new_feature) templates to this folder.
+   - Add [Bug Report](pathname:///assets/governance/issue-templates/bug_report.md) and [New Feature](pathname:///assets/governance/issue-templates/new_feature.md) templates to this folder.
    - For a form-like experience, use [GitHub Issue Forms](https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/configuring-issue-templates-for-your-repository#creating-issue-forms). 
-     - Place YAML formatted templates, like [Bug Report Form](bug-reports/bug_report.yml) and [New Feature Form](features/new_feature.yml), in the same folder.
+     - Place YAML formatted templates, like [Bug Report Form](pathname:///assets/governance/issue-templates/bug_report.yml) and [New Feature Form](pathname:///assets/governance/issue-templates/new_feature.yml), in the same folder.
 
 3. **Commit and Use Templates**:
    - Commit these files to the `main` branch.

docs/guides/governance/contributions/pull-requests/README.md

@@ -25,7 +25,7 @@
 
 ## Quick Start
 
-**[⬇️ Pull Request Template](PULL_REQUEST_TEMPLATE)** ([see example](https://github.com/riverma/terraformly/blob/main/.github/PULL_REQUEST_TEMPLATE))
+**[⬇️ Pull Request Template](pathname:///assets/governance/pull-requests/PULL_REQUEST_TEMPLATE.md)** ([see example](https://github.com/riverma/terraformly/blob/main/.github/PULL_REQUEST_TEMPLATE))
 
 Our recommended pull request template for projects.
 
@@ -37,7 +37,7 @@ Recommendations from GitHub.com on how-to facilitate the use of pull request tem
 
 ## Step-by-Step Guide
 
-1. **Team Discussion**: Discuss the benefits of a pull request template with your team. Gain consensus on adopting this approach for consistency in contributions. Below is an explanation of our recommended [Pull Request Template](PULL_REQUEST_TEMPLATE.md) file's fields. Adjust as necessary.
+1. **Team Discussion**: Discuss the benefits of a pull request template with your team. Gain consensus on adopting this approach for consistency in contributions. Below is an explanation of our recommended [Pull Request Template](pathname:///assets/governance/pull-requests/PULL_REQUEST_TEMPLATE.md) file's fields. Adjust as necessary.
    - ***Purpose***: To clearly state the intention behind the pull request. This helps reviewers understand the context and significance of your changes.
    - ***Proposed Changes***:
       - `[ADD]` for new features or content the contributor introduced.
@@ -51,7 +51,7 @@ Recommendations from GitHub.com on how-to facilitate the use of pull request tem
    - In your GitHub repository, create a `.github/` folder to hold community health files.
 
 3. **Add Pull Request Template**:
-   - Copy the [Pull Request Template](PULL_REQUEST_TEMPLATE.md) into `.github/PULL_REQUEST_TEMPLATE`.
+   - Copy the [Pull Request Template](pathname:///assets/governance/pull-requests/PULL_REQUEST_TEMPLATE.md) into `.github/PULL_REQUEST_TEMPLATE`.
    - Commit and push this file to the `main` branch of your repository.
 
 4. **Usage**:

docs/guides/governance/governance-model/README.md

@@ -26,7 +26,7 @@
 
 ## Quick Start
 
-**[Governance Model Template](GOVERNANCE-TEMPLATE.md)** ([see example](https://nasa-ammos.github.io/slim/docs/about/GOVERNANCE/))
+**[⬇️ Governance Model Template](pathname:///assets/governance/governance-model/GOVERNANCE-TEMPLATE.md)** ([see example](https://nasa-ammos.github.io/slim/docs/about/GOVERNANCE/))
 
 Access our recommended template to start integrating a governance model into your project.
 

docs/guides/software-lifecycle/continuous-testing/README.md

@@ -6,7 +6,7 @@ sidebar_label: Continuous Testing
 
 <!--
 import CodeBlock from '@theme/CodeBlock';
-import PreCommitConfigSource from '!!raw-loader!./.pre-commit-config.yaml';
+import PreCommitConfigSource from '!!raw-loader!/assets/software-lifecycle/continuous-testing/pre-commit-config.yaml';
 -->
 
 <pre align="center">A comprehensive guide to developing a continuous testing plan, implementation, and automation approach for your project using AI tools.</pre>
@@ -50,7 +50,9 @@ Although there are many steps in setting up a continuous testing architecture, t
 - **If you are brand new to continuous testing**: we recommend starting with our (#step-by-step) guide to set up an efficient continuous testing plan for your project. 
 Key Concepts to Get Started with:
 
-**[⬇️ Download and setup a TESTING.md Test Plan](TESTING)** (see [example](TESTING-example) of template in action)
+**[⬇️ Download and setup a TESTING.md test plan](pathname:///assets/software-lifecycle/continuous-testing/TESTING.md)** (see [example](TESTING-example) of template in action)
+
+**[⬇️ Download our .pre-commit-config.yaml](pathname:///assets/software-lifecycle/continuous-testing/pre-commit-config.yaml)** for a standard code styling, formatting and linting checker
 
 **📝 Generate unit tests automatically using a Large Language Model (LLM), such as [codellama](https://ollama.com/library/codellama) via [ollama](https://ollama.com)** (see [example](#21-unit-tests) of unit test script generation)
 
@@ -76,7 +78,7 @@ We recommend creating a `TESTING.md` file that outlines the testing objectives a
 
 Having this information in a single file helps guide your testing journey and adds clarity for your team. 
 
-**[⬇️ Download our TESTING.md Template](TESTING)** (see [example](TESTING-example) of template in action)
+**[⬇️ Download our TESTING.md Template](pathname:///assets/software-lifecycle/continuous-testing/TESTING.md)** (see [example](TESTING-example) of template in action)
 
 #### 1.1 Testing Categories
 
@@ -348,7 +350,7 @@ The quality of the generated test code can be compared with the example provided
 Our recommendation is to automate as many of your tests as possible using [pre-commit](https://pre-commit.com/), a framework that manages and maintains multi-language pre-commit hooks that can be used on the client side as well as the server (VCS) side. 
 
 #### 3.1 Static Test Automation
-We recommend setting up a static test using [`.pre-commit-config.yaml`](.pre-commit-config.yaml). 
+We recommend setting up a static test using [`.pre-commit-config.yaml`](pathname:///assets/software-lifecycle/continuous-testing/pre-commit-config.yaml). 
 
 #### 3.2 Component Test Automation
 
@@ -610,7 +612,7 @@ Your tests should be updated, at minimum, upon the following events:
 4. Periodic [code coverage](testing-frameworks) analysis identifies **underused or obsolete tests**.
 
 This is the list of items to be maintained:
-1. [TESTING.md](TESTING)
+1. [TESTING.md](pathname:///assets/software-lifecycle/continuous-testing/TESTING.md)
 2. [Component tests](#21-component-tests)
 3. [System tests](#22-system-tests)
 4. [Test automation](#3-automate-your-tests)