@@ -17,7 +17,7 @@
[](https://nasa-ammos.github.io/slim/)
-
+
This repository hosts the SLIM website, a project aimed at developing a common set of best practices in software development standards for NASA multi-mission space and ground software. The website leverages Docusaurus 2, a static website generator.
diff --git a/docs/about/README.md b/docs/about/README.md
index c896cee3c..e4d10086e 100644
--- a/docs/about/README.md
+++ b/docs/about/README.md
@@ -6,29 +6,33 @@ sidebar_position: 1
> _A shared resource for discussing, iterating and referencing best practices in software lifecycle process improvements for multi-mission space and ground software_
-[📖 View our Infographic (PDF)](https://github.com/NASA-AMMOS/slim/files/8534342/SLIM-Infographic.pdf)
+[📖 View our Infographic (PDF)](SLIM-Infographic.pdf)
Software Lifecycle Improvement & Modernization (SLIM) is a project focused on collecting, developing, and disseminating best practices and process improvement strategies in NASA multi-mission software development lifecycle ecosystems. SLIM represents both a community of contributors as well as a continually evolving repository for best practices documentation.
-## Scope
+## Our Focus
There are three key areas within the software development lifecycle improvement space that SLIM focuses on providing best practice guidance for:
-
+
-## Process
+## Our Process
+
+### Community Outreach
We reach out to community member projects, and solicit input on outstanding process improvement needs, including the respective needs' relative ranking in importance / criticality. A few needs are chosen to focus active contributor time upon - seeking to develop best practice guides, including items such as use case lists, trade-studies, reference architectures and starter kits.
-
+
+
+### Standards-as-Code
-Once prioritized needs are identified, contributors go through a series of steps to create best practice guides for the community.
+We use a technique we like to call "standards-as-code", which basically means that we develop best practices that are _patchable_ to existing or new community member project codebases or are _deployable_ to their infrastructure. Therefore, we target providing best practices in a way that is most easily can be infused into existing projects. This way, we are actually able to scale out our best practice dissemination widely to many projects at once.
-
+
More information on our development process for best practice guides can be found in our [Contributing Guide](docs/contribute/contributing/development-process).
-## Community Members
+## Our Community Members
What does it mean to be a community member of SLIM? The following ideas apply to member projects:
- Has a representative (a point-of-contact) who interfaces with the SLIM effort
@@ -40,22 +44,22 @@ The following list of projects are currently SLIM member projects:
-## Get Involved
+## How To Get Involved
SLIM best practice guides and recommendations are open source, which means you have the freedom to use our work (in accordance with our [LICENSE](https://nasa-ammos.github.io/slim/LICENSE)) as well as contribute and help shape our future work. We're excited to welcome new contributors and users.
diff --git a/docs/about/SLIM-Infographic.pdf b/docs/about/SLIM-Infographic.pdf
new file mode 100644
index 000000000..dd2d854f0
Binary files /dev/null and b/docs/about/SLIM-Infographic.pdf differ
diff --git a/docs/contribute/submit-best-practice.md b/docs/contribute/submit-best-practice.md
index 11eedb2f6..94fcd1c1e 100644
--- a/docs/contribute/submit-best-practice.md
+++ b/docs/contribute/submit-best-practice.md
@@ -2,46 +2,146 @@
## 1⃣️ Find or Make a Ticket
-To create a GitHub ticket for the repository [NASA-AMMOS/slim](https://github.com/NASA-AMMOS/slim), follow these steps:
+To create an issue for the [NASA-AMMOS/slim](https://github.com/NASA-AMMOS/slim) repository:
-1. **Navigate to the repository**: Visit the [NASA-AMMOS/slim](https://github.com/NASA-AMMOS/slim) repository on GitHub.
+1. Go to [NASA-AMMOS/slim](https://github.com/NASA-AMMOS/slim) on GitHub
+2. Click on the "Issues" tab
+3. Select "New issue" > appropriate template (e.g., "New Best Practice Guide", "Improve an Existing Best Practice Guide", or "New Process Improvement Need")
+4. Enter a concise title and fill out the template
+5. Add labels and screenshots as relevant
+6. Review and click on "Submit new issue"
+7. Engage in discussions on the ticket if needed
-2. **Go to the "Issues" tab**: Click on the "Issues" tab located near the top of the repository page.
+Follow GitHub best practices: be clear and concise.
-3. **Click on "New issue"**: On the right-hand side, click on the green "New issue" button.
+## 2⃣️ Initialize a Draft Pull Request
-4. **Choose a template**: Select the appropriate template for your ticket from the available options: "Best Practice Need" or "Website Issue." Choose the template that best fits the issue you want to report.
+To submit your solution to the [NASA-AMMOS/slim](https://github.com/NASA-AMMOS/slim) repository follow the below steps. Note: we highly recommend iterating a draft pull request rather than issuing a pull request _after_ you've already written up a guide - the SLIM community can provide much better feedback as you iterate!
-5. **Provide a title**: Enter a descriptive and concise title for your ticket that summarizes the issue.
+1. Fork [NASA-AMMOS/slim](https://github.com/NASA-AMMOS/slim)
+2. Clone your fork (`git clone https://github.com/YourUsername/slim.git`) on your local machine
+3. Create a branch (`git checkout -b your-branch-name`)
+4. Develop, iterate and commit your solution as it grows (see Step 3 below _Develop Your Contribution_)
+5. Push to your fork (`git push origin your-branch-name`)
+6. Within your fork, click the "Contribute" button, choose to submit a pull request and fill in details and reference any related issues. Consider keeping your a pull request a [draft pull request](https://github.blog/2019-02-14-introducing-draft-pull-requests/) while you iterate so the community knowns you're still working on the contribution.
+7. Address review feedback promptly and iterate as needed. Once your pull request is finalized, ensure it is no longer in "draft" mode. A SLIM collaborator and reviewer will help you finalize and get your contribution merged if possible.
+8. Keep your fork synchronized with the original repo using `git fetch upstream` and `git merge upstream/main`
-6. **Fill out the template**: Carefully fill out the sections within the chosen template. Provide as much relevant information as possible to help others understand the issue and provide appropriate assistance.
+## 3⃣️ Develop Your Contribution
-7. **Add labels (if applicable)**: Apply relevant labels to your ticket to categorize it. For example, you might use labels like "bug," "enhancement," or "help wanted" to provide further context to your issue.
-8. **Attach screenshots (if necessary)**: If visual information is relevant to your issue, attach screenshots or images that help illustrate the problem. Click on "Attach files" to add the necessary files.
+When developing your contribution to the [NASA-AMMOS/slim](https://github.com/NASA-AMMOS/slim) repository, consider the following sub-sections:
-9. **Preview and submit**: Review your ticket to ensure all information is accurate and complete. Once you are satisfied, click on "Submit new issue" to create your ticket.
+### Think about Automation
-10. **Engage with the community**: Stay engaged with the ticket by responding to any follow-up questions or discussions from other contributors. This helps to clarify details and collaborate effectively.
+To make it easier for users to adopt your best practice solution, consider presenting it as templates, software automation, or starter kits. This approach allows users to quickly implement your best practice in production. By providing automated tools or templates, you can streamline the adoption process and increase the likelihood of successful implementation.
-Remember to follow best practices when creating a GitHub ticket, such as providing clear and concise information, including relevant details, and maintaining a respectful and collaborative tone throughout the process.
+### Adhere to Folder Structure
-## 2⃣️ Develop Your Contribution
+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.
+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
+├── contribute
+└── guides
+ ├── documentation
+ ├── search.md
+ └── software-lifecycle
+ ├── application-starter-kits
+ ├── continuous-integration
+ ├── continuous-testing
+ └── security
+ ├── README.md
+ ├── dependabot
+ ├── secrets-detection
+ └── my-security-guide
+ └── README.md
+ └── other-file.txt
+ └── other-file.json
+ └── other-file.jpg
+```
-When developing your contribution to the [NASA-AMMOS/slim](https://github.com/NASA-AMMOS/slim) repository, consider the following sub-sections:
+### Use our Standard Guide Template
-### Think about Automation
+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.
-To make it easier for users to adopt your best practice solution, consider presenting it as templates, software automation, or starter kits. This approach allows users to quickly implement your best practice in production. By providing automated tools or templates, you can streamline the adoption process and increase the likelihood of successful implementation.
+Directions:
+- Create a new Markdown file for your guide (sample below) and call it `README.md`. Its advised to create a new folder for your best practice, where you can include multiple files, templates, and miscellaneous files if needed. See the above "Adere to Folder Structure" section.
+- Copy/paste the below template into the file
+- Fill in the guide with your contents
-### Adhere to Folder Structure
+```
+# _Title Goes Here_
-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.
+
+ NASA AMMOS
+ Unity SDS
+ HySDS
One sentence description of your best practice solution.+ +## Introduction + +**Background**: _A longer description of the problem you aim to solve and your solution. Talk about the background of why this is needed, what kind of benefits the user might enjoy, and any other background information that may be useful for the reader. Additionally, talk about the expected outcome the user can expect in implementing your solution._ + +**Use Cases**: +- _A list of the types of use cases where your process improvement solution will shine_ +- _e.g. Making code repository README's consistent for internal and external contributors_ + +--- + +## Prerequisites +_List any software, hardware, or skills required to utilize the solution._ + +* Prerequisite 1 +* Prerequisite 2 +* ... + +--- + +## Quick Start +**[Link to Process Improvement Solution (template/code sample/tool/etc.)](#)** + +_A brief description of what the link provides, e.g., "Click the link above to access the full template for the README.md file."_ + +--- + +## Step-by-Step Guide + +1. **Step 1**: _Brief description of the step._ + + +2. **Step 2**: _Brief description of the step._ + + +3. ... + +--- + +## Frequently Asked Questions (FAQ) + +- Q: Example question relevant to this guide +- A: Example answer to the question + +--- + +## Credits + +**Authorship**: +- _List of contributing authors of this write-up who actually wrote words. Link to GitHub profiles if available, e.g. [Bugs Bunny](https://www.github.com/bbuny573429)_ + +**Acknowledgements**: +* Source/Organization 1 that inspired the solution or was adapted from +* Source/Organization 2 that inspired the solution or was adapted from +* ... + +--- + +## Feedback and Contributions + +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, 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: +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 { @@ -59,25 +159,3 @@ To document metadata about your best practice, add a JSON entry to the file `dat ``` 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. - -## 3⃣️ Make a Pull Request - -To contribute your solution to the [NASA-AMMOS/slim](https://github.com/NASA-AMMOS/slim) repository, follow these best practices for creating a pull request: - -1. **Fork the repository**: Start by forking the [NASA-AMMOS/slim](https://github.com/NASA-AMMOS/slim) repository to your GitHub account. This creates a copy of the repository under your control. - -2. **Clone the repository**: Clone your forked repository to your local development environment using the Git command `git clone https://github.com/YourUsername/slim.git`. Replace `YourUsername` with your actual GitHub username. - -3. **Create a new branch**: Before making any changes, create a new branch for your contribution using a descriptive and meaningful name. This helps in organizing and tracking your changes. Use the Git command `git checkout -b your-branch-name`. - -4. **Develop your solution**: Implement your best practice solution, following the guidelines and best practices discussed earlier. Make sure to commit your changes regularly and provide clear commit messages that describe the purpose of each commit. - -5. **Push changes to your fork**: Once you have completed your solution, push the changes to your forked repository using the Git command `git push origin your-branch-name`. - -6. **Submit a pull request**: Go to the original [NASA-AMMOS/slim](https://github.com/NASA-AMMOS/slim) repository on GitHub. Click on the "Pull requests" tab and then click on the green "New pull request" button. Select your branch and provide a descriptive title and detailed description of your contribution. Be sure to reference any related issues, if applicable. - -7. **Review and address feedback**: After submitting your pull request, the repository maintainers and other contributors may review your changes and provide feedback. Be responsive to their comments and address any requested changes or improvements promptly. Engaging in constructive discussions can help improve the quality of your contribution. - -8. **Keep your fork up to date**: While your pull request is under review, keep your forked repository up to date with the original repository. This ensures that your changes remain compatible with the latest updates in the main repository. Use the Git commands `git fetch upstream` and `git merge upstream/main` to update your local repository and then push the changes to your fork. - -Following these best practices helps maintain a collaborative and efficient contribution process. By adhering to these guidelines, you increase the likelihood of having your pull request accepted and integrated into the main repository. \ No newline at end of file diff --git a/docs/guides/documentation/_category_.json b/docs/guides/documentation/_category_.json index e3a294f99..36f5bf161 100644 --- a/docs/guides/documentation/_category_.json +++ b/docs/guides/documentation/_category_.json @@ -3,6 +3,6 @@ "position": 3, "link": { "type": "generated-index", - "description": "Documentation Best Practices." + "description": "Check out our below list of guides and sub-sections related to documentation best practices." } } diff --git a/docs/guides/documentation/change-log/README.md b/docs/guides/documentation/change-log/README.md index e377bbe0d..b81c38489 100644 --- a/docs/guides/documentation/change-log/README.md +++ b/docs/guides/documentation/change-log/README.md @@ -1,21 +1,61 @@ # Change Log -A change log provides a *human readable* list of significant changes, additions, deprecations, removals for software over time. It is meant to be able to be read by *people*. Change logs should be documented within a file called `CHANGELOG.md` and be updated per key release. See [semantic release](https://semver.org) for guidance on releasing cycles and versioning of your software. +
A guide for setting up a log to document software changes in a human-centric format.-⚠️ A `CHANGELOG.md` can replicate wording from a releases page (e.g. GitHub Releases), but should not be left out *in place of* a releases page. Down-stream inheritors of your software may not have access to your releases page, and will expect a `CHANGELOG.md` to be present as part of your software distribution. +## Introduction -## Keep a Changelog +**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. -This change log standard seeks to provide a template for *human readable* change logs, among other key guidance on the change logging process. +**Use Cases**: +- Documenting software changes for easy understanding and tracking. +- Enhancing transparency in software development and release cycles. +- Storing the history of significant changes independent of code hosts like GitHub.com +--- -Starter Kit: -- [Guidance](https://keepachangelog.com/en/1.0.0/#how) -- [Demo 1](https://github.com/riverma/terraformly/blob/main/CHANGELOG.md) -- [Demo 2](https://github.com/olivierlacan/keep-a-changelog/blob/main/CHANGELOG.md) -- [Webpage](https://keepachangelog.com/en/1.0.0/) +## Prerequisites -To leverage this template, make sure to do the following: -1. Talk with your team about leveraging this template, and seek wide agreement before you adopt -2. Copy the demo `CHANGELOG.md` above, and place in a file within your repository called `CHANGELOG.md` -3. Edit the `CHANGELOG.md` file with your specific release information. If you have many historic releases prior to the creation of this file, mark the latest release as the first entry, and commit to updating this for future releases as the happen. -4. Add an entry to your `README.md` under the `Changelog` section to point to your `CHANGELOG.md` file. \ No newline at end of file +* Familiarity with semantic versioning and release cycles. +* Basic knowledge of Markdown formatting. + +--- + +## Quick Start + +**[⬇️ Keep a Changelog](https://keepachangelog.com/en/1.0.0/#how)** + +Download a template for creating a human-readable change log for your software project. + +--- + +## Step-by-Step Guide + +1. **Team Agreement**: Discuss the importance of a change log with your team, emphasizing its value for transparency and communication. +2. **Creating the Change Log**: + - Start a `CHANGELOG.md` in your repository. + - See demo use of the templates like [Demo 1](https://github.com/riverma/terraformly/blob/main/CHANGELOG.md) or [Demo 2](https://github.com/olivierlacan/keep-a-changelog/blob/main/CHANGELOG.md) as a base. + - Customize the file with your project's release information. +3. **Integrating with Project Documentation**: + - Link to the `CHANGELOG.md` from your project’s `README.md` to enhance visibility. + +--- + +## 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. + +--- + +## Credits + +**Authorship**: +- [Rishi Verma](https://github.com/riverma) + +**Acknowledgements**: +* This guide draws from the ["Keep a Changelog"](https://keepachangelog.com) standard and examples from various open source projects. + +--- + +## Feedback and Contributions + +Feedback and contributions are encouraged to refine this guide. See our [contribution guidelines](https://nasa-ammos.github.io/slim/docs/contribute/contributing/). diff --git a/docs/guides/documentation/documentation-hosts/README.md b/docs/guides/documentation/documentation-hosts/README.md index a1e0c53bd..398705a24 100644 --- a/docs/guides/documentation/documentation-hosts/README.md +++ b/docs/guides/documentation/documentation-hosts/README.md @@ -1,11 +1,59 @@ -# Documentation Hosts +# Documentation Hosting -## Use Cases +
Guidance on selecting and implementing documentation hosting tools.-See the possible use cases and mapping to recommended tools for hosting different types of documentation. Feel free to propose changes by submitting a pull request for the Markdown file on our GitHub. See [contribution guide](docs/about/README.md#for-adding-improvements-to-an-existing-best-practice-guide) for details. +## Introduction -- [Use Cases](use-cases) +**Background**: Choosing the right platform for hosting various types of documentation is crucial for project success. This guide explores use cases for different documentation types and recommends tools for hosting user, developer, admin, API docs, and more, aiding in informed decision-making for documentation management. -## Trade Studies +**Use Cases**: +- Hosting user, admin, developer, and API documentation. +- Selecting appropriate platforms for different documentation needs. +- Ensuring accessible and maintainable documentation for a variety of audiences. -- [Trade Study: User/Dev/Admin/API Doc Hosting Frameworks](trade-study-hostingdocs-user) \ No newline at end of file +--- + +## Prerequisites + +* Understanding of different types of documentation and their requirements. +* Familiarity with various documentation hosting platforms and frameworks. + +--- + +## Quick Start + +**[📔 Documentation Use Cases and Hosting Tools](use-cases)** + +See various use cases and then select corresponding tools for hosting different types of documentation. + +**[📔 Trade Study on Hosting Frameworks](trade-study-hostingdocs-user)** + +View a trade-study of documentation hosting tools that we recommend. + +--- + +## Step-by-Step Guide + +1. **Identify Documentation Needs**: Assess your project's documentation requirements based on use cases. For use case mapping, consult our [Documentation Use Cases and Hosting Tools](use-cases) document. +2. **Choose Appropriate Tools**: Refer to the [Trade Study on Hosting Frameworks](trade-study-hostingdocs-user) to select the right tools for your documentation type based on features. +3. **Implement and Maintain**: Set up your chosen documentation platforms and ensure they are regularly updated and maintained. + +--- + +## Frequently Asked Questions (FAQ) + +- Q: How do I choose the right platform for hosting my project's documentation? +- A: Consider the type of documentation (user, admin, developer, API), the audience, and the specific features offered by the hosting platforms. + +--- + +## Credits + +**Authorship**: +- [Rishi Verma](https://github.com/riverma) + +--- + +## Feedback and Contributions + +Feedback and contributions are welcome to enhance this guide. Visit our [contribution guidelines](https://nasa-ammos.github.io/slim/docs/contribute/contributing/). diff --git a/docs/guides/documentation/documentation-hosts/trade-study-hostingdocs-user.md b/docs/guides/documentation/documentation-hosts/trade-study-hostingdocs-user.md index 03f12ca4f..13d630a2e 100644 --- a/docs/guides/documentation/documentation-hosts/trade-study-hostingdocs-user.md +++ b/docs/guides/documentation/documentation-hosts/trade-study-hostingdocs-user.md @@ -3,14 +3,11 @@ title: Docs Hosting Trade Study sidebar_label: Docs Hosting Trade Study --- -| Tool Name | Licensing | Render Time | VCS Stored Content | Self-Hosting | Managed Hosting | API Actions | Generate API Docs | WYSIWYG Editing | Markdown Support | Embedded Content | Hierarchial Structure | Templating Support | Roles | Comment Support | Search | Import From Other Formats | Export Other Formats | Anchor Links | Draft Content | Version Control | Internationalization | File Uploads | Diagram Editing | Usage Analytics | Extension Support | -| ----------------------------------------------- | ----------------------------------------------------------------------------------------------------- | ----------- | ----------------------------------------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------- | --------------- | ------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------- | ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- | ------------------------------------------------------------------------------- | -------------------------------------------------------------- | -------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- | -------------------------------------------------------- | ------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ | -| [GitBook](https://www.gitbook.com) | [Free for OSS](https://www.gitbook.com/pricing) / $$$ | Fast | [Yes](https://docs.gitbook.com/integrations/git-sync) | No | [Yes](https://docs.gitbook.com/hosting/custom-domains) | [Yes](https://developer.gitbook.com) | [Yes](https://docs.gitbook.com/features/openapi) | Yes | [Yes](https://docs.gitbook.com/editing-content/markdown) | [Yes](https://docs.gitbook.com/editing-content/embeds) | [Yes](https://docs.gitbook.com/editing-content/content-structure) | [Yes](https://docs.gitbook.com/getting-started/start-exploring#starter-templates) | [Yes](https://docs.gitbook.com/collaboration/team-management) | [Yes](https://docs.gitbook.com/collaboration/comments) | [Yes](https://docs.gitbook.com/features/multiple-space-search) | [Yes](https://docs.gitbook.com/features/import) | [Yes](https://docs.gitbook.com/features/pdf-export) | [Yes](https://docs.gitbook.com/features/shareable-links) | [Yes](https://docs.gitbook.com/collaboration/team-management/setting-up-permissions) | Yes | [Yes](https://docs.gitbook.com/features/internationalization) | [Yes](https://docs.gitbook.com/features/files) | No | [Yes](https://docs.gitbook.com/features/insights#data-sampling) | No | -| [Confluence](https://confluence.atlassian.com/) | [Free for OSS](https://www.atlassian.com/software/views/open-source-license-request) / $$ | | No | No | Yes | [Yes](https://developer.atlassian.com/server/confluence/confluence-server-rest-api/) | No (only non-free plugins) | Yes | [Partial](https://confluence.atlassian.com/doc/confluence-wiki-markup-251003035.html) (for embedded content) | Yes | Yes | [Yes](https://confluence.atlassian.com/doc/create-a-template-296093779.html) | Yes | Yes | Yes | [Yes](https://confluence.atlassian.com/doc/import-content-into-confluence-191141.html) | [Yes](https://confluence.atlassian.com/doc/export-content-to-word-pdf-html-and-xml-139475.html) | Yes | Yes | Yes | [No](https://confluence.atlassian.com/confeval/confluence-evaluator-resources/confluence-managing-content-in-multiple-language-translations) | Yes | No (only non-free plugins) | No (non-free plans only) | [Yes](https://developer.atlassian.com/server/confluence/writing-confluence-plugins/) | -| [ReadTheDocs](https://readthedocs.org) | [Free (with ads)](https://docs.readthedocs.io/en/stable/advertising/advertising-details.html) | | Yes | No | Yes | [Yes](https://docs.readthedocs.io/en/stable/api/) | [No](https://docs.readthedocs.io/en/stable/gsoc.html#integration-with-openapi-swagger) | No | Yes | [Yes](https://docutils.sourceforge.io/docs/ref/rst/directives.html#raw-data-pass-through) | Yes | [Yes](https://www.sphinx-doc.org/en/master/templating.html) | Yes | [No](https://docs.readthedocs.io/en/stable/faq.html#i-want-comments-in-my-docs) | Yes | [Limited](https://docs.readthedocs.io/en/stable/intro/import-guide.html) | [Yes](https://www.sphinx-doc.org/en/master/man/sphinx-build.html) | Yes | No | Yes [including doc packages](https://docs.readthedocs.io/en/stable/versions.html) | [Yes](https://www.sphinx-doc.org/en/master/usage/advanced/intl.html) | No (embed/link only) | Yes [(with plugins)](https://chiplicity.readthedocs.io/en/latest/Using_Sphinx/UsingGraphicsAndDiagramsInSphinx.html#id15) | [Yes](https://docs.readthedocs.io/en/stable/analytics.html) | [Yes](https://www.sphinx-doc.org/en/master/extdev/index.html) | -| [RETYPE](https://github.com/retypeapp/retype) | [Freemium (with limits)](https://github.com/retypeapp/retype/discussions/62#discussioncomment-971938) | | Yes | Yes | No [(satic hosts only)](https://retype.com/hosting/github-pages/) | No | [No](https://github.com/retypeapp/retype/issues/229) | No | Yes | [Yes](https://retype.com/components/embed/) | Yes | No | No | No | Yes | No | No | Yes | No | Yes | [No](https://github.com/retypeapp/retype/issues/24) | No (embed/link only) | [Yes](https://retype.com/components/mermaid/) | No (third-party only) | No | -| [mdBook](https://rust-lang.github.io/mdBook/) | [Free (Mozilla Public License 2.0)](https://github.com/rust-lang/mdBook/blob/master/LICENSE) | | Yes | Yes | No [(static hosts only)](https://rust-lang.github.io/mdBook/continuous-integration.html?highlight=deploy#deploying) | No | No | No | Yes | No | Yes | [Yes](https://rust-lang.github.io/mdBook/format/theme/index-hbs.html?highlight=template#indexhbs) | No | No | Yes | No | [No](https://github.com/rust-lang/mdBook/issues/88) | Yes | No | Yes | [No](https://github.com/rust-lang/mdBook/issues/5) | [No](https://rust-lang.github.io/mdBook/format/mdbook.html?highlight=file#including-files) (embed/link only) | [Partial](https://github.com/badboy/mdbook-mermaid) (as a preprocessor) | No (third-party only) | [Yes](https://rust-lang.github.io/mdBook/for_developers/preprocessors.html?highlight=preproce#hooking-into-mdbook) | -| docusaurus (TBD) | | | | | | | | | | | | | | | | | | | | | | | | | | -| MkDocs (TBD) | | | | | | | | | | | | | | | | | | | | | | | | | | -| daux (TBD) | | | | | | | | | | | | | | | | | | | | | | | | | | -| docsify (TBD) | | | | | | | | | | | | | | | | | | | | | | | | | | \ No newline at end of file +| Tool Name | Licensing | Render Time | VCS Stored Content | Self-Hosting | Managed Hosting | API Actions | Generate API Docs | WYSIWYG Editing | Markdown Support | Embedded Content | Hierarchial Structure | Templating Support | Roles | Comment Support | Search | Import From Other Formats | Export Other Formats | Anchor Links | Draft Content | Version Control | Internationalization | File Uploads | Diagram Editing | Usage Analytics | Extension Support | +| ----------------------------------------------- | --------------------------------------------------------------------------------------------- | ----------- | ----------------------------------------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------- | ------------------- | ------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------- | ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- | ------------------------------------------------------------------------------- | -------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- | -------------------------------------------------------- | ------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------ | +| [GitBook](https://www.gitbook.com) | [Free for OSS](https://www.gitbook.com/pricing) / $$$ | Fast | [Yes](https://docs.gitbook.com/integrations/git-sync) | No | [Yes](https://docs.gitbook.com/hosting/custom-domains) | [Yes](https://developer.gitbook.com) | [Yes](https://docs.gitbook.com/features/openapi) | Yes | [Yes](https://docs.gitbook.com/editing-content/markdown) | [Yes](https://docs.gitbook.com/editing-content/embeds) | [Yes](https://docs.gitbook.com/editing-content/content-structure) | [Yes](https://docs.gitbook.com/getting-started/start-exploring#starter-templates) | [Yes](https://docs.gitbook.com/collaboration/team-management) | [Yes](https://docs.gitbook.com/collaboration/comments) | [Yes](https://docs.gitbook.com/features/multiple-space-search) | [Yes](https://docs.gitbook.com/features/import) | [Yes](https://docs.gitbook.com/features/pdf-export) | [Yes](https://docs.gitbook.com/features/shareable-links) | [Yes](https://docs.gitbook.com/collaboration/team-management/setting-up-permissions) | Yes | [Yes](https://docs.gitbook.com/features/internationalization) | [Yes](https://docs.gitbook.com/features/files) | No | [Yes](https://docs.gitbook.com/features/insights#data-sampling) | No | +| [Confluence](https://confluence.atlassian.com/) | [Free for OSS](https://www.atlassian.com/software/views/open-source-license-request) / $$ | Slow | No | No | Yes | [Yes](https://developer.atlassian.com/server/confluence/confluence-server-rest-api/) | No (only non-free plugins) | Yes | [Partial](https://confluence.atlassian.com/doc/confluence-wiki-markup-251003035.html) (for embedded content) | Yes | Yes | [Yes](https://confluence.atlassian.com/doc/create-a-template-296093779.html) | Yes | Yes | Yes | [Yes](https://confluence.atlassian.com/doc/import-content-into-confluence-191141.html) | [Yes](https://confluence.atlassian.com/doc/export-content-to-word-pdf-html-and-xml-139475.html) | Yes | Yes | Yes | [No](https://confluence.atlassian.com/confeval/confluence-evaluator-resources/confluence-managing-content-in-multiple-language-translations) | Yes | No (only non-free plugins) | No (non-free plans only) | [Yes](https://developer.atlassian.com/server/confluence/writing-confluence-plugins/) | +| [ReadTheDocs](https://readthedocs.org) | [Free (with ads)](https://docs.readthedocs.io/en/stable/advertising/advertising-details.html) | Slow | Yes | No | Yes | [Yes](https://docs.readthedocs.io/en/stable/api/) | [No](https://docs.readthedocs.io/en/stable/gsoc.html#integration-with-openapi-swagger) | No | Yes | [Yes](https://docutils.sourceforge.io/docs/ref/rst/directives.html#raw-data-pass-through) | Yes | [Yes](https://www.sphinx-doc.org/en/master/templating.html) | Yes | [No](https://docs.readthedocs.io/en/stable/faq.html#i-want-comments-in-my-docs) | Yes | [Limited](https://docs.readthedocs.io/en/stable/intro/import-guide.html) | [Yes](https://www.sphinx-doc.org/en/master/man/sphinx-build.html) | Yes | No | Yes [including doc packages](https://docs.readthedocs.io/en/stable/versions.html) | [Yes](https://www.sphinx-doc.org/en/master/usage/advanced/intl.html) | No (embed/links only) | Yes [(with plugins)](https://chiplicity.readthedocs.io/en/latest/Using_Sphinx/UsingGraphicsAndDiagramsInSphinx.html#id15) | [Yes](https://docs.readthedocs.io/en/stable/analytics.html) | [Yes](https://www.sphinx-doc.org/en/master/extdev/index.html) | +| [mdBook](https://rust-lang.github.io/mdBook/) | [Free (Mozilla Public License 2.0)](https://github.com/rust-lang/mdBook/blob/master/LICENSE) | Fast | Yes | Yes | No [(static hosts only)](https://rust-lang.github.io/mdBook/continuous-integration.html?highlight=deploy#deploying) | No | No | No | Yes | No | Yes | [Yes](https://rust-lang.github.io/mdBook/format/theme/index-hbs.html?highlight=template#indexhbs) | No | No | Yes | No | No | Yes | No | Yes | [No](https://github.com/rust-lang/mdBook/issues/5) | No (embed/links only) | [Yes](https://github.com/badboy/mdbook-mermaid) (as a preprocessor) | No (third-party only) | [Yes](https://rust-lang.github.io/mdBook/for_developers/preprocessors.html?highlight=preproce#hooking-into-mdbook) | +| [Docusaurus](https://docusaurus.io/) | [Free MIT License](https://github.com/facebook/docusaurus/blob/main/LICENSE) | Fast | Yes | Yes | Yes (with static site hosts like Vercel, Netlify) | No | [Yes (with plugins)](https://docusaurus.io/docs/api-docs) | No | [Yes](https://docusaurus.io/docs/markdown-features) | [Yes](https://docusaurus.io/docs/markdown-features/react) | [Yes](https://docusaurus.io/docs/sidebar) | [Yes](https://docusaurus.io/docs/using-themes) | No | No | [Yes](https://docusaurus.io/docs/search) | No | No (but can be done with external tools) | Yes | No | No | [Yes](https://docusaurus.io/docs/i18n/introduction) | No (embed/links only) | [Yes (with plugins)](https://docusaurus.io/blog/releases/2.2#mermaid-diagrams) | [No](https://docusaurus.io/docs/analytics) (third-party only) | Yes | +| [Docsify](https://docsify.js.org/) | [Free MIT License](https://github.com/docsifyjs/docsify/blob/develop/LICENSE) | Fast | Yes | Yes | Yes (with static site hosts like GitHub Pages, Netlify) | No | No | No (Markdown-based) | [Yes](https://docsify.js.org/#/quickstart) | [Yes](https://docsify.js.org/#/embed-files) | [Yes](https://docsify.js.org/#/more-pages) | No | No | No | [Yes (with plugins)](https://docsify.js.org/#/plugins?id=full-text-search) | No | No | Yes | No | No | No | No (embed/links only) | [Partial (with plugins)](https://docsify.js.org/#/plugins?id=diagrams) | [No](https://docsify.js.org/#/awesome?id=analytics-plugins) (third-party only) | [Yes](https://docsify.js.org/#/plugins) | \ No newline at end of file diff --git a/docs/guides/documentation/readme/README-TEMPLATE.md b/docs/guides/documentation/readme/README-TEMPLATE.md index 1388246fe..7b46679be 100644 --- a/docs/guides/documentation/readme/README-TEMPLATE.md +++ b/docs/guides/documentation/readme/README-TEMPLATE.md @@ -1,3 +1,8 @@ +--- +title: README Template +sidebar_label: README Template +--- + ```markdown
diff --git a/docs/guides/documentation/readme/index.md b/docs/guides/documentation/readme/index.md index cb369542e..e0a675b16 100644 --- a/docs/guides/documentation/readme/index.md +++ b/docs/guides/documentation/readme/index.md @@ -1,23 +1,63 @@ -# README Template +# READMEs -A `README.md` template that can be used to help developers and users understand your repository concisely and clearly. +
A guide to constructing an effective and impressive README for your project.-## Directions +## Introduction -This template is meant for general software projects `README.md` files, including both interpreted as well as compiled language code. +**Background**: A well-crafted `README.md` is essential for introducing your software repository. It serves as the first point of contact for developers and users, providing a concise and clear overview. This guide offers a template suitable for various software projects, aiding in the creation of effective README files. -Starter Kit: -- [Markdown](./README-TEMPLATE.md) of template -- [Demo](https://github.com/riverma/terraformly/blob/main/README.md) of template +**Use Cases**: +- Creating an informative and welcoming introduction to your software project. +- Standardizing README content across various types of software repositories. +- Enhancing project understanding for contributors and users. +- Answering questions in a FAQ setting +- Guiding readers on licensing and who to contact for support -To leverage this template, make sure to do the following: -1. Talk with your team about leveraging this template, and seek wide agreement before you adopt -2. Copy the template text, and place in a file within your repository called `README.md` -3. Search and replace the `[INSERT ...` text within the file with specifics for your project -4. Add a link to the `CONTRIBUTING.md` to your `README.md` file within the `Contributing` section +--- -This starter kit template was developed by evaluating best `README.md` practices in the following organizations: -- NASA-AMMOS -- ReactJS -- VueJS -- Apache Kafka \ No newline at end of file +## Prerequisites + +* Basic knowledge of Markdown formatting. +* Understanding of your project's key features and usage. + +--- + +## Quick Start + +**[⬇️ README Template](README-TEMPLATE)** + +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). +2. **Customize the Template**: + - Copy the [README Template](README-TEMPLATE) 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. + +--- + +## Frequently Asked Questions (FAQ) + +- Q: What makes a README file effective? +- A: Clarity, completeness, and relevance of information regarding the project's purpose, usage, and contribution process. + +--- + +## Credits + +**Authorship**: +- [Rishi Verma](https://github.com/riverma) + +**Acknowledgements**: +* Inspired by README best practices from NASA-AMMOS, ReactJS, VueJS, and Apache Kafka. + +--- + +## Feedback and Contributions + +We welcome feedback and improvements to this template. See our [contribution guidelines](https://nasa-ammos.github.io/slim/docs/contribute/contributing/). diff --git a/docs/guides/governance/_category_.json b/docs/guides/governance/_category_.json index f1c2dbf54..ca74086d7 100644 --- a/docs/guides/governance/_category_.json +++ b/docs/guides/governance/_category_.json @@ -3,6 +3,6 @@ "position": 2, "link": { "type": "generated-index", - "description": "Governance Best Practices." + "description": "Check out our below list of guides and sub-sections related to governance best practices." } } diff --git a/docs/guides/governance/contributions/README.md b/docs/guides/governance/contributions/README.md deleted file mode 100644 index fa1c3b59e..000000000 --- a/docs/guides/governance/contributions/README.md +++ /dev/null @@ -1 +0,0 @@ -# Contributions \ No newline at end of file diff --git a/docs/guides/governance/contributions/_category_.json b/docs/guides/governance/contributions/_category_.json new file mode 100644 index 000000000..10e785fc2 --- /dev/null +++ b/docs/guides/governance/contributions/_category_.json @@ -0,0 +1,8 @@ +{ + "label": "Contributions", + "position": 1, + "link": { + "type": "generated-index", + "description": "Contributing Best Practices." + } +} diff --git a/docs/guides/governance/contributions/change-request-templates/README.md b/docs/guides/governance/contributions/change-request-templates/README.md deleted file mode 100644 index bc256b053..000000000 --- a/docs/guides/governance/contributions/change-request-templates/README.md +++ /dev/null @@ -1,18 +0,0 @@ -# Change Request Templates - -Pull requests are the currency for how contributions are made to projects. Having a pre-filled out pull request template offers guidance to your potential developers on how to contribute to your project. - -## GitHub Pull Request Template (General) - -GitHub provides a mechanism to automatically display a template whenever a potential contributor proposes a pull request to your repository. Please see the [documentation](https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/creating-a-pull-request-template-for-your-repository) on GitHub for details. - -Starter Kits: -- [Pull Request Template](github/PULL_REQUEST_TEMPLATE.md) - -To leverage this template, make sure to do the following: -1. Talk with your team about leveraging this template, and seek wide agreement before you adopt -2. Create a new folder within your GitHub repository with the following path: `.github/` -3. Copy the Pull Request Template template file above into the following path: - 1. `.github/PULL_REQUEST_TEMPLATE.md` -4. Commit the above file to the `main` branch -5. Whenever you propose a new pull request, your new templates should appear in the text box \ No newline at end of file diff --git a/docs/guides/governance/contributions/code-of-conduct/README.md b/docs/guides/governance/contributions/code-of-conduct/README.md index 238574b29..2cf08429e 100644 --- a/docs/guides/governance/contributions/code-of-conduct/README.md +++ b/docs/guides/governance/contributions/code-of-conduct/README.md @@ -1,21 +1,76 @@ # Code of Conduct -The code of conduct is typically a document that provides guidance to a project team on *how* the team members should interact with each other. It identifies behaviors that are helpful for building a better development community, provides contact information for addressing grievances (should they arise), and finally lists key responses that team leadership should / will take for dealing with unexpected behavior. Below are some examples to expedite the incorporation of a code of conduct. +
A walkthrough on setting up a code-of-conduct policy for your project.-## Directions +## Introduction -We recommend a community-developed code of conduct called the Contributor Covenant, that has been [adopted by many open source projects](https://www.contributor-covenant.org/adopters/). It provides a fairly standard code of conduct that (1) explicitly identifies problematic behavior that's deemed unacceptable in team interactions, (2) who to contact if problematic behavior is identified, and (3) tiers of how team leadership can respond. +**Background**: A Code of Conduct is important in setting the standards for interaction within a project team. It promotes a positive community environment, addressing unacceptable behaviors and providing mechanisms for conflict resolution. In this guide, we'll help you bootstrap your project with a recommended a Code of Conduct, notably the Contributor Covenant, which is widely recognized and adopted in open-source communities. -Starter Kit: -- [Markdown](https://www.contributor-covenant.org/version/2/1/code_of_conduct/code_of_conduct.md) of template -- [Demo](https://github.com/riverma/terraformly/blob/main/CODE_OF_CONDUCT.md) of template and [demo](https://github.com/riverma/terraformly) of badge -- [Webpage](https://www.contributor-covenant.org) for more information +**Use Cases**: +- Establishing a respectful and inclusive team culture. +- Providing clear guidelines on acceptable behaviors and handling grievances. -To leverage this template, make sure to do the following: -1. Talk with your team about leveraging this template, and seek wide agreement before you adopt -2. Copy the template text, and place in a file within your repository called `CODE_OF_CONDUCT.md` -3. Search and replace the `[INSERT CONTACT METHOD]` text within the file with a person, private e-mail list, or other form of contact for grievances to be addressed to -4. Add the contributor covenant badge () to your `README.md` file (example below) -``` -[](code_of_conduct.md) -``` \ No newline at end of file +--- + +## Prerequisites + +* Understanding of community management and team dynamics. +* Familiarity with Markdown for editing documentation. + +--- + +## Quick Start + +**[⬇️ Contributor Covenant Template](https://www.contributor-covenant.org/version/2/1/code_of_conduct/code_of_conduct.md)** + +Access the standard Contributor Covenant template for a robust Code of Conduct policy to use in your project. + +--- + +## Step-by-Step Guide + +1. **Team Consultation**: Discuss the adoption of the Contributor Covenant with your team, ensuring consensus. +2. **Setting Up the Document**: + - Create a `CODE_OF_CONDUCT.md` file in your repository. + - Copy the Contributor Covenant template into this file. + - Replace `[INSERT CONTACT METHOD]` with appropriate contact details for reporting issues. +3. **Integrate into Your Project**: + - Add the Contributor Covenant badge () to your `README.md` for visibility and easy access. + ``` + [](CODE_OF_CONDUCT.md) + ``` + +--- + +## Frequently Asked Questions (FAQ) + +- Q: Why is a Code of Conduct important for projects? +- A: It establishes a standard for behavior, promoting a safe and inclusive environment for collaboration. + + +- Q: Can I customize the Contributor Convenant Code of Conduct template? +- A: Yes! Especially if your project is managed in a unique way. + + +- Q: What should be done if a team member violates the Code of Conduct? +- A: Violations should be reported to the designated contact person or team. The matter should be handled confidentially and in accordance with the guidelines set forth in the Code of Conduct. + + +- Q: How often should the Code of Conduct be reviewed or updated? +- A: Regularly reviewing and updating the Code of Conduct ensures it stays relevant and effective. It's advisable to reassess it annually or when significant changes occur within the project or community. + +--- + +## Credits + +**Authorship**: +- [Rishi Verma](https://github.com/riverma) + +**Acknowledgements**: +* Inspired by the [Contributor Covenant](https://www.contributor-covenant.org). + +--- + +## Feedback and Contributions + +Your feedback and contributions are welcome to enhance this guide. See our [contribution guidelines](https://nasa-ammos.github.io/slim/docs/contribute/contributing/). diff --git a/docs/guides/governance/contributions/contributing-guide/CONTRIBUTING.md b/docs/guides/governance/contributions/contributing-guide/CONTRIBUTING.md index 4fba8057f..8cda033d6 100644 --- a/docs/guides/governance/contributions/contributing-guide/CONTRIBUTING.md +++ b/docs/guides/governance/contributions/contributing-guide/CONTRIBUTING.md @@ -7,20 +7,6 @@ Thanks for taking the time to consider contributing! We very much appreciate you Before you begin contributing to our project, it'll be a good idea to ensure you've satisfied the below pre-requisites. -### Developer Certificate of Origin (DCO) - -To accept your contributions for any kind of patch, you'll want to: -1. Understand what a Developer Certificate of Origin is. See [this](https://wiki.linuxfoundation.org/dco) guide. -2. Read and agree to the [terms](https://developercertificate.org) of the Developer Certificate of Origin. -3. Remember to add your Sign-Off for each patch contribution you submit to our project via either: - 1. By using the `-s` flag if using Git. See [these](https://git-scm.com/docs/git-commit#Documentation/git-commit.txt--s) instructions. - 2. By including the following text in your patch contributions (i.e. pull requests) - ``` - Signed-off-by: Full Name
Fast track developing a contribution guide for your new contributors.-We provide a sample contribution guide template below, but please keep in mind to: -- Modify and adapt to your project as needed. You may not need all features of the template guide. -- Replace all instances of `[INSERT ...]` within the template with your project's specific environment. +## Introduction -## Contributing Guide Template +**Background**: A well-defined contribution guide is crucial for open-source projects. It helps new contributors understand the expectations and processes for contributing effectively. We walk you through developing a contribution guide for your project via our template, which sets clear standards for contributions and details a recommended process to follow. -This template covers the following contributions areas: -- Prerequisites to contributing -- Development process -- Ways to contribute: issues, code, documentation, media and questions, among other types of contributions +**Use Cases**: +- Guiding new contributors on making meaningful contributions. +- Ensuring contributions align with project norms and requirements. +- Facilitating a transparent and efficient contribution process. -Starter Kit: -- [Markdown](./CONTRIBUTING.md) of template -- [Demo](https://github.com/riverma/terraformly/blob/main/CONTRIBUTING.md) of template +--- -To leverage this template, make sure to do the following: -1. Talk with your team about leveraging this template, and seek wide agreement before you adopt -2. Copy the template text, and place in a file within your repository called `CONTRIBUTING.md` -3. Search and replace the `[INSERT ...` text within the file with specifics for your project -4. Add a link to the `CONTRIBUTING.md` to your `README.md` file within the `Contributing` section +## Prerequisites -This template was influenced by the following sources: +* Understanding of basic project management and version control systems. +* Familiarity with GitHub and Markdown formatting. + +--- + +## Quick Start + +**[⬇️ Contributing Guide Template](CONTRIBUTING)** + +Download our customizable template to create a contributing guide for your project. + +--- + +## Step-by-Step Guide + +1. **Team Discussion**: Collaborate with your team to decide on adopting a contribution guide template. This step is essential to establish project norms and contribution expectations. Our template touches the following topics that you'll want to consider: + - License overview + - Code of Conduct + - Governance Model + - Developer environment setup + - Communication channels + - How-to in interacting with the codebase + - Pull requests + - Ways to contribute (e.g. code, docs, media, etc.) + - etc. + + +2. **Customize the Template**: Modify the [Contributing Guide Template](CONTRIBUTING) 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**: + - Add a link to `CONTRIBUTING.md` in your project's `README.md` file under the `Contributing` section. +4. **Communicate**: + - Share the guide with existing contributors and all new contributors as their starting point. + +--- + +## Frequently Asked Questions (FAQ) + +- Q: Why should I even bother with a contributing guide? +- A: Do you want to constantly re-explain your project's philosophy and contribution norms? If not - a contribution guide helps set clear expectations and processes, ensuring contributions are consistent and aligned with your project's goals. + +--- + +## Credits + +**Authorship**: +- [Rishi Verma](https://github.com/riverma) + +**Acknowledgements**: +This template is influenced by guidelines from the following: - [Open Source Guide](https://opensource.guide/how-to-contribute/) - [Facebook React Contribution Guide](https://reactjs.org/docs/how-to-contribute.html) - [NASA-AMMOS Repositories](https://github.com/NASA-AMMOS) - [Kubernetes Contributors Guide](https://github.com/kubernetes/community/tree/master/contributors/guide) - [SciKit Learn Contributors Guide](https://scikit-learn.org/dev/developers/contributing.html) -- [Django Contributors Guide](https://docs.djangoproject.com/en/dev/internals/contributing) \ No newline at end of file +- [Django Contributors Guide](https://docs.djangoproject.com/en/dev/internals/contributing) + +--- + +## Feedback and Contributions + +Feedback and contributions are encouraged to refine this guide. Visit our [contribution guidelines](https://nasa-ammos.github.io/slim/docs/contribute/contributing/) for more information. diff --git a/docs/guides/governance/contributions/developer-certificate-origin/README.md b/docs/guides/governance/contributions/developer-certificate-origin/README.md deleted file mode 100644 index d155d1c92..000000000 --- a/docs/guides/governance/contributions/developer-certificate-origin/README.md +++ /dev/null @@ -1,14 +0,0 @@ -# Developer Certificate of Origin (DCO) - -This GitHub Action provides an automated check for ensuring developers have a "signed-off" commit when contributing to a given GitHub repository. - -Starter Kit: -- [GitHub App](https://github.com/apps/dco) to install onto your GitHub repo - -To leverage this template, make sure to do the following: -1. Talk with your team about leveraging this GitHub action, and seek wide agreement before you adopt -2. Log into GitHub.com -3. Click the above GitHub App starter kit link -4. Click "Install" in the top-right hand corner of the page -5. Follow the prompts to select the organizations and repositories you'd like to install this app -6. Verify the installation by navigating to your given repository's "Settings" page, and confirming the app appears in the "Integrations -> Applications" left-hand menu \ No newline at end of file diff --git a/docs/guides/governance/contributions/issue-templates/README.md b/docs/guides/governance/contributions/issue-templates/README.md index 595b12c92..e206f1935 100644 --- a/docs/guides/governance/contributions/issue-templates/README.md +++ b/docs/guides/governance/contributions/issue-templates/README.md @@ -1,40 +1,84 @@ # Issue Templates -Issue tickets help development teams keep the language of bug, feature, and other types of issues readable and consistent. Templates appear whenever a person submits a new issue, and helps guide that person in providing the key information that gives developers context for a given issue. +
Make issue tracking clear and consistent with structured issue templates for your contributors.-## GitHub Issues (Markdown) +## Introduction -GitHub issue markdown templates provide pre-filled structure, in markdown format, for people to enter issue information. Please see the [documentation](https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/about-issue-and-pull-request-templates) on GitHub templates for more details. +**Background**: Implementing issue templates in GitHub projects standardizes and clarifies the submission of bug reports, feature requests, and other types of issues. It guides contributors in providing essential details, helping developers understand and address issues more efficiently. -Starter Kits: -- [Bug Report](./github/bug_report.md) -- [New Feature](./github/new_feature.md) +**Use Cases**: +- Enhancing clarity and consistency in issue or feature reporting. +- Streamlining the process for contributors to report bugs or request features so that a wide audience can switch between issues easily. +- Improving developers' understanding of issues for quicker resolution. -To leverage these template, make sure to do the following: -1. Talk with your team about leveraging this template, and seek wide agreement before you adopt -2. Create a new folder within your GitHub repository with the following path: `.github/ISSUE_TEMPLATE` -3. Copy the Bug Report and New Feature template files above into the following paths: - 1. `.github/ISSUE_TEMPLATE/bug_report.md` - 2. `.github/ISSUE_TEMPLATE/new_feature.md` -4. Commit the above two files to the `main` branch -5. Navigate to your issues tab within GitHub, and you should see options to use your new templates appear +--- -## GitHub Issues (Forms) +## Prerequisites -GitHub issue forms are a method to provide a _form like_ experience when filling out a new issue ticket. Please see the [documentation](https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/configuring-issue-templates-for-your-repository#creating-issue-forms) on GitHub forms for more details. +* Access to a GitHub repository with administrative permissions. +* Basic knowledge of Markdown for editing GitHub templates. -⚠️ NOTE: GitHub issue forms are currently in beta. When using a third-party issue tracking system like ZenHub, the templates will not be usable in that system. +--- -Starter Kits: -- [Bug Report](./github/bug_report.yml.md) -- [New Feature](./github/new_feature.yml.md) +## Quick Start +**Bug Reports:** +- **[⬇️ Bug Report Template (Markdown)](bug-reports/bug_report)** +- **[⬇️ Bug Report Template (GitHub Form)](bug-reports/bug_report.yml)** -To leverage these template, make sure to do the following: -1. Talk with your team about leveraging this template, and seek wide agreement before you adopt -2. Create a new folder within your GitHub repository with the following path: `.github/ISSUE_TEMPLATE` -3. Copy the Bug Report and New Feature template files above into the following paths: - 1. `.github/ISSUE_TEMPLATE/bug_report.yml` - 2. `.github/ISSUE_TEMPLATE/new_feature.yml` -4. Commit the above two files to the `main` branch -5. Navigate to your issues tab within GitHub, and you should see options to use your new templates appear \ No newline at end of file +**New Features:** +- **[⬇️ New Feature Template (Markdown)](features/new_feature)** +- **[⬇️ New Feature Template (GitHub Form)](features/new_feature.yml)** + +**[📔 GitHub Issue Template Documentation](https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/about-issue-and-pull-request-templates)** + +--- + +## Step-by-Step Guide + +1. **Team Discussion**: Consult with your team about using GitHub issue templates. Reach a consensus on adopting this practice. Our suggested templates request the below information - see justification below. + + - Bug Reports: + 1. **Checked for duplicates**: This section asks the contributor to verify if the issue has already been reported. It helps prevent duplication and streamlines the issue management process. + 2. **Describe the bug**: The contributor provides a clear, concise description of the bug. This section is critical for developers to understand the issue's nature and impact. + 3. **What did you expect?**: Understanding the contributor's expectations clarifies the disparity between expected and actual behavior, helping to pinpoint the issue more accurately. + 4. **Reproducible steps**: Step-by-step reproduction instructions are crucial for developers to replicate the issue, diagnose the problem, and test solutions effectively. + 5. **What is your environment?**: Providing details about the hardware, operating system, or other contextual factors helps in identifying if the bug is environment-specific and aids in troubleshooting. + - New Features: + 1. **Checked for duplicates**: This section ensures the contributor has checked for existing feature requests, avoiding redundancy and streamlining the development process. + 2. **Alternatives considered**: Encourages the contributor to consider and document alternative solutions. This insight can guide the evaluation of the feature's necessity. + 3. **Related problems**: This helps identify if the feature request is a solution to an existing problem, adding context and justification for the request. + 4. **Describe the feature request**: A clear description from the contributor about the proposed feature. This clarity is essential for understanding the feature's purpose and scope. + +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. + - 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. + +3. **Commit and Use Templates**: + - Commit these files to the `main` branch. + - New issues in your repository will now offer these templates for contributors to fill. + +--- + +## Frequently Asked Questions (FAQ) + +- Q: Why are issue templates important in GitHub projects? +- A: They ensure that all necessary information is provided, leading to more effective issue tracking and resolution. + +--- + +## Credits + +**Authorship**: +- [Rishi Verma](https://www.github.com/riverma) + +**Acknowledgements**: +* GitHub for providing documentation for issue templates. + +--- + +## Feedback and Contributions + +Feedback and contributions are welcome to enhance these guidelines. See our [contribution guidelines](https://nasa-ammos.github.io/slim/docs/contribute/contributing/). diff --git a/docs/guides/governance/contributions/issue-templates/bug-reports/_category_.json b/docs/guides/governance/contributions/issue-templates/bug-reports/_category_.json new file mode 100644 index 000000000..d5eebba22 --- /dev/null +++ b/docs/guides/governance/contributions/issue-templates/bug-reports/_category_.json @@ -0,0 +1,3 @@ +{ + "label": "Bug Reports" +} diff --git a/docs/guides/governance/contributions/issue-templates/github/bug_report.md b/docs/guides/governance/contributions/issue-templates/bug-reports/bug_report.md similarity index 100% rename from docs/guides/governance/contributions/issue-templates/github/bug_report.md rename to docs/guides/governance/contributions/issue-templates/bug-reports/bug_report.md diff --git a/docs/guides/governance/contributions/issue-templates/github/bug_report.yml.md b/docs/guides/governance/contributions/issue-templates/bug-reports/bug_report.yml.md similarity index 100% rename from docs/guides/governance/contributions/issue-templates/github/bug_report.yml.md rename to docs/guides/governance/contributions/issue-templates/bug-reports/bug_report.yml.md diff --git a/docs/guides/governance/contributions/issue-templates/features/_category_.json b/docs/guides/governance/contributions/issue-templates/features/_category_.json new file mode 100644 index 000000000..a176d3628 --- /dev/null +++ b/docs/guides/governance/contributions/issue-templates/features/_category_.json @@ -0,0 +1,3 @@ +{ + "label": "New Features" +} diff --git a/docs/guides/governance/contributions/issue-templates/github/new_feature.md b/docs/guides/governance/contributions/issue-templates/features/new_feature.md similarity index 100% rename from docs/guides/governance/contributions/issue-templates/github/new_feature.md rename to docs/guides/governance/contributions/issue-templates/features/new_feature.md diff --git a/docs/guides/governance/contributions/issue-templates/github/new_feature.yml.md b/docs/guides/governance/contributions/issue-templates/features/new_feature.yml.md similarity index 100% rename from docs/guides/governance/contributions/issue-templates/github/new_feature.yml.md rename to docs/guides/governance/contributions/issue-templates/features/new_feature.yml.md diff --git a/docs/guides/governance/contributions/change-request-templates/github/PULL_REQUEST_TEMPLATE.md b/docs/guides/governance/contributions/pull-requests/PULL_REQUEST_TEMPLATE.md similarity index 95% rename from docs/guides/governance/contributions/change-request-templates/github/PULL_REQUEST_TEMPLATE.md rename to docs/guides/governance/contributions/pull-requests/PULL_REQUEST_TEMPLATE.md index 0d9cad598..7a6e526e3 100644 --- a/docs/guides/governance/contributions/change-request-templates/github/PULL_REQUEST_TEMPLATE.md +++ b/docs/guides/governance/contributions/pull-requests/PULL_REQUEST_TEMPLATE.md @@ -4,6 +4,7 @@ ## Proposed Changes - [ADD] ... - [CHANGE] ... +- [REMOVE] ... - [FIX] ... ## Issues - Links to relevant issues diff --git a/docs/guides/governance/contributions/pull-requests/README.md b/docs/guides/governance/contributions/pull-requests/README.md new file mode 100644 index 000000000..baafc1424 --- /dev/null +++ b/docs/guides/governance/contributions/pull-requests/README.md @@ -0,0 +1,74 @@ +# Pull Requests + +
A walk-through on using our standardized template for pull requests.+ +## Introduction + +**Background**: Pull requests help manage contributions to projects, especially on platforms like GitHub. By using a standardized pull request template, projects can streamline the contribution process, providing clarity and consistency for both contributors and maintainers. This guide will help you implement a GitHub Pull Request Template to improve how contributions are made to your project. + +**Use Cases**: +- Standardizing the format of pull requests for clarity and efficiency. +- Providing guidelines to contributors for submitting well-documented pull requests. + +--- + +## Prerequisites + +* Access to a GitHub repository where you can add files. +* Basic understanding of GitHub's file structure and Markdown formatting. + +--- + +## Quick Start + +**[⬇️ Pull Request Template](PULL_REQUEST_TEMPLATE)** + +Our recommended pull request template for projects. + +**[📔 GitHub Pull Request Template Documentation](https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/creating-a-pull-request-template-for-your-repository)** + +Recommendations from GitHub.com on how-to facilitate the use of pull request templates. + +--- + +## 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) 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. + - `[CHANGE]` for modifications to existing features or code. + - `[REMOVE]` for removals features or code. + - `[FIX]` for bug fixes the contributor implemented. + - ***Issues***: To link any related issues your PR addresses. This creates a traceable connection between the issue and the solution provided. + - ***Testing***: To document how the contributor tested the changes. Including links to test results or noting the operating systems on which the tests were performed. This assures reviewers of the reliability and effectiveness of changes. + +2. **Create Template Directory**: + - 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) into `.github/PULL_REQUEST_TEMPLATE`. + - Commit and push this file to the `main` branch of your repository. + +4. **Usage**: + - Once set up, this template will automatically appear in the pull request description box for contributors to fill out. + +--- + +## Frequently Asked Questions (FAQ) + +- Q: How does a pull request template improve contributions? +- A: It provides a structured format for contributors, ensuring all necessary information is included, which facilitates better review and collaboration. + +--- + +## Credits + +**Authorship**: +- [Rishi Verma](https://www.github.com/riverma) + +--- + +## Feedback and Contributions + +We welcome feedback and contributions to enhance this guide. For contributing, please see our [contribution guidelines](https://nasa-ammos.github.io/slim/docs/contribute/contributing/). diff --git a/docs/guides/governance/governance-model/README.md b/docs/guides/governance/governance-model/README.md index 7cf84f82b..614edec7b 100644 --- a/docs/guides/governance/governance-model/README.md +++ b/docs/guides/governance/governance-model/README.md @@ -1,23 +1,84 @@ # Governance Model -This governance model template seeks to generalize how most government-sponsored open source projects can expect to operate in the open source arena. It is targeted towards medium and large-sized teams. This template governance model can be included in your repository under the file name `GOVERNANCE.md`. There are two key philosophies behind this governance model to keep note of: -- Liberal acceptance, encouragement and promotion of open source contributors from the public -- Retention of decision-making authority to sources of funding +
Establish a project guide for effective open source governance.-# Directions +## Introduction -Template: -- [Markdown](GOVERNANCE-TEMPLATE.md) of template +**Background**: A governance model is essential for government-sponsored open source projects, particularly for medium and large-sized teams. It helps in liberal acceptance of public contributions while retaining decision-making authority with funding sources. This guide provides a template to integrate a generalized governance model into your project, promoting clear operational structure and community engagement. -To leverage this template, make sure to do the following: -1. Talk with your team (including stakeholders) about leveraging this template, and seek wide agreement before you adopt. In particular, ensure there's buy-in for the philosophy of the governance approach (i.e. liberal acceptance of contributors) and role-based committees for governing (i.e. technical / project steering committees). -2. Copy the template text and place in a file within your repository called `GOVERNANCE.md` -3. Search and replace the `[INSERT ...` text within the file with specifics for your project -4. Add a link to the `GOVERNANCE.md` to your `README.md` file within the `Contributing` section +**Use Cases**: +- Structuring decision-making processes in open source projects. +- Balancing open contribution with authoritative project direction. +- Establishing clear roles and responsibilities within the project team. + +--- + +## Prerequisites + +* Understanding of open source project management. +* Familiarity with Markdown for editing GitHub documentation. + +--- + +## Quick Start + +**[Governance Model Template](GOVERNANCE-TEMPLATE.md)** + +Access our recommended template to start integrating a governance model into your project. + +--- + +## 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: + - 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). + - 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**: + - Commit the `GOVERNANCE.md` file to the `main` branch. + - Link to the governance document in your `README.md` file under the `Contributing` section. + +--- + +## Frequently Asked Questions (FAQ) + +- **Q: What is the importance of a governance model in open source projects?** +- A: It provides a framework for decision-making, contribution processing, and project management, ensuring transparent and structured project operations. + + +- **Q: What is the role of the Technical Steering Committee (TSC) in this governance model?** +- A: The TSC handles technical decisions, governance processes, and maintains collaborator lists, playing a key role in guiding the project's technical aspects. + + +- **Q: How are conflicts resolved in this governance model?** +- A: The model advocates for consensus-seeking; however, if consensus cannot be reached, the Product Manager has final authority, ensuring decision-making progresses. + + +- **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. + +--- + +## Credits + +**Authorship**: +- [Eric Ferguson](https://github.com/ewferg) +- [Rishi Verma](https://github.com/riverma) + +**Acknowledgements**: This template was developed by evaluating best `GOVERNANCE.md` practices in the following organizations: - [NASA AMMOS AERIE](https://github.com/NASA-AMMOS/aerie/blob/develop/docs/GOVERNANCE.md) - [node.js](https://github.com/nodejs/node/blob/main/GOVERNANCE.md) - [OpenSSL](https://www.openssl.org/policies/omc-bylaws.html) - [PostgresQL](https://www.postgresql.org/developer/) -- [OpenMCT](https://github.com/nasa/openmct/blob/master/CONTRIBUTING.md) \ No newline at end of file +- [OpenMCT](https://github.com/nasa/openmct/blob/master/CONTRIBUTING.md) + +--- + +## 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/). diff --git a/docs/guides/governance/governance-model/governance-template-small-team.md b/docs/guides/governance/governance-model/governance-template-small-team.md new file mode 100644 index 000000000..5d999602a --- /dev/null +++ b/docs/guides/governance/governance-model/governance-template-small-team.md @@ -0,0 +1,75 @@ +````markdown +# [INSERT PROJECT NAME] Project Governance + +This governance model aims to create an open source community that encourages transparency, contributions, and collaboration, but maintains sound technical and quality standards. Our goal is to build a community comprised of members across the [INSERT PROJECT DOMAIN] community and beyond, including from private organizations, universities, government organizations, and international organizations. + +The project follows a fairly liberal contribution model where people and/or organizations who do the most work will have the most influence on project direction. Roles determine decision making influence, and a governing Steering Committee is set up to ensure the project's direction is in-line with requirements/goals while supporting flexibility for future growth and membership. Decision making will primarily be made through a "[consensus-seeking](https://en.wikipedia.org/wiki/Consensus-seeking_decision-making)" approach within the Steering Committee. + +## Roles + +| Role | Restricted To | Description | Read/Clone | Propose Pull Request | Comment in Tickets / Discussions | Triage | Review | Commit | Decisions | +| ------------------ | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- | -------------------- | -------------------------------- | ------ | ------ | ------ | ------------------------- | +| User | None | Anyone downloading, deploying, or operating the software to meet a specific objective. | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ | +| Contributor | None | Anyone providing input to the project, including: code, issues, documentation, graphics, etc. | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ | +| Committer | Contributor | Subset of contributors granted write access to one or more of the project repositories. | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ | +| Steering Committee Member | Committer | A subset of committers with decision making authority over technical and project aspects, including admin privileges. | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| Product Manager | Steering Committee Member | Overall manager of project with final authority over all key decisions when consensus cannot be reached within the Steering Committee. | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | + +### User + +Anyone who has downloaded, deployed, or operated [INSERT PROJECT NAME] to meet a specific objective. This project was primarily designed for [INSERT DESCRIPTION OF PROJECT PURPOSE], but let us know if you've found other uses for it. + +### Contributor + +Contributors include anyone that provides input to the project. This includes code, issues, documentation, graphics, designs, or anything else that tangibly improves the project. We encourage you to start contributing right away by joining our [Discussions]([INSERT LINK TO DISCUSSION BOARD OR MAILING LIST(S)]) or submitting an [Issue]([INSERT LINK TO ISSUE TRACKING SYSTEM]). + +### Triager + +Subset of contributors who have demonstrated a strong familiarity with the project and are regularly contributing to the project via issue creation, commenting, discussions, etc. Triagers are given specific permissions do the following: + + - Label issues and pull requests + - Comment, close, and reopen issues and pull requests + +[List of current Triagers]([INSERT LINK TO GITHUB, GITLAB, ETC. TEAM ASSOCIATED WITH TRIAGERS]) + +### Collaborator + +Subset of contributors who have been given write access to one or more project repositories. Both contributors and collaborators can propose changes to the project via pull requests, but only collaborators can formally review and approve (merge) these requests. Any contributor who has made a non-trivial contribution should be on-boarded as a collaborator in a timely manner. + +If you are planning on making a substantial contribution to the project or feel as though you should be given write access to a repository, please send a request to [INSERT LINK TO EMAIL/GITHUB USER HANDLE] + +[List of current collaborators]([INSERT LINK TO GITHUB, GITLAB, ETC. TEAM ASSOCIATED WITH COLLABORATORS]) + +### Steering Committee Member + +A subset of collaborators form the Steering Committee. The Steering Committee has authority over all aspects of this project: + +- Technical direction and guidance +- Project governance and process +- Contribution policy +- Conduct guidelines +- Maintaining the list of collaborators + +#### Committee Members +- [INSERT MEMBER NAME] ([username1]([INSERT LINK TO USERNAME]), [INSERT ORG ASSOCIATION] +(Additional member listings) + +
+
+
+#### Scope
+(Description remains the same as TSC Scope)
+
+#### Decision Making Process
+(Description remains the same as TSC Decision Making Process)
+
+### Product Manager
+(Description remains the same)
+
+# Acknowledgements
+(Description remains the same)
+````
\ No newline at end of file
diff --git a/docs/guides/search.md b/docs/guides/search.md
index 6340f5608..db93ae7b8 100644
--- a/docs/guides/search.md
+++ b/docs/guides/search.md
@@ -4,17 +4,55 @@ sidebar_position: 1
import FacetedPanels from '@site/src/components/FacetedPanels';
import registryJSON from '@site/static/data/slim-registry.json';
-
-
-# All Guides
-
-Welcome to our best practice guide resources!
-
-Here's how to get started using our resources:
-- Use the faceted search below to find exactly the type of best practice you're looking for
-- Use the left-navigation sidebar to explore our best practice guides organically
+import { Card, Button } from 'react-bootstrap';
+import 'bootstrap/dist/css/bootstrap.min.css';
+import { Link } from 'react-router-dom';
+
+# Guides
+
+Explore our guides via the categories below or the left-hand navigation. You may also search our guides.
+
+Emeriti
+#### Committee Emeriti +- [INSERT MEMBER NAME] ([username1]([INSERT LINK TO USERNAME]), [INSERT ORG ASSOCIATION] +(Additional member listings) +
+
+
+
+ 
+ Software Lifecycle
+
+ Covers the entire process of software development, continuous pipelines, application kits, testing, and security.
+
+
+
+
+
+
+
+
+ 
+ Governance
+
+ Dedicated to establishing robust governance frameworks, with standards for contributions and governance models.
+
+
+
+
+
+
+
+
+ 
+ Documentation
+
+ Focuses on creating effective project documentation, including Change Logs, Documentation Hosts, and README templates.
+
+
+
+
+
+
+
+ +## Search +
A deployment-ready Python 3 application template for quick, standards-based project setup.+ +## Introduction + +**Background**: The Python Starter Kit serves as a comprehensive template for Python 3 applications to streamline development processes. It exemplifies an integrated approach to build, release and publish using GitHub's CI/CD automation. By leveraging modern Python tooling, the kit simplifies the process of compiling, tagging, releasing and publishing to the Python Package Index (PyPi). It adheres to PEP 517/518 standards with TOML-based configurations to ensure a modern, declarative programming approach. + +**Use Cases**: +- Streamlining Python project setup and configuration. +- Facilitating the build and release process of Python packages to PyPi. +- Update build and release tooling to modern standards using PEP [517](https://peps.python.org/pep-0517/)/[518](https://peps.python.org/pep-0518/) compliant tooling with declarative [TOML-based](https://toml.io/en/) configurations in a `pyproject.toml` file. + +--- + +## Prerequisites + +* GitHub account with repository creation rights. +* Familiarity with Python, Docker and GitHub Actions. +* Access to PyPi for package publishing. + +--- + +## Quick Start + +**[SLIM Starterkit Python](https://github.com/NASA-AMMOS/slim-starterkit-python)** + +Click the link above to access the starter kit and begin setting up your project using Python best practices. Select GitHub's "Use this template" feature to leverage the template repository. + +--- + +## Step-by-Step Guide + +1. **Team Consensus**: Discuss and agree on continuous integration best practices with your development team. Establish a workflow for building, publishing and releasing software. + +2. **Create a Repository**: + - Use our [repository template](https://github.com/NASA-AMMOS/slim-starterkit-python/generate) for a quick start. + - Alternatively, [clone and manually edit our starter kit](https://github.com/NASA-AMMOS/slim-starterkit-python). + +3. **Setup Account Credentials**: + - Register to create accounts on [Test PyPi](https://test.pypi.org/account/register/) and [PyPi](https://pypi.org/account/register/). You'll use one account for testing and one for deployments of your artifact. + - [Generate API tokens](https://pypi.org/help/#apitoken) on PyPI for your accounts. Name your tokens `PYPI_API_TOKEN` and copy their value for the next step below. + - Configure these tokens in your repository's [GitHub Secrets](https://docs.github.com/en/actions/security-guides/encrypted-secrets?tool=webui#creating-encrypted-secrets-for-a-repository). + +4. **Choose a Unique Python 3 Module Name**: Ensure it's distinct from [existing PyPi modules](https://pypi.org/search/?q=). + +5. **Move Code into Place**: + - Rename `slim_sample_project` to your module name. + - For existing projects, integrate your Python 3 code into the new project structure underneath the module-name directory. + > **Shortcut** + Lines requiring code updates are commented with the keyword `MODIFY`. + > Documentation requiring updates are marked with the keyword `INSERT`. + +6. **Apply Project Settings**: + - Update `pyproject.toml` to update build system dependencies + - [Edit the `write_to` variable](https://github.com/NASA-AMMOS/slim-starterkit-python/blob/main/pyproject.toml#L12) to point to the directory containing your Python 3 code. + - Update `setup.cfg` to specify build system configurations + - [Edit the metadata keywords](https://github.com/NASA-AMMOS/slim-starterkit-python/blob/main/setup.cfg#L4) to set appropriate [keyword values](https://setuptools.pypa.io/en/latest/references/keywords.html) to apply to your project. 1. Set `name` to match your unique module name. 2. Modify `console_scripts` to point at your entry-point: 1. If your [module launches from a command-line](https://setuptools.pypa.io/en/latest/userguide/entry_point.html#entry-points), define an executable inside your module: `executable-name = my_package.module:function`. 2. Set the value as empty if there is no entry-point. 3. Update URLs for your project. - 1. Replace `NASA-AMMOS/slim-starterkit-python` with the **project/repo_name** for your cloned project. + 1. Replace `NASA-AMMOS/slim-starterkit-python` with the **project/repo_name** for your cloned project (or refactoring on an existing repo). 4. Update `author`, `author_email`, `description` and `keywords` to reflect your project details - 3. Update documentation to reflect details about your new project - 1. Suggested updates for `CODE_OF_CONDUCT.md`, `CONTRIBUTING.md` and `README.md` are marked by the keyword `INSERT` and explained in detail within markdown. -> **Alert** - Unique development configurations may adversely impact testing on local workstations. Testing should be conducted with a [supported python.org release](https://www.python.org/downloads/) or [virtual container as used on GitHub](https://hub.docker.com/_/python/) . -7. Build locally to test the configuration -The application will build, install and deploy from a local command line when all configurations are properly set. - 1. [Install local tooling and requirements](https://github.com/NASA-AMMOS/slim-starterkit-python/tree/main#required-local-tooling) - 2. [Clean and build](https://github.com/NASA-AMMOS/slim-starterkit-python/tree/main#local-build-testing) and clean again after module builds successfully + +7. **Build Locally**: The application will build, install and deploy from a local command line when all configurations are properly set. + - [Install local tooling and requirements](https://github.com/NASA-AMMOS/slim-starterkit-python/tree/main#required-local-tooling) + - [Clean and build](https://github.com/NASA-AMMOS/slim-starterkit-python/tree/main#local-build-testing) and clean again after module builds successfully > **Information** - To validate the module, we test on the Test PyPi sandbox _by default_. Then, to release on the official PyPi, a _minor configuration change is required_. __All previous steps must be complete.__ -8. Build on GitHub + To validate deployment, we publish the module to the Test PyPi sandbox _by default_. To publish on the official PyPi, a _minor configuration change is required_. __All previous steps must be complete and the application must build successfully.__ + +8. **Build on GitHub**: A release kicks off a build and release process in GitHub Actions. - 1. Test publication on Test PyPi + - Test publication on Test PyPi 1. Update the [version number in the `version.py` file](https://github.com/NASA-AMMOS/slim-starterkit-python/blob/main/slim_sample_project/version.py). 2. [Kick off a build by releasing your product using the same version.](https://github.com/NASA-AMMOS/slim-starterkit-python/tree/main#automated-build-kickoff) - 3. When the product builds successfully, proceed to step **ii**. _Otherwise, revisit earlier steps and check for errors or other invalid settings._ - 2. Release to PyPi (simple configuration changes point at the release server) + 3. When the product builds successfully, proceed to the next section, **Release to PyPi**. _Otherwise, revisit earlier steps and check for errors or other invalid settings._ + - Release to PyPi (simple configuration changes point at the release server) 1. Update `PYPI_API_TOKEN` to point at PyPi in [GitHub Secrets](https://docs.github.com/en/actions/security-guides/encrypted-secrets?tool=webui#creating-encrypted-secrets-for-a-repository) in your newly created repository 1. In the repository, select the `Settings` tab and navigate to `Security`: `Secrets and variables` **-->** `Actions`. - 2. Recalling the PyPi token previously saved in step 3(ii): In `Repository secrets`, edit the `PYPI_API_TOKEN` and paste the saved PyPi token value to update it. + 2. Recalling the PyPi token previously saved in **Setup Account Credentials** (step 3 above): Edit the `PYPI_API_TOKEN` in `Repository secrets` to the saved PyPi token value for PyPi. (In other words, replace the test token with the regular, non-test PyPi token.) 2. Change the `python-publish.yml` configuration to remove Test PyPi coordinates 1. Remove '`--repository testpypi`' from the one-line publish command to read: `twine upload --verbose dist/*.whl dist/*.zip` 3. Update the [version number in the `version.py` file](https://github.com/NASA-AMMOS/slim-starterkit-python/blob/main/slim_sample_project/version.py). - 4. [Kick off a build by releasing your product using the same version.](https://github.com/NASA-AMMOS/slim-starterkit-python/tree/main#automated-build-kickoff) + 4. [Kick off a build by tagging and releasing your product using the same version number.](https://github.com/NASA-AMMOS/slim-starterkit-python/tree/main#automated-build-kickoff) -#### Deliverables +--- + +## Additional Files This starter kit produces several deliverables deployed for distribution: * **GitHub** * [Release report with automatic changelog summaries based on commit history.](https://github.com/NASA-AMMOS/slim-starterkit-python/releases/latest) @@ -89,7 +97,37 @@ This starter kit produces several deliverables deployed for distribution: * [ZIP](https://github.com/NASA-AMMOS/slim-starterkit-python/tags/) * **PyPi** * [Fully documented site with project links](https://test.pypi.org/project/slim-sample-project/) - * Source distribution (with release hashes): - * [ZIP](https://test.pypi.org/project/slim-sample-project/#files) - * Built Python 3 distribution: - * [Python wheel](https://test.pypi.org/project/slim-sample-project/#files) \ No newline at end of file + * Completely built Python 3 distributions: + * [Compressed ZIP source code with release hashes](https://test.pypi.org/project/slim-sample-project/#files) + * [Python wheel](https://test.pypi.org/project/slim-sample-project/#files) + +--- + +## Frequently Asked Questions (FAQ) + +- Q: What tooling is necessary to use the starter kit? +- A: [Python 3 version 3.9 or greater](https://www.python.org/downloads/) must be installed with a working [package manager (`pip`)](https://pip.pypa.io/en/stable/installation/). As well, you'll need the latest versions of `pip`, `build`, `setuptools`, `twine` and `wheel`. + ``` + python3 --version # must report Python >3.9.x + pip3 install --upgrade pip + pip3 install --upgrade build setuptools setuptools_scm twine wheel + ``` + +- Q: How do I choose a unique module name for PyPi? +- A: Research existing modules on PyPi and select a name that is not already in use. Consider using a creative and/or descriptive name relevant to your project. + +--- + +## Credits + +**Authorship**: +- [John Engelke](https://github.com/jpl-jengelke) + +**Acknowledgements**: +* Inspiration and practices from modern Python tooling and GitHub CI/CD workflows. + +--- + +## Feedback and Contributions + +We welcome feedback and contributions to improve this guide. Please see our [contribution guidelines](https://nasa-ammos.github.io/slim/docs/contribute/contributing/). diff --git a/docs/guides/software-lifecycle/continuous-integration/README.md b/docs/guides/software-lifecycle/continuous-integration/README.md index b42495c83..3fd096671 100644 --- a/docs/guides/software-lifecycle/continuous-integration/README.md +++ b/docs/guides/software-lifecycle/continuous-integration/README.md @@ -1,3 +1,85 @@ # Continuous Integration -This this guide, we explore best practices for continuous integration - including exploring scenarios for build integration, publishing test results and releasing compiled software. +
A guide for implementing continuous integration in software projects.+ +## Introduction + +**Background**: Continuous Integration (CI) is a critical practice in modern software development. This guide introduces a comprehensive approach to CI from analysis and testing to orchestration and release management. We focus on using a variety of tools like Git hooks, GitHub Actions, Jenkins and more to create a robust CI pipeline. By following this guide and combining these tools, developers can automate their build and testing processes, ensuring software is always ready for deployment. + +**Use Cases**: +- Automating software integration, build and testing. +- Streamlining software release and deployment. +- Ensuring software quality and reliability through repeatable engineering processes. + +--- + +## Prerequisites + +* Basic knowledge of software development and version control systems. +* Familiarity with CI/CD concepts and practices. + +--- + +## Quick Start + +**[📔 CI Tools and Frameworks](continuous-integration-frameworks.md)** + +Click the link above to explore various tools and systems for setting up and optimizing your CI pipeline. + +**[📔 CI Reference Architectures](reference-architecture.md)** + +Click the link above to explore the overall sample architecture for a continuous integration system. + +--- + +## Step-by-Step Guide + +1. **Explore CI Tools and Frameworks**: + - Start with the [CI Tools and Frameworks](continuous-integration-frameworks.md) guide to explore a range of task-focused CI tools. + - Review different categories, such as Analysis and Testing, Credentialing, and Execution and Reporting Tests. + - Based on your use case, select appropriate tools, e.g. Git hooks, GitHub Actions, Jenkins, Maven plugins or SetupTools, that are are designed for the software and technologies used in your product. + +2. **Understand the Reference Architecture**: + - Dive into the [CI Reference Architectures](reference-architecture.md) for an overview of the CI process and its components. + - Understand the core concepts of the CI pipeline, which involves Developer systems, Continuous Integration services, Continuous Deployment platforms and other touchpoints. + - Learn about the discrete process steps in a CI pipeline, such as Compile, Test, Package, Publish and Deploy (i.e. release or deliver), and how they contribute to building and releasing software. + +3. **Combine Reference Architecture with Selected Tools**: + - With the understanding of CI tools from **Step 1**, and the architectural insights from **Step 2**, begin mapping tools to specific roles in your CI pipeline. + - For example: + - Use Git hooks for code check-ins and GitHub Actions for automated build and testing processes. + - Utilize Jenkins or GitHub Actions for more complex workflows, like orchestrating builds across different environments or managing deployment strategies. + - Implement credentialing tools like Jenkins Credentials Binding Plugin or OAuth for secure access to resources. + - Ensure testing is thorough by integrating language-specific plugins or frameworks, such as Maven for Java or PyTest for Python, into your build process. + - Use orchestration tools like Ansible for deployment, aligning them with your cloud infrastructure managed by Terraform or Kubernetes. + - Package your application using Docker or appropriate tools, ensuring a streamlined process from development to deployment. + - Update a copy of the reference architectural diagram with your selected tools. + +--- + +## Frequently Asked Questions (FAQ) + +- Q: How do I choose the right CI tools for my project? +- A: Consider your project’s language, complexity and the specific needs of your deployment environment. Research and compare tools to find the best fit for your workflow. + +- Q: What is the difference between Continuous Integration, Continuous Deployment and Continuous Delivery? +- A: These related concepts apply to different target stages of a comprehensive CI/CD process, but their definitions are often conflated. Each one of these stages determines the endpoint as builds progress in a given automation process. + - _Continuous Integration_ (code compiles) tests whether code when merged from different developer systems can be compiled together on a control system, e.g. the CI server. + - _Continuous Deployment_ (packages published) is the publishing of successfully compiled and packaged binaries to an artifact repository and/or local test servers. + - _Continuous Delivery_ (packages released) extends deployment by pushing packaged binaries immediately to production services upon successful build, test and publishing. + +--- + +## Credits + +**Authorship**: +- [John Engelke](https://www.github.com/jpl-jengelke) + +**Acknowledgements**: +* This guide was inspired by the comprehensive tooling options available in the CI/CD ecosystem. + +--- + +## Feedback and Contributions + +Your feedback and contributions are vital to the continuous improvement of this guide. Please see our [contribution guidelines](https://nasa-ammos.github.io/slim/docs/contribute/contributing/) for more information. diff --git a/docs/guides/software-lifecycle/continuous-integration/continuous-integration-frameworks/continuous-integration-frameworks.md b/docs/guides/software-lifecycle/continuous-integration/continuous-integration-frameworks.md similarity index 97% rename from docs/guides/software-lifecycle/continuous-integration/continuous-integration-frameworks/continuous-integration-frameworks.md rename to docs/guides/software-lifecycle/continuous-integration/continuous-integration-frameworks.md index 1b0c0a8c0..0f4c02650 100644 --- a/docs/guides/software-lifecycle/continuous-integration/continuous-integration-frameworks/continuous-integration-frameworks.md +++ b/docs/guides/software-lifecycle/continuous-integration/continuous-integration-frameworks.md @@ -1,6 +1,6 @@ --- -title: Continuous Integration Frameworks -sidebar_label: Continuous Integration Frameworks +title: CI Tools and Frameworks +sidebar_label: CI Tools and Frameworks --- diff --git a/docs/guides/software-lifecycle/continuous-integration/continuous-integration-frameworks/README.md b/docs/guides/software-lifecycle/continuous-integration/continuous-integration-frameworks/README.md deleted file mode 100644 index 65e6456cc..000000000 --- a/docs/guides/software-lifecycle/continuous-integration/continuous-integration-frameworks/README.md +++ /dev/null @@ -1,3 +0,0 @@ -# Continuous Integration Frameworks - -[Frameworks & Use Cases) [continuous-integration-frameworks] \ No newline at end of file diff --git a/docs/guides/software-lifecycle/continuous-integration/reference-architecture/README.md b/docs/guides/software-lifecycle/continuous-integration/reference-architecture.md similarity index 99% rename from docs/guides/software-lifecycle/continuous-integration/reference-architecture/README.md rename to docs/guides/software-lifecycle/continuous-integration/reference-architecture.md index 7fb7bda2f..b78a3be9e 100644 --- a/docs/guides/software-lifecycle/continuous-integration/reference-architecture/README.md +++ b/docs/guides/software-lifecycle/continuous-integration/reference-architecture.md @@ -1,4 +1,4 @@ -# Reference Architectures +# CI Reference Architectures ## Overview Architectures presented here provides a high-level reference guide for the implementation of continuous integration diff --git a/docs/guides/software-lifecycle/security/README.md b/docs/guides/software-lifecycle/security/README.md deleted file mode 100644 index 0e42385e6..000000000 --- a/docs/guides/software-lifecycle/security/README.md +++ /dev/null @@ -1 +0,0 @@ -# Security \ No newline at end of file diff --git a/docs/guides/software-lifecycle/security/_category_.json b/docs/guides/software-lifecycle/security/_category_.json new file mode 100644 index 000000000..eb6832c17 --- /dev/null +++ b/docs/guides/software-lifecycle/security/_category_.json @@ -0,0 +1,8 @@ +{ + "label": "Security", + "position": 1, + "link": { + "type": "generated-index", + "description": "Security Best Practices." + } +} diff --git a/docs/guides/software-lifecycle/security/dependabot/README.md b/docs/guides/software-lifecycle/security/dependabot/README.md deleted file mode 100644 index 17924832a..000000000 --- a/docs/guides/software-lifecycle/security/dependabot/README.md +++ /dev/null @@ -1,45 +0,0 @@ -# Dependabot -A GitHub ecosystem tool for dependency version and security vulnerability analysis. - -## Automated Dependency Updates - -This Dependabot task provides an automated check for OSS component updates and automatically creates [pull requests](https://docs.github.com/en/code-security/dependabot/working-with-dependabot/managing-pull-requests-for-dependency-updates) to commit new versions. - -Starter Kit: -- [SLIM Starterkit Python -- Dependabot Script](https://github.com/NASA-AMMOS/slim-starterkit-python/blob/main/.github/dependabot.yml) to install in your GitHub repo - -To leverage Dependabot, make sure to do the following: -1. Discuss with your development team the cybersecurity best practice to regularly update OSS to latest versions and seek consensus on a workflow to accept proposed updates. -2. Add Dependabot automation to your repository, either via the **admin console** or **manually** (choose **one**): -> **Shortcut** - Copy the pre-set configuration to an identical path in your repository, e.g. `.github/dependabot.yml`. - * **Admin console:** (requires admin rights) - 1. Proceed to [enable Dependabot alerts through GitHub Settings UI](https://docs.github.com/en/code-security/dependabot/dependabot-alerts/configuring-dependabot-alerts#enabling-or-disabling-dependabot-alerts-for-a-repository). - * **Manually:** (_approach available to all committers_) - 1. Create an issue and an issue branch to implement a code change. Checkout the issue branch. - 2. Copy the Dependabot configuration file from one of the SLIM Starterkit repos -- for example, [`dependabot.yml` in the Python Starterkit](https://github.com/NASA-AMMOS/slim-starterkit-python/blob/main/.github/dependabot.yml) -- into the root of your repository at `.github/dependabot.yml`. -3. Modify [Dependabot configurations](https://docs.github.com/en/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file#configuration-options-for-the-dependabotyml-file) for your project: -> **Requirement** - Set properties to match your repository setup, including core packaging system. - * Set the `package-ecosystem` property to [match your packaging system](https://docs.github.com/en/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file#package-ecosystem) in `dependabot.yml`. - * Set the `target-branch` to the [name of your default branch](https://github.com/NASA-AMMOS/slim-starterkit-python/branches) in `dependabot.yml`. - * Optionally, value-added features may be set, including such settings as [scheduling](https://docs.github.com/en/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file#scheduleday), a [strategy for versioning](https://docs.github.com/en/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file#versioning-strategy) and [pull request reviewers](https://docs.github.com/en/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file#reviewers). -4. Dependabot is now installed and detections can be tracked through the dependency graph at [`Insights` **->** `Dependency graph` **->** `Dependabot`](https://github.com/NASA-AMMOS/slim-starterkit-python/network/updates). [Pull Requests](https://github.com/NASA-AMMOS/slim-starterkit-python/pulls) also will include automatically created Dependabot merges. - -## Automated Security Updates - -This Dependabot task automates security scanning for [known vulnerabilities](https://github.com/advisories) in OSS components and automatically creates [pull requests](https://docs.github.com/en/code-security/dependabot/working-with-dependabot/managing-pull-requests-for-dependency-updates) to update flagged components. - -[Dependabot Security Updates](https://docs.github.com/en/code-security/dependabot/dependabot-security-updates) requires [Dependabot Automated Dependency Updates](./README.md#automated-dependency-updates) (see above). Although technically part of the same automation stack, it's [enabled through the GitHub Settings UI](https://docs.github.com/en/code-security/dependabot/dependabot-security-updates/configuring-dependabot-security-updates#enabling-or-disabling-dependabot-security-updates-for-an-individual-repository). Optionally, dependency updates can be disabled so that only security updates create pull requests. - -> **Requirement** - Install and set up the Starter Kit for Dependabot Automated Dependency Updates. - -To leverage this template, make sure to do the following: -1. Discuss with your development team the cybersecurity best practice to regularly scan OSS components for security flaws and seek consensus on a workflow to accept proposed updates. -2. Enable Security Updates: - 1. At [`Settings` **->** `Code security and analysis` **->** `Dependabot`](https://github.com/NASA-AMMOS/slim-starterkit-java/settings/security_analysis), select the `Enable` button to turn on `Dependabot security updates`. -> **Requirement** - Admin rights are necessary to modify `Code security and analysis` settings. -3. Modify [Dependabot configurations](https://docs.github.com/en/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file#configuration-options-for-the-dependabotyml-file) for your project: (optional) - 1. If only security-related pull requests are desired, [set the `open-pull-requests-limit` property to `0` for `updates` block(s)](https://docs.github.com/en/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file#open-pull-requests-limit). diff --git a/docs/guides/software-lifecycle/security/github-security/README.md b/docs/guides/software-lifecycle/security/github-security/README.md new file mode 100644 index 000000000..1f18cc822 --- /dev/null +++ b/docs/guides/software-lifecycle/security/github-security/README.md @@ -0,0 +1,106 @@ +# GitHub Security Best Practices + +
Recommendations for enabling GitHub security features for your repositories.+ +## Introduction + +**Background:** GitHub offers a suite of security features to help maintainers and developers protect their code and ensure the safety of their repositories. From automatically detecting vulnerabilities in dependencies to scanning for secrets and setting security policies, these tools are essential for any project, especially in today’s security-conscious environment. + +**Use Cases:** +- Being alerted over e-mail or GitHub notifications about known vulnerabilities in your dependencies and having pull-requests automatically created to resolve the issues. +- Being alerted if your dependencies have updated versions available. +- Being alerted if your commits have potentially harmful secrets or sensitive information within the code - including being blocked from pushing your commits. + +## Prerequisites + +- A GitHub repository +- Familiarity with GitHub’s user interface +- Admin rights for certain security configuration tasks +- Team discussion: before diving into any configurations, we recommend engaging with your development team about the importance of GitHub’s security features. Establish a consensus on which ones to prioritize and implement. + +## Quick Start + +The fastest way to enable recommended GitHub Security features is to perform it in bulk for _all_ of your repositories within a given organization. Consult [Enabling security features for multiple repositories](https://docs.github.com/en/enterprise-cloud@latest/code-security/security-overview/enabling-security-features-for-multiple-repositories) for details. Organization administrative-level access is required. + +We recommend enabling the below features for all your repositories: + + + +Specifically: +- Dependency graphs (select "Enable All") + - Select "Automatically enable for new private repositories" +- Dependabot Alerts (select "Enable All") + - Select "Automatically enable for new repositories" +- Dependabot Security Updates (select "Enable All") + - Select "Automatically enable for new repositories" +- Code Scanning (select "Enable All") + - Select the default "CodeQL high-precision queries" option + +If you do not have organizational permissions or if you wish to customize security features per repository, see our Step-by-Step guide below for repository-specific guidance. + +## Step-by-Step Guide per Repository + +1. **Set Up Dependabot:** + - Navigate to your repository and click on the `Settings` tab. + - From the left sidebar, select the `Code security and analysis` menu. + - Under the "Dependabot" section: + - We recommend enabling Dependabot alerts to stay informed about insecure dependencies in your project. + - For added security, we suggest turning on Dependabot security updates to automatically generate pull requests for known vulnerabilities in your dependencies. + - We also recommend enabling Dependabot version updates _if you are using a package manager for your project_. This will help you keep your dependencies up-to-date. To configure Dependabot version updates: + 1. Create a `.github/dependabot.yml` file in your repository. + 2. Specify the package-ecosystem, directory, and schedule for the updates. For example: + ```yml + version: 2 + updates: + - package-ecosystem: "npm" + directory: "/" + schedule: + interval: "daily" + ``` + - To view Dependabot alerts and version updates: + - Head back to the main page of your repository. + - Click on the `Security` tab. Here, you can select `Dependabot alerts` to view security alerts, and you can see version updates in the `Pull requests` tab labeled with "Dependabot". + + +2. **Enable Code Scanning:** + - In the `Code security and analysis` menu from the `Settings` tab, click the "Set Up" or enable the following workflows: + - _CodeQL Analysis workflow:_ a free tool provided by GitHub that scans your code for vulnerabilities across a variety of languages. Simply choose a CodeQL Analysis template (default is acceptable) and follow the instructions. + - To view Code scanning alerts: + - Return to the repository main page. + - Click on the `Security` tab and select `Code scanning alerts`. + +3. **Enable Secret Scanning:** + - In the `Code security and analysis` menu from the `Settings` tab: + - Click on the `Secret scanning` enable button. + - We recommend enabling "Push protection" for blocking commits containing secrets + - To view Secret scanning alerts: + - Navigate to the repository main page. + - Click on the `Security` tab and select `Secret scanning alerts`. + +## Frequently Asked Questions (FAQ) + +- **Q: Can these security features be used outside of GitHub?** + + A: This guide specifically focuses on GitHub’s ecosystem. While some tools might have external equivalents, the integrations and configurations here are GitHub-specific. + +- **Q: Are these security features available on GitHub Enterprise?** + + A: It depends on your institution's particular version of GitHub deployed. You'll have to check your Settings tab to view the features that are provided. GitHub.com is the most up-to-date version we recommend for. + +- **Q: If I receive security alerts, what should I do and how soon should I act?** + + A: When you receive a security alert, it indicates a potential vulnerability in your repository. First, review the details of the alert to understand the severity and the affected component. Address critical vulnerabilities immediately, as they can pose a significant risk to your project. For less severe alerts, plan to address them in a timely manner. Always keep in mind that the sooner you act on security alerts, the better you can protect your code and users from potential threats. + +## Credits + +**Authorship:** +- John Engelke [@jpl-jengelke](http://github.com/jpl-jengelke/) +- Rishi Verma [@riverma](http://github.com/riverma/) + +**Acknowledgements:** +- GitHub for providing the security features and related documentation. See [GitHub’s Security Features](https://docs.github.com/en/code-security) to access an overview of the suite of security features GitHub provides for repositories. +- [OWASP DevSecOps Guideline](https://owasp.org/www-project-devsecops-guideline/latest/) for providing a Shift Left strategy to secure all phases of development. + +## Feedback and Contributions + +We welcome feedback and contributions to help improve and grow this guide. Please see our [contribution guidelines](https://nasa-ammos.github.io/slim/docs/contribute/contributing/). diff --git a/docs/guides/software-lifecycle/security/secrets-detection/README.md b/docs/guides/software-lifecycle/security/secrets-detection/README.md index ea961bf72..288c1c6e2 100644 --- a/docs/guides/software-lifecycle/security/secrets-detection/README.md +++ b/docs/guides/software-lifecycle/security/secrets-detection/README.md @@ -1,437 +1,291 @@ # Secrets Detection -We recommend [detect-secrets](https://github.com/Yelp/detect-secrets) to identify secure information included in source controlled files. Its prowess lies in its extensible Python plugin API, which allows custom rules and heuristics to tackle a broad spectrum of secrets. Designed to scan the project's current state rather than the entire git history, -it operates swiftly, making it ideal for continuous integration pipelines. Leveraging the concept of a "baseline file" (`.secrets.baseline`), it enables easy handling of known secrets and false positives, facilitating its gradual integration into existing projects. - - - - - -Our application of `detect-secrets` embraces a tri-layered approach, bolstered by customized plugins ([full list of plugins available here](https://github.com/NASA-AMMOS/slim-detect-secrets/tree/exp#viewing-all-enabled-plugins)), to provide robust protection against potential secret leaks at the earliest stage. -This page proposes three layers of secret scanning to help prevent secrets from being leaked on GitHub - -Three layers of protection are: -1. Client-side full scan of existing code base -2. Client-side scan of updated code upon Git commit -3. Server-side push to GitHub.com from client - -Each layer has its own advantages and disadvantages. The full use of these three layers of protection is recommended to minimize human negligence. -```mermaid -flowchart TB - User([fa:fa-user User]) - - subgraph UserWorkflow["User Workflow to Secure Secrets"] - Layer1["Layer 1: Full scan (client-side)"] - Layer2["Layer 2: Git commit scan (client-side)"] - Layer3["Layer 3: GitHub.com (server-side)"] - - Layer1 -->|If Secrets Detected| Clean1[Clean local file directly.] - Layer2 -->|If Secrets Detected| Clean2[Clean local file directly.
Don't need to worry about cleaning commit history] - Layer3 -->|If Secrets Detected| Clean3[Purge or Fix the commit manually] - - SaveTime["It saves your time. And secrets are safe from GitHub"] - Clean1 --> SaveTime - Clean2 --> SaveTime - - Secure["Only GitHub-Protected branch is in safe.
Secrets are leaked on other branch before cleaning"] - Clean3--> Secure - end - - User -->|At least use| Layer1 - User -->|Helpful to use| Layer2 - User -->|Optional to use| Layer3 - - style User fill:#F6F5F3,stroke:#333,stroke-width:1px - style UserWorkflow fill:#AF7AC5,stroke:#333,stroke-width:2px - style Layer1 fill:#F3B044,stroke:#333,stroke-width:2px,stroke-dasharray: 5 5 - style Layer2 fill:#F3B044,stroke:#333,stroke-width:2px,stroke-dasharray: 5 5 - style Layer3 fill:#F3B044,stroke:#333,stroke-width:2px,stroke-dasharray: 5 5 - style Clean1 fill:#5A88ED,stroke:#333,stroke-width:2px - style Clean2 fill:#5A88ED,stroke:#333,stroke-width:2px - style Clean3 fill:#5A88ED,stroke:#333,stroke-width:2px - style SaveTime fill:#5ABF9B,stroke:#333,stroke-width:2px - style Secure fill:#AF3034,stroke:#333,stroke-width:2px - -``` -> **Note**: Below three layers, are running on experimental version [slim-detect-secrets](https://github.com/NASA-AMMOS/slim-detect-secrets/tree/exp) which supports additional secret detection [plugins](https://github.com/NASA-AMMOS/slim-detect-secrets/tree/exp#viewing-all-enabled-plugins). -> -> They are: -> > * AWS sensitive information -> > * Public IP Address -> > * Absolute Path -> > * Email Address -> > -> > Link to their [implementation](https://github.com/NASA-AMMOS/slim-detect-secrets/tree/exp/detect_secrets/plugins) and [test suites](https://github.com/NASA-AMMOS/slim-detect-secrets/tree/exp/tests/plugins) -> -> It is being tested by both [NASA-AMMOS/slim](https://github.com/NASA-AMMOS/slim) team and [Yelp/detect-secrets](https://github.com/Yelp/detect-secrets) team. -> Eventually, it will be merged into Yelp/detect-secrets. -> -> At that time, this document will be updated to use the official version of detect-secrets. - -## Layer 1: Full Scan and Audit (Client-side) - -The first layer initiates a direct scan on the developer's local environment. This is achieved through the `detect-secrets` tool, which scans the entire codebase and outputs a new baseline file containing detected secrets. The developer can then audit this file to view detailed information about detected secrets. - -```mermaid -sequenceDiagram - participant Dev as Developer - participant Env as Local Environment - participant DS as Detect-Secrets - participant File as Baseline File - participant Audit as Audit Tool - - Note over Dev,Env: Developer initiates a direct scan for secrets - Dev->>+Env: Triggers direct scan - Env->>+DS: Requests scan on the codebase - DS->>DS: Performs secret scanning - DS->>File: Generates new baseline file - File->>DS: Acknowledges file creation - DS-->>-Env: Returns scan results and new baseline file - Env-->>Dev: Presents scan results and new baseline file - Note over Dev,File: Developer may audit the new baseline file - Dev->>Audit: Initiates audit on the new baseline file - Audit->>File: Fetches details from the baseline file - File->>Audit: Returns secret details - Audit-->>Dev: Presents detailed information of detected secrets - -``` -Starter Kit: -1. Install experimental version of [slim-detect-secrets](https://github.com/NASA-AMMOS/slim-detect-secrets/tree/exp) -```bash -pip install git+https://github.com/NASA-AMMOS/slim-detect-secrets.git@exp -``` - -2. Scan all local files from current directory and output the result as a baseline file -```bash -detect-secrets scan ./ --all-files --disable-plugin AbsolutePathDetectorExperimental --exclude-files '.secrets.*' --exclude-files '.git*' > .secrets.baseline -``` -Here it scans all the local files from current directory, but excludes `.git` directory and `.secrets` baseline files from scanning to reduce false positive. Make modifications when necessary. - -3. Check result in the baseline file -```bash -cat .secrets.baseline -``` -> This command is supported in Unix-like system. For Windows, you can use other command, such as `type .secrets.baseline` -If any secrets are detected, the result will be located at the "results:" of the file. - -For example, -```json -"results": { - "Sample/sample-develop.sh": [ - { - "type": "AWS Sensitive Information", - "filename": "Sample/sample-develop.sh", - "hashed_secret": "d3f72b97cd8756fe12345678bdf96aef1ac23b7d", - "is_verified": false, - "line_number": 39 -}, -``` -Only line number is visible through this approach. You can check them manually in the file, or use the following audit tool to conveniently view the actual secret. - -4. Analyze results by `audit` tool -```bash -detect-secrets audit .secrets.baseline -``` -> detect-secrets audit tool can provide you an interactive interface to view the actual secret based on the line number -> and label it as false positive or true positive. - -For example, - -
Guide to identify and automatically prevent leaking of sensitive information into your codebase.+ +## Introduction + +**Background**: Sensitive information like API keys, passwords, or tokens may inadvertently be getting committed into your repository. Such slip-ups can pose significant security risks. We recommend not only scanning for sensitive information recurringly, but preventing sensitive information from getting infused in the first place. To support these goals, we recommend a tool called [detect-secrets](https://github.com/Yelp/detect-secrets) to mitigate these risks. It scans for common sensitive information categories like passwords, high-entropy entries that may contain sensitive information, and a plugin system that supports customization. It's compatible for use in continuous integration pipelines and execution on local-developer machines. It has a "baseline file" approach, leveraging `.secrets.baseline`, that streamlines the management of legitimate secrets and reduces false positives. This helps both new and established projects detect and prevent secrets getting into source code. + +**Use Cases**: +- Finding and preventing commits of sensitive information such as: + - Username / passwords + - High entropy strings + - IP addresses + - E-mail addresses + - AWS sensitive information +- Scanning local client repositories for exposed sensitive information _before_ making them public. +- Preventing secrets from being committed to a local repository using pre-commit hooks. +- Implementing a safety net in continuous integration (CI) pipelines using GitHub Actions to catch inadvertent secret commits. +- Streamlining the management of known secrets and false positives during codebase audits. + +--- + +## Prerequisites +To get the most out of `detect-secrets`, you'll need: + +* Python `pip` tool. +* (Optional) Familiarity with Python for potential custom plugin development. +* (Optional) A GitHub repository supporting GitHub Actions + +--- + + + +## Quick Start + +1. Install slim-detect-secrets: + + > ℹ️ **Note:** the SLIM project has customized the Detect Secrets tool to identify additional sensitive keywords such as IP addresses, file paths, and AWS information. These additions are currently [under review](https://github.com/Yelp/detect-secrets/pulls/perryzjc) by the detect-secrets team for merger into the main codebase of the tool. Until then, we recommend using our SLIM fork per below. -**Warning**: Adding your `.secrets.baseline` file to your local Git and pushing changes to a remote without following the above directions could create a security risk by sharing the sensitive parts of your security scan with the outside world! - -5. Commit your changes - -Now, you can commit your changes as usual. If any **new secrets** are detected, the commit will be prevented and the secrets will be reported. - -For example, - -
-
-> **Note**: The pre-commit hook blocks a commit by comparing new secrets with the results in the `.secrets.baseline` file. If new secrets are introduced, the hook will report them, but it does not automatically update the `.secrets.baseline` file. To update the baseline file with newly introduced secrets, you need to re-run the scan command in Layer 1 (step 2) and generate a new baseline file.
-
-> **Note**: during commit checks, detect secrets may not display all secrets present within a single file during a single scan. This can be to [minimize noise](https://github.com/Yelp/detect-secrets/blob/master/docs/design.md#potentialsecret), among other reasons. Thus if you have multiple violations of different types of secrets per file, multiple independent commits may be necessary to help identify all violations.
->
-> You can create an empty result baseline file by running this command at a directory without secrets.
-
-## Layer 3: Server-side Push to GitHub.com
-The final layer of our solution is a server-side pre-commit scan powered by [GitHub Action](https://github.com/features/actions). This scan is triggered whenever a developer pushes to a branch or creates a pull request. If the scan detects any new secrets, it can generate a not detailed report compared to layer 2 (for security concern), email to the developer, and report a status check to GitHub. The status check will prevent the developer from merging the pull request or pushing to the **protected** branch. This layer protects the protected branch from being polluted by secrets, but secrets can still be pushed to other branches.
-
-```mermaid
-sequenceDiagram
- participant User as Developer
- participant GH as GitHub
- participant Workflow as detect-secrets.yaml
- participant GA as GitHub Action
- participant DS as Detect-Secrets
-
- Note over User,GH: Developer creates pull request or pushes to branch
- User->>+GH: Creates pull request / pushes to branch
- GH->>+Workflow: Triggers GitHub Action workflow
- Workflow->>GA: Sets up and runs Detect-Secrets scan
- GA->>DS: Requests secret scan
- DS->>DS: Scans repository for secrets
- alt Secrets Detected
- DS-->>GA: Returns detected secrets
- GA-->>GH: Fails status check
- GH-->>User: Prevents merge / push & sends email notification
- else No Secrets Detected
- DS-->>GA: Returns clean result
- GA-->>GH: Passes status check
- GH-->>User: Allows merge / push
- end
-
-```
-Starter Kit:
-1. Create a workflow file `detect-secrets.yaml` in `.github/workflows` directory from your repository root.
-```yaml
-name: Secret Detection Workflow
-on:
- push:
- branches:
- - main
- pull_request:
- branches:
- - main
-
-jobs:
- secret-detection:
- runs-on: ubuntu-latest
- steps:
- - name: Checkout code
- uses: actions/checkout@v2
-
- - name: Install necessary packages
- run: |
- # This is the experimental version of slim-detect-secrets.
- # It will be updated to the official Yelp/detect-secrets version once the customized plugins are merged.
- # For more information about slim/detect-secrets, check the following:
- # 1. https://github.com/NASA-AMMOS/slim-detect-secrets/tree/exp
- # 2. https://github.com/NASA-AMMOS/slim/blob/d20ee6134a0dc0e0dab11d2d2570e358ef7e4550/continuous-testing/starter-kits/README.md#detect-secrets
- pip install git+https://github.com/NASA-AMMOS/slim-detect-secrets.git@exp
- # This library is used for JSON operations.
- pip install jq
-
- - name: Create an initial .secrets.baseline if .secrets.baseline does not exist
- run: |
- if [ ! -f .secrets.baseline ]; then
- # This generated baseline file will only be temporarily available on the GitHub side and will not appear in the user's local files.
- # Scanning an empty folder to generate an initial .secrets.baseline without secrets in the results.
- echo "⚠️ No existing .secrets.baseline file detected. Creating a new blank baseline file."
- mkdir empty-dir
- detect-secrets scan empty-dir > .secrets.baseline
- echo "✅ Blank .secrets.baseline file created successfully."
- rm -r empty-dir
- else
- echo "✅ Existing .secrets.baseline file detected. No new baseline file will be created."
- fi
-
- - name: Scan repository for secrets
- run: |
- # scripts to scan repository for new secrets
-
- # backup the list of known secrets
- cp .secrets.baseline .secrets.new
-
- # find the secrets in the repository
- detect-secrets scan --disable-plugin AbsolutePathDetectorExperimental --baseline .secrets.new --exclude-files '.secrets.*' --exclude-files '.git*'
-
- # if there is any difference between the known and newly detected secrets, break the build
- # Function to compare secrets without listing them
- compare_secrets() { diff <(jq -r '.results | keys[] as $key | "\($key),\(.[$key] | .[] | .hashed_secret)"' "$1" | sort) <(jq -r '.results | keys[] as $key | "\($key),\(.[$key] | .[] | .hashed_secret)"' "$2" | sort) >/dev/null; }
-
- # Check if there's any difference between the known and newly detected secrets
- if ! compare_secrets .secrets.baseline .secrets.new; then
- echo "⚠️ Attention Required! ⚠️" >&2
- echo "New secrets have been detected in your recent commit. Due to security concerns, we cannot display detailed information here and we cannot proceed until this issue is resolved." >&2
- echo "" >&2
- echo "Please follow the steps below on your local machine to reveal and handle the secrets:" >&2
- echo "" >&2
- echo "1️⃣ Run the 'detect-secrets' tool on your local machine. This tool will identify and clean up the secrets. You can find detailed instructions at this link: https://nasa-ammos.github.io/slim/continuous-testing/starter-kits/#detect-secrets" >&2
- echo "" >&2
- echo "2️⃣ After cleaning up the secrets, commit your changes and re-push your update to the repository." >&2
- echo "" >&2
- echo "Your efforts to maintain the security of our codebase are greatly appreciated!" >&2
- exit 1
- fi
-
-```
-**Explanation**
-
-The Detect Secrets Action follows these steps to ensure the security of your code:
-
-- **Checkout Code**: Utilizes GitHub's checkout action to access the repository. This is the code that will be scanned for secrets.
-- **Install Necessary Packages**: Deploys the required Python packages, including the experimental version of `slim-detect-secrets` and `jq`. These packages enable the primary functionality of the Action.
-- **Check Existence of .secrets.baseline**: Ensures the Action remains operational even if no baseline file exists yet. If the `.secrets.baseline` file is not found, the action creates an initial baseline file by scanning an empty directory.
-- **Scan Repository for Secrets**: In this step, the Action backs up the list of known secrets and scans the repository for any new secrets. The scan excludes files starting with '.secrets.' and '.git'. The 'compare_secrets' function is used to identify any differences between the known secrets and newly detected ones. If new secrets are detected, the build fails, and the user is guided to clean up the secrets using the `detect-secrets` tool.
-
-After this, GitHub will automatically run the workflow when you push to the branch or create a pull request.
-
-This workflow will run the `detect-secrets` tool on the GitHub server. If any new secrets are detected, it will:
-- Fail the status check
-
- Recommend to manully double check detected files
due to "minimize noise" feature from detect-secrets - Dev->>Dev: Clean Commit History - Note over Dev: If a secret has already been committed, refer:
https://help.github.com/articles/removing-sensitive-data-from-a-repository - Dev->>L2: Set Up Git Commit Scan - Note over Dev, L2: Minimizes chances of pushing secrets
Easier to clean local files than GitHub commit history - Dev->>L1: Use Full Scan & Audit at Each Stage - Note over Dev, L1: Assists in generating, updating or analyzing baseline file for L2 and L3 - Dev->>L3: Retry Push/Merge to Main Branch - else No Secrets Detected - DS-->>GH: No Secrets Detected - GH->>Dev: Allows Push/Merge to Main Branch - end - -``` - -## More Configurations - -Check out -1. [detect-secrets](https://github.com/Yelp/detect-secrets) -2. [pre-commit](https://pre-commit.com/) + ```bash + pip install git+https://github.com/NASA-AMMOS/slim-detect-secrets.git@exp + ``` + +2. Execute a baseline scan: + + ```bash + detect-secrets scan --all-files --disable-plugin AbsolutePathDetectorExperimental --exclude-files '\.secrets.*' --exclude-files '\.git*' > .secrets.baseline + ``` + +3. Review the `.secrets.baseline` file for any detected secrets via an audit: + + ```bash + detect-secrets audit .secrets.baseline + ``` + +Additional steps like whitelisting, establishing pre-commit hooks or enabling further automation are covered in detail below. + +--- + +## Step-by-Step Guide + +There are three recommended layers of protection we suggest you enable to ensure maximum security. Please see the below sections for details. + +### Table of Contents +- [Secrets Detection](#secrets-detection) + - [Introduction](#introduction) + - [Prerequisites](#prerequisites) + - [Quick Start](#quick-start) + - [Step-by-Step Guide](#step-by-step-guide) + - [Table of Contents](#table-of-contents) + - [Layer 1: Full Scan and Audit (Client-side)](#layer-1-full-scan-and-audit-client-side) + - [Steps](#steps) + - [Layer 2: Git Commit Scan (Client-side)](#layer-2-git-commit-scan-client-side) + - [Steps](#steps-1) + - [Layer 3: Server-side Push to GitHub.com](#layer-3-server-side-push-to-githubcom) + - [Steps](#steps-2) + - [Frequently Asked Questions (FAQ)](#frequently-asked-questions-faq) + - [Credits](#credits) + - [Feedback and Contributions](#feedback-and-contributions) + +### Layer 1: Full Scan and Audit (Client-side) +This layer directly scans the developer's local environment using the `detect-secrets` tool. After scanning, a baseline file containing detected secrets is generated. Developers can audit this file for detailed information on detected secrets. + +#### Steps +1. **Installation** + - Install the experimental version of [slim-detect-secrets](https://github.com/NASA-AMMOS/slim-detect-secrets/tree/exp). + ```bash + pip install git+https://github.com/NASA-AMMOS/slim-detect-secrets.git@exp + ``` + +2. **Scanning** + - Scan all local files from the current directory and output results to a baseline file. + ```bash + detect-secrets scan --all-files --disable-plugin AbsolutePathDetectorExperimental --exclude-files '\.secrets.*' --exclude-files '\.git*' > .secrets.baseline + ``` + +3. **Checking Results** + - View the results in the baseline file. + ```bash + cat .secrets.baseline + ``` + +4. **Analysis** + - Analyze results using the `audit` tool. + ```bash + detect-secrets audit .secrets.baseline + ``` + +[View more on Auditing Secrets in Baseline](https://github.com/Yelp/detect-secrets#auditing-secrets-in-baseline) + +> ℹ️ **Note**: If you've marked any secrets as true positives, make sure to remove all references to these secrets and rerun a full scan. + +### Layer 2: Git Commit Scan (Client-side) +This layer represents a prevention mechanism in the local developer environment that scans changes when a developer tries to commit and if new secrets are detected, the commit is blocked. + +To support this strategy, we recommend the installation of another third party tool called [pre-commit](https://pre-commit.com/#install), which is integral in allowing specialized plugins to run during the local developer's commit phase of using Git. It allows detect-secrets to prevent commits that are flagged with sensitive information. + +#### Steps +1. **Installation** + + - Install [pre-commit](https://pre-commit.com/#install). + + ```bash + pip install pre-commit + ``` + +2. **Configuration** + - Create a `.pre-commit-config.yaml` configuration file with the below contents. + + ```yaml + repos: + - repo: https://github.com/NASA-AMMOS/slim-detect-secrets + # using commit id for now, will change to tag when official version is released + rev: 91e097ad4559ae6ab785c883dc5ed989202c7fbe + hooks: + - id: detect-secrets + args: + - '--baseline' + - '.secrets.baseline' + - '--exclude-files' + - '\.git*' + - '--exclude-files' + - '\.secrets.*' + ``` + +3. **Hook Installation** + - Install the pre-commit hook into your local environment, ensuring the hook gets invoked during local git commits. + + ```bash + pre-commit install + ``` + +4. **Committing Changes** + - Commit changes. If new secrets are detected, the commit will be blocked. + +> ℹ️ **Note**: The pre-commit hook does not automatically update the `.secrets.baseline` file. Update it by re-running the scan command. + +### Layer 3: Server-side Push to GitHub.com + +> ⚠️ Warning: the strategy recommended below is currently experimental and may not work as intended. Use with caution. + +This strategy provides a final layer of protection by scanning server-side commits for sensitive information during pull request creation. It leverages the [pre-commit](https://pre-commit.com/#install) tool and [GitHub Action](https://github.com/features/actions). The scan is triggered during a push or pull request and any detected new secrets are reported, while merges or pushes to protected branches are prevented. + +#### Steps +1. **Workflow Creation** + - The first step is to create a `detect-secrets.yaml` workflow file in the `.github/workflows` directory to define the GitHub action. Copy and paste the below while ensuring the correct branch of your codebase is referenced. + + ```yaml + name: Secret Detection Workflow + on: + push: + branches: + - main + pull_request: + branches: + - main + + jobs: + secret-detection: + runs-on: ubuntu-latest + steps: + - name: Checkout code + uses: actions/checkout@v2 + + - name: Install necessary packages + run: | + # This is the experimental version of slim-detect-secrets. + # It will be updated to the official Yelp/detect-secrets version once the customized plugins are merged. + # For more information about slim/detect-secrets, check the following: + # 1. https://github.com/NASA-AMMOS/slim-detect-secrets/tree/exp + # 2. https://github.com/NASA-AMMOS/slim/blob/d20ee6134a0dc0e0dab11d2d2570e358ef7e4550/continuous-testing/starter-kits/README.md#detect-secrets + pip install git+https://github.com/NASA-AMMOS/slim-detect-secrets.git@exp + # This library is used for JSON operations. + pip install jq + + - name: Create an initial .secrets.baseline if .secrets.baseline does not exist + run: | + if [ ! -f .secrets.baseline ]; then + # This generated baseline file will only be temporarily available on the GitHub side and will not appear in the user's local files. + # Scanning an empty folder to generate an initial .secrets.baseline without secrets in the results. + echo "⚠️ No existing .secrets.baseline file detected. Creating a new blank baseline file." + mkdir empty-dir + detect-secrets scan empty-dir > .secrets.baseline + echo "✅ Blank .secrets.baseline file created successfully." + rm -r empty-dir + else + echo "✅ Existing .secrets.baseline file detected. No new baseline file will be created." + fi + + - name: Scan repository for secrets + run: | + echo "✅ Scanning repository for new secrets" + + # backup the list of known secrets + cp .secrets.baseline .secrets.new + echo "✅ Created backup of known secrets" + + # find the secrets in the repository + detect-secrets scan --disable-plugin AbsolutePathDetectorExperimental --baseline .secrets.new --exclude-files '\.secrets.*' --exclude-files '\.git*' + echo "✅ Scanned repository for secrets" + + # if there is any difference between the known and newly detected secrets, break the build + # Function to compare secrets without listing them + compare_secrets() { diff <(jq -r '.results | keys[] as $key | "\($key),\(.[$key] | .[] | .hashed_secret)"' "$1" | sort) <(jq -r '.results | keys[] as $key | "\($key),\(.[$key] | .[] | .hashed_secret)"' "$2" | sort) >/dev/null; } + echo "✅ Run comparison against baseline secrets file" + + # Check if there's any difference between the known and newly detected secrets + if ! compare_secrets .secrets.baseline .secrets.new; then + echo "⚠️ Attention Required! ⚠️" >&2 + echo "New secrets have been detected in your recent commit. Due to security concerns, we cannot display detailed information here and we cannot proceed until this issue is resolved." >&2 + echo "" >&2 + echo "Please follow the steps below on your local machine to reveal and handle the secrets:" >&2 + echo "" >&2 + echo "1️⃣ Run the 'detect-secrets' tool on your local machine. This tool will identify and clean up the secrets. You can find detailed instructions at this link: https://nasa-ammos.github.io/slim/continuous-testing/starter-kits/#detect-secrets" >&2 + echo "" >&2 + echo "2️⃣ After cleaning up the secrets, commit your changes and re-push your update to the repository." >&2 + echo "" >&2 + echo "Your efforts to maintain the security of our codebase are greatly appreciated!" >&2 + exit 1 + else + echo "✅ No new secrets detected" + fi + ``` + > ℹ️ Explanation: The GitHub Action checks out code, installs necessary packages, checks for a baseline file, and scans the repository for secrets. If new secrets are detected, the build fails and provides guidance. + +After setting this up, GitHub will run the workflow during pushes or pull requests. If any new secrets are detected, the status check will fail and the user will be notified in the pull request. + +> ⚠️ Warning: the check ensures the specific line of code that may have sensitive information is not disclosed publicly in the GitHub Action logs, only a yes / no indication if sensitive information was detected. That being said, it may not be too many steps for an attacker to identify sensitive information. Monitor your pull requests actively to respond and always ensure [Layer 1](#layer-1-full-scan-and-audit-client-side) and [Layer 2](#layer-2-git-commit-scan-client-side) are actively used by your team to prevent issues in the first place. + +--- + +### Frequently Asked Questions (FAQ) + +- Q: **If secrets are detected in my code, what should I do?** + + A: Follow these steps: + + - _Identify and Confirm:_ Review the identified secrets in the `.secrets.baseline` or any other report generated. Ensure that they are indeed secrets and not false positives. + - _Removal:_ Remove or replace all references to the detected secrets from your codebase. Ensure that no trace of the secret remains in the code, comments, or commit history. If you want to ignore the secret as a false positive during a pre-commit scan, you can follow directions [here](https://github.com/Yelp/detect-secrets#inline-allowlisting-1). + - _Rotation:_ If the detected secret was an API key, password, or any other form of authentication, consider it compromised. Rotate the secret immediately, i.e., generate a new secret/key and update it wherever required. + - _Rerun Scans:_ After you've made the necessary changes, run the `detect-secrets` tool again to ensure no secrets remain. + - _Commit Safely:_ When you're sure all secrets have been removed, you can safely commit your changes. Remember, the Git commit scan (Layer 2) and the server-side push scan (Layer 3) will provide additional layers of checks. + - _Educate and Prevent:_ To avoid such instances in the future, educate your team on the importance of not committing secrets and the potential risks associated with it. Consider adopting practices or tools that prevent the accidental inclusion of secrets in your codebase. + +- Q: **Does detect-secrets scan the entire git history?** + + A: No, it's designed to scan the current state of a project for efficiency. + +- Q: **Where can I find more configurations and options for detect-secrets?** + + A: Refer to the official documentation for [detect-secrets](https://github.com/Yelp/detect-secrets) and [pre-commit](https://pre-commit.com/). + + +--- + +## Credits + +**Authorship**: +- Jingchao Zhong [@perryzjc](https://github.com/perryzjc) +- Rishi Verma [@riverma](https://github.com/riverma) +- John Engelke [@jpl-jengelke](http://github.com/jpl-jengelke) + +**Acknowledgements**: +- [Yelp's detect-secrets maintainers](https://github.com/Yelp/detect-secrets) +- [@nutjob4life](https://github.com/nutjob4life) for detect-secrets usage tips + +--- + +## Feedback and Contributions + +We value your feedback and contributions. Enhance and expand this guide by referring to our [contribution guidelines](https://nasa-ammos.github.io/slim/docs/contribute/contributing/). diff --git a/docusaurus.config.js b/docusaurus.config.js index 628a1182b..c6a4dc8b8 100644 --- a/docusaurus.config.js +++ b/docusaurus.config.js @@ -8,7 +8,7 @@ const darkCodeTheme = require('prism-react-renderer/themes/dracula'); const config = { title: 'SLIM', tagline: 'Software Lifecycle Improvement & Modernization (SLIM)', - favicon: 'img/slim-favicon.ico', + favicon: '/img/favicon.ico', // Set the production url of your site here @@ -143,14 +143,16 @@ const config = { darkTheme: darkCodeTheme, }, colorMode: { - disableSwitch: true + disableSwitch: false, + defaultMode: 'dark', + respectPrefersColorScheme: false }, }), markdown: { mermaid: true, }, - themes: ['@docusaurus/theme-mermaid'], + themes: ['@docusaurus/theme-mermaid'] }; module.exports = config; diff --git a/src/components/FacetedPanels.js b/src/components/FacetedPanels.js index 0093b0a85..6d06061f7 100644 --- a/src/components/FacetedPanels.js +++ b/src/components/FacetedPanels.js @@ -2,7 +2,7 @@ import React, { useState, useEffect } from 'react'; import { Container, Row, Col, Form, Card, Dropdown, Badge, Button, ListGroup, ListGroupItem, Navbar, Nav, Glyphicon } from 'react-bootstrap'; import 'bootstrap/dist/css/bootstrap.min.css'; -const Panel = ({ title, uri, tags, lastUpdated, description }) => ( +const Panel = ({ title, uri, tags, description }) => (
{description}
-