Merge branch 'main' into issue-159

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,22 +26,35 @@
 
 ## Quick Start
 
-**[Governance Model Template](GOVERNANCE-TEMPLATE.md)** ([see example](https://nasa-ammos.github.io/slim/docs/about/GOVERNANCE/))
+**[⬇️ Governance Model Template (Small Teams)](pathname:///assets/governance/governance-model/GOVERNANCE-TEMPLATE-SMALL-TEAMS.md)**
 
-Access our recommended template to start integrating a governance model into your project.
+Our recommended governance model for small teams of 1-3 active members.
+
+**[⬇️ Governance Model Template (Medium Teams)](pathname:///assets/governance/governance-model/GOVERNANCE-TEMPLATE-MEDIUM-TEAMS.md)**
+
+Our recommended governance model for small teams of 3-10 active members.
+
+**[⬇️ Governance Model Template (Large Teams)](pathname:///assets/governance/governance-model/GOVERNANCE-TEMPLATE-LARGE-TEAMS.md)**
+
+Our recommended governance model for small teams of 10+ active members.
 
 ---
 
 ## Step-by-Step Guide
 
 1. **Team Consultation**: Collaborate with your team and stakeholders to discuss adopting the governance model template. You'll want to consider topics like:
+   - Decide on how big of a team you currently estimate wanting to be
    - Roles (and how contributors can be promoted between roles)
-   - Committees (the groups that guide your project)
-2. **Customize the Template**:
-   - View and download our [Governance Model Template](GOVERNANCE-TEMPLATE.md).
+   - Committees (the groups that guide your project - if any)
+2. **Choose the Right Template**:
+   - Depending on the size of your team, choose between:
+     - [Governance Model Template (Small Teams)](pathname:///assets/governance/governance-model/GOVERNANCE-TEMPLATE-SMALL-TEAMS.md) - ideal for 1-3 active team members.
+     - [Governance Model Template (Medium Teams)](pathname:///assets/governance/governance-model/GOVERNANCE-TEMPLATE-MEDIUM-TEAMS.md) - ideal for 3-10 active team members.
+     - [Governance Model Template (Large Teams)](pathname:///assets/governance/governance-model/GOVERNANCE-TEMPLATE-LARGE-TEAMS.md) - ideal for 10+ active team members.
+3. **Customize the Template**:
    - Place the template in a `GOVERNANCE.md` file within the root folder of your repository.
    - Modify and personalize the template, replacing `[INSERT ...]` text with specifics for your project.
-3. **Implement the Governance Model**:
+4. **Implement the Governance Model**:
    - Commit the `GOVERNANCE.md` file to the `main` branch.
    - Link to the governance document in your `README.md` file under the `Contributing` section.
 
@@ -64,6 +77,10 @@ Access our recommended template to start integrating a governance model into you
 - **Q: Can the governance structure be modified as the project evolves?**
 - A: Yes, the model is flexible and can adapt to changing project needs, subject to agreement by the Project Steering Committee (PMC) and stakeholders.
 
+
+- **Q: Should I choose the right GOVERNANCE template for my current team size or intended team size?**
+- A: Governance models should evolve slowly - therefore, choose the governance model that is right for your aspirational team size and modify if needed in the future. 
+
 ---
 
 ## Credits 
@@ -85,4 +102,4 @@ This template was developed by evaluating best `GOVERNANCE.md` practices in the
 
 ## Feedback and Contributions
 
-We invite feedback and contributions to refine this guide. Visit our [contribution guidelines](https://nasa-ammos.github.io/slim/docs/contribute/contributing/).
+We invite feedback and contributions to refine this guide. Visit our [contribution guidelines](https://nasa-ammos.github.io/slim/docs/contribute/contributing/).