diff --git a/404.html b/404.html index 32e137066..bd41842a7 100644 --- a/404.html +++ b/404.html @@ -5,13 +5,13 @@ Page Not Found | SLIM - +
Skip to main content

Page Not Found

We could not find what you were looking for.

Please contact the owner of the site that linked you to the original URL and let them know their link is broken.

- + \ No newline at end of file diff --git a/assets/js/684aec4d.88251110.js b/assets/js/684aec4d.88251110.js new file mode 100644 index 000000000..98961b9c7 --- /dev/null +++ b/assets/js/684aec4d.88251110.js @@ -0,0 +1 @@ +"use strict";(self.webpackChunkdocusaurus=self.webpackChunkdocusaurus||[]).push([[4103],{3905:(e,t,n)=>{n.d(t,{Zo:()=>p,kt:()=>h});var a=n(7294);function i(e,t,n){return t in e?Object.defineProperty(e,t,{value:n,enumerable:!0,configurable:!0,writable:!0}):e[t]=n,e}function r(e,t){var n=Object.keys(e);if(Object.getOwnPropertySymbols){var a=Object.getOwnPropertySymbols(e);t&&(a=a.filter((function(t){return Object.getOwnPropertyDescriptor(e,t).enumerable}))),n.push.apply(n,a)}return n}function s(e){for(var t=1;t=0||(i[n]=e[n]);return i}(e,t);if(Object.getOwnPropertySymbols){var r=Object.getOwnPropertySymbols(e);for(a=0;a=0||Object.prototype.propertyIsEnumerable.call(e,n)&&(i[n]=e[n])}return i}var o=a.createContext({}),c=function(e){var t=a.useContext(o),n=t;return e&&(n="function"==typeof e?e(t):s(s({},t),e)),n},p=function(e){var t=c(e.components);return a.createElement(o.Provider,{value:t},e.children)},u="mdxType",m={inlineCode:"code",wrapper:function(e){var t=e.children;return a.createElement(a.Fragment,{},t)}},d=a.forwardRef((function(e,t){var n=e.components,i=e.mdxType,r=e.originalType,o=e.parentName,p=l(e,["components","mdxType","originalType","parentName"]),u=c(n),d=i,h=u["".concat(o,".").concat(d)]||u[d]||m[d]||r;return n?a.createElement(h,s(s({ref:t},p),{},{components:n})):a.createElement(h,s({ref:t},p))}));function h(e,t){var n=arguments,i=t&&t.mdxType;if("string"==typeof e||i){var r=n.length,s=new Array(r);s[0]=d;var l={};for(var o in t)hasOwnProperty.call(t,o)&&(l[o]=t[o]);l.originalType=e,l[u]="string"==typeof e?e:i,s[1]=l;for(var c=2;c{n.r(t),n.d(t,{assets:()=>o,contentTitle:()=>s,default:()=>m,frontMatter:()=>r,metadata:()=>l,toc:()=>c});var a=n(7462),i=(n(7294),n(3905));const r={},s="Secrets Detection",l={unversionedId:"guides/software-lifecycle/security/secrets-detection/README",id:"guides/software-lifecycle/security/secrets-detection/README",title:"Secrets Detection",description:"Guide to identify and automatically prevent leaking of sensitive information into your codebase.",source:"@site/docs/guides/software-lifecycle/security/secrets-detection/README.md",sourceDirName:"guides/software-lifecycle/security/secrets-detection",slug:"/guides/software-lifecycle/security/secrets-detection/",permalink:"/slim/docs/guides/software-lifecycle/security/secrets-detection/",draft:!1,editUrl:"https://github.com/nasa-ammos/slim/tree/main/docs/guides/software-lifecycle/security/secrets-detection/README.md",tags:[],version:"current",frontMatter:{},sidebar:"guidesSidebar",previous:{title:"GitHub Security Best Practices",permalink:"/slim/docs/guides/software-lifecycle/security/github-security/"},next:{title:"Continuous Integration",permalink:"/slim/docs/guides/software-lifecycle/continuous-integration/"}},o={},c=[{value:"Introduction",id:"introduction",level:2},{value:"Prerequisites",id:"prerequisites",level:2},{value:"Quick Start",id:"quick-start",level:2},{value:"Step-by-Step Guide",id:"step-by-step-guide",level:2},{value:"Table of Contents",id:"table-of-contents",level:3},{value:"Layer 1: Full Scan and Audit (Client-side)",id:"layer-1-full-scan-and-audit-client-side",level:3},{value:"Steps",id:"steps",level:4},{value:"Layer 2: Git Commit Scan (Client-side)",id:"layer-2-git-commit-scan-client-side",level:3},{value:"Steps",id:"steps-1",level:4},{value:"Layer 3: Server-side Push to GitHub.com",id:"layer-3-server-side-push-to-githubcom",level:3},{value:"Steps",id:"steps-2",level:4},{value:"Frequently Asked Questions (FAQ)",id:"frequently-asked-questions-faq",level:3},{value:"Credits",id:"credits",level:2},{value:"Feedback and Contributions",id:"feedback-and-contributions",level:2}],p={toc:c},u="wrapper";function m(e){let{components:t,...n}=e;return(0,i.kt)(u,(0,a.Z)({},p,n,{components:t,mdxType:"MDXLayout"}),(0,i.kt)("h1",{id:"secrets-detection"},"Secrets Detection"),(0,i.kt)("pre",{align:"center"},"Guide to identify and automatically prevent leaking of sensitive information into your codebase."),(0,i.kt)("h2",{id:"introduction"},"Introduction"),(0,i.kt)("p",null,(0,i.kt)("strong",{parentName:"p"},"Background"),": Sensitive information like API keys, passwords or tokens may be inadvertently committed to your repository. Such slip-ups can pose significant security risks. We recommend not only recurring scans for sensitive information, but proactively preventing sensitive information from getting infused. To support these goals, we recommend a tool called ",(0,i.kt)("a",{parentName:"p",href:"https://github.com/Yelp/detect-secrets"},"detect-secrets"),' that mitigates these risks. It scans for common sensitive information categories like passwords and other high-entropy values that contain sensitive data. It also provides a plugin system to support additional customization. It\'s fast for use in continuous integration pipelines and quickly executes on local-developer machines. It uses a "baseline file" approach, leveraging ',(0,i.kt)("inlineCode",{parentName:"p"},".secrets.baseline"),", that streamlines management of legitimate secrets and reduces false positives. This helps both new and established projects detect and prevent secrets from entering the code base."),(0,i.kt)("p",null,(0,i.kt)("strong",{parentName:"p"},"Use Cases"),":"),(0,i.kt)("ul",null,(0,i.kt)("li",{parentName:"ul"},"Finding and preventing commits of sensitive information such as:",(0,i.kt)("ul",{parentName:"li"},(0,i.kt)("li",{parentName:"ul"},"Username / passwords"),(0,i.kt)("li",{parentName:"ul"},"High entropy strings"),(0,i.kt)("li",{parentName:"ul"},"IP addresses"),(0,i.kt)("li",{parentName:"ul"},"E-mail addresses"),(0,i.kt)("li",{parentName:"ul"},"AWS sensitive information"))),(0,i.kt)("li",{parentName:"ul"},"Scanning local client repositories for exposed sensitive information ",(0,i.kt)("em",{parentName:"li"},"before")," making them public."),(0,i.kt)("li",{parentName:"ul"},"Preventing secrets from being committed to a local repository using pre-commit hooks."),(0,i.kt)("li",{parentName:"ul"},"Implementing a safety net in continuous integration (CI) pipelines using GitHub Actions to catch inadvertent secret commits."),(0,i.kt)("li",{parentName:"ul"},"Streamlining the management of known secrets and false positives during codebase audits.")),(0,i.kt)("hr",null),(0,i.kt)("h2",{id:"prerequisites"},"Prerequisites"),(0,i.kt)("p",null,"To get the most out of ",(0,i.kt)("inlineCode",{parentName:"p"},"detect-secrets"),", you'll need:"),(0,i.kt)("ul",null,(0,i.kt)("li",{parentName:"ul"},"Python 3 with the ",(0,i.kt)("inlineCode",{parentName:"li"},"pip")," tool installed."),(0,i.kt)("li",{parentName:"ul"},"(Optional) Familiarity with Python for potential custom plugin development."),(0,i.kt)("li",{parentName:"ul"},"(Optional) A GitHub repository supporting GitHub Actions.")),(0,i.kt)("hr",null),(0,i.kt)("h2",{id:"quick-start"},"Quick Start"),(0,i.kt)("ol",null,(0,i.kt)("li",{parentName:"ol"},(0,i.kt)("p",{parentName:"li"},"Install slim-detect-secrets:"),(0,i.kt)("blockquote",{parentName:"li"},(0,i.kt)("p",{parentName:"blockquote"},"\u2139\ufe0f ",(0,i.kt)("strong",{parentName:"p"},"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 ",(0,i.kt)("a",{parentName:"p",href:"https://github.com/Yelp/detect-secrets/pulls/perryzjc"},"under review")," by the detect-secrets team for merge into the tool's ",(0,i.kt)("inlineCode",{parentName:"p"},"main")," codebase. Until then we recommend using our SLIM fork as described below. ")),(0,i.kt)("pre",{parentName:"li"},(0,i.kt)("code",{parentName:"pre",className:"language-bash"},"pip install git+https://github.com/NASA-AMMOS/slim-detect-secrets.git@exp\n"))),(0,i.kt)("li",{parentName:"ol"},(0,i.kt)("p",{parentName:"li"},"Execute a baseline scan:"),(0,i.kt)("pre",{parentName:"li"},(0,i.kt)("code",{parentName:"pre",className:"language-bash"},"detect-secrets scan --all-files --disable-plugin AbsolutePathDetectorExperimental --exclude-files '\\.secrets.*' --exclude-files '\\.git*' > .secrets.baseline\n"))),(0,i.kt)("li",{parentName:"ol"},(0,i.kt)("p",{parentName:"li"},"Review the ",(0,i.kt)("inlineCode",{parentName:"p"},".secrets.baseline")," file for any detected secrets via an audit:"),(0,i.kt)("pre",{parentName:"li"},(0,i.kt)("code",{parentName:"pre",className:"language-bash"},"detect-secrets audit .secrets.baseline\n")))),(0,i.kt)("p",null,"Additional steps like whitelisting accepted values and false positives, establishing pre-commit hooks and/or enabling further automation are covered in detail below."),(0,i.kt)("hr",null),(0,i.kt)("h2",{id:"step-by-step-guide"},"Step-by-Step Guide"),(0,i.kt)("p",null,"There are three recommended layers of protection we suggest you enable to ensure comprehensive security. Please see below sections for further details. "),(0,i.kt)("h3",{id:"table-of-contents"},"Table of Contents"),(0,i.kt)("ul",null,(0,i.kt)("li",{parentName:"ul"},(0,i.kt)("a",{parentName:"li",href:"#secrets-detection"},"Secrets Detection"),(0,i.kt)("ul",{parentName:"li"},(0,i.kt)("li",{parentName:"ul"},(0,i.kt)("a",{parentName:"li",href:"#introduction"},"Introduction")),(0,i.kt)("li",{parentName:"ul"},(0,i.kt)("a",{parentName:"li",href:"#prerequisites"},"Prerequisites")),(0,i.kt)("li",{parentName:"ul"},(0,i.kt)("a",{parentName:"li",href:"#quick-start"},"Quick Start")),(0,i.kt)("li",{parentName:"ul"},(0,i.kt)("a",{parentName:"li",href:"#step-by-step-guide"},"Step-by-Step Guide"),(0,i.kt)("ul",{parentName:"li"},(0,i.kt)("li",{parentName:"ul"},(0,i.kt)("a",{parentName:"li",href:"#table-of-contents"},"Table of Contents")),(0,i.kt)("li",{parentName:"ul"},(0,i.kt)("a",{parentName:"li",href:"#layer-1-full-scan-and-audit-client-side"},"Layer 1: Full Scan and Audit (Client-side)"),(0,i.kt)("ul",{parentName:"li"},(0,i.kt)("li",{parentName:"ul"},(0,i.kt)("a",{parentName:"li",href:"#steps"},"Steps")))),(0,i.kt)("li",{parentName:"ul"},(0,i.kt)("a",{parentName:"li",href:"#layer-2-git-commit-scan-client-side"},"Layer 2: Git Commit Scan (Client-side)"),(0,i.kt)("ul",{parentName:"li"},(0,i.kt)("li",{parentName:"ul"},(0,i.kt)("a",{parentName:"li",href:"#steps-1"},"Steps")))),(0,i.kt)("li",{parentName:"ul"},(0,i.kt)("a",{parentName:"li",href:"#layer-3-server-side-push-to-githubcom"},"Layer 3: Server-side Push to GitHub.com"),(0,i.kt)("ul",{parentName:"li"},(0,i.kt)("li",{parentName:"ul"},(0,i.kt)("a",{parentName:"li",href:"#steps-2"},"Steps")))),(0,i.kt)("li",{parentName:"ul"},(0,i.kt)("a",{parentName:"li",href:"#frequently-asked-questions-faq"},"Frequently Asked Questions (FAQ)")))),(0,i.kt)("li",{parentName:"ul"},(0,i.kt)("a",{parentName:"li",href:"#credits"},"Credits")),(0,i.kt)("li",{parentName:"ul"},(0,i.kt)("a",{parentName:"li",href:"#feedback-and-contributions"},"Feedback and Contributions"))))),(0,i.kt)("h3",{id:"layer-1-full-scan-and-audit-client-side"},"Layer 1: Full Scan and Audit (Client-side)"),(0,i.kt)("p",null,"This layer directly scans the developer's local environment using the ",(0,i.kt)("inlineCode",{parentName:"p"},"detect-secrets")," tool. After scanning, a baseline file containing detected secrets is generated. Developers can audit this file for detailed information on detected secrets."),(0,i.kt)("h4",{id:"steps"},"Steps"),(0,i.kt)("ol",null,(0,i.kt)("li",{parentName:"ol"},(0,i.kt)("p",{parentName:"li"},(0,i.kt)("strong",{parentName:"p"},"Installation")),(0,i.kt)("ul",{parentName:"li"},(0,i.kt)("li",{parentName:"ul"},"Install the experimental version of ",(0,i.kt)("a",{parentName:"li",href:"https://github.com/NASA-AMMOS/slim-detect-secrets/tree/exp"},"slim-detect-secrets"),".",(0,i.kt)("pre",{parentName:"li"},(0,i.kt)("code",{parentName:"pre",className:"language-bash"},"pip install git+https://github.com/NASA-AMMOS/slim-detect-secrets.git@exp\n"))))),(0,i.kt)("li",{parentName:"ol"},(0,i.kt)("p",{parentName:"li"},(0,i.kt)("strong",{parentName:"p"},"Scanning")),(0,i.kt)("ul",{parentName:"li"},(0,i.kt)("li",{parentName:"ul"},"Scan all local files from the current directory and output results to a baseline file.",(0,i.kt)("pre",{parentName:"li"},(0,i.kt)("code",{parentName:"pre",className:"language-bash"},"detect-secrets scan --all-files --disable-plugin AbsolutePathDetectorExperimental --exclude-files '\\.secrets.*' --exclude-files '\\.git*' > .secrets.baseline\n"))))),(0,i.kt)("li",{parentName:"ol"},(0,i.kt)("p",{parentName:"li"},(0,i.kt)("strong",{parentName:"p"},"Checking Results")),(0,i.kt)("ul",{parentName:"li"},(0,i.kt)("li",{parentName:"ul"},"View the results in the baseline file.",(0,i.kt)("pre",{parentName:"li"},(0,i.kt)("code",{parentName:"pre",className:"language-bash"},"cat .secrets.baseline\n"))))),(0,i.kt)("li",{parentName:"ol"},(0,i.kt)("p",{parentName:"li"},(0,i.kt)("strong",{parentName:"p"},"Analysis")),(0,i.kt)("ul",{parentName:"li"},(0,i.kt)("li",{parentName:"ul"},"Analyze results using the ",(0,i.kt)("inlineCode",{parentName:"li"},"audit")," tool.",(0,i.kt)("pre",{parentName:"li"},(0,i.kt)("code",{parentName:"pre",className:"language-bash"},"detect-secrets audit .secrets.baseline\n")))))),(0,i.kt)("p",null,(0,i.kt)("a",{parentName:"p",href:"https://github.com/Yelp/detect-secrets#auditing-secrets-in-baseline"},"View more on Auditing Secrets in Baseline")),(0,i.kt)("blockquote",null,(0,i.kt)("p",{parentName:"blockquote"},"\u2139\ufe0f ",(0,i.kt)("strong",{parentName:"p"},"Note"),": If you've marked any secrets as true positives, make sure to remove all references to these secrets and rerun a full scan.")),(0,i.kt)("h3",{id:"layer-2-git-commit-scan-client-side"},"Layer 2: Git Commit Scan (Client-side)"),(0,i.kt)("p",null,"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."),(0,i.kt)("p",null,"To support this strategy, we recommend the installation of another third party tool called ",(0,i.kt)("a",{parentName:"p",href:"https://pre-commit.com/#install"},"pre-commit"),", 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."),(0,i.kt)("h4",{id:"steps-1"},"Steps"),(0,i.kt)("ol",null,(0,i.kt)("li",{parentName:"ol"},(0,i.kt)("p",{parentName:"li"},(0,i.kt)("strong",{parentName:"p"},"Installation")),(0,i.kt)("ul",{parentName:"li"},(0,i.kt)("li",{parentName:"ul"},(0,i.kt)("p",{parentName:"li"},"Install ",(0,i.kt)("a",{parentName:"p",href:"https://pre-commit.com/#install"},"pre-commit"),"."),(0,i.kt)("pre",{parentName:"li"},(0,i.kt)("code",{parentName:"pre",className:"language-bash"},"pip install pre-commit\n"))))),(0,i.kt)("li",{parentName:"ol"},(0,i.kt)("p",{parentName:"li"},(0,i.kt)("strong",{parentName:"p"},"Configuration")),(0,i.kt)("ul",{parentName:"li"},(0,i.kt)("li",{parentName:"ul"},(0,i.kt)("p",{parentName:"li"},"Create a ",(0,i.kt)("inlineCode",{parentName:"p"},".pre-commit-config.yaml")," configuration file with the below contents."),(0,i.kt)("pre",{parentName:"li"},(0,i.kt)("code",{parentName:"pre",className:"language-yaml"}," repos:\n - repo: https://github.com/NASA-AMMOS/slim-detect-secrets\n # using commit id for now, will change to tag when official version is released\n rev: 91e097ad4559ae6ab785c883dc5ed989202c7fbe\n hooks:\n - id: detect-secrets\n args:\n - '--baseline'\n - '.secrets.baseline'\n - '--exclude-files'\n - '\\.git*'\n - '--exclude-files'\n - '\\.secrets.*' \n"))))),(0,i.kt)("li",{parentName:"ol"},(0,i.kt)("p",{parentName:"li"},(0,i.kt)("strong",{parentName:"p"},"Hook Installation")),(0,i.kt)("ul",{parentName:"li"},(0,i.kt)("li",{parentName:"ul"},(0,i.kt)("p",{parentName:"li"},"Install the pre-commit hook into your local environment, ensuring the hook gets invoked during local git commits."),(0,i.kt)("pre",{parentName:"li"},(0,i.kt)("code",{parentName:"pre",className:"language-bash"},"pre-commit install\n"))))),(0,i.kt)("li",{parentName:"ol"},(0,i.kt)("p",{parentName:"li"},(0,i.kt)("strong",{parentName:"p"},"Committing Changes")),(0,i.kt)("ul",{parentName:"li"},(0,i.kt)("li",{parentName:"ul"},"Commit changes. If new secrets are detected, the commit will be blocked.")))),(0,i.kt)("blockquote",null,(0,i.kt)("p",{parentName:"blockquote"}," \u2139\ufe0f ",(0,i.kt)("strong",{parentName:"p"},"Note"),": The pre-commit hook does not automatically update the ",(0,i.kt)("inlineCode",{parentName:"p"},".secrets.baseline")," file. Update it by re-running the scan command.")),(0,i.kt)("h3",{id:"layer-3-server-side-push-to-githubcom"},"Layer 3: Server-side Push to GitHub.com"),(0,i.kt)("p",null,"This strategy provides a final layer of protection by scanning server-side commits for sensitive information during pull request creation. It leverages the ",(0,i.kt)("a",{parentName:"p",href:"https://pre-commit.com/#install"},"pre-commit")," tool and ",(0,i.kt)("a",{parentName:"p",href:"https://github.com/features/actions"},"GitHub Action"),". The scan is triggered during a push or pull request and any detected new secrets are reported while blocking merges or pushes to protected branches."),(0,i.kt)("h4",{id:"steps-2"},"Steps"),(0,i.kt)("ol",null,(0,i.kt)("li",{parentName:"ol"},(0,i.kt)("strong",{parentName:"li"},"Workflow Creation"),(0,i.kt)("ul",{parentName:"li"},(0,i.kt)("li",{parentName:"ul"},"The first step is to create a ",(0,i.kt)("inlineCode",{parentName:"li"},"detect-secrets.yaml")," workflow file in the ",(0,i.kt)("inlineCode",{parentName:"li"},".github/workflows")," directory to define the GitHub action. Copy and paste the below while ensuring the correct branch of your codebase is referenced. For example (from the ",(0,i.kt)("a",{parentName:"li",href:"https://github.com/NASA-AMMOS/slim-starterkit-python/blob/main/.github/workflows/secrets-detection.yml"},"Slim Python Starter Kit"),"):")))),(0,i.kt)("pre",null,(0,i.kt)("code",{parentName:"pre",className:"language-yaml"},'name: "Secret Detection"\non:\n push:\n branches: [main, develop]\n pull_request:\n # The branches below must be a subset of the branches above\n branches: [develop]\n\njobs:\n secret-detection:\n name: Secret-Detection\n runs-on: ubuntu-latest\n permissions:\n actions: write\n contents: read\n security-events: write\n steps:\n - name: Checkout repository\n uses: actions/checkout@v4\n with:\n fetch-depth: 0\n - name: Upgrade tooling\n run: |\n python3 -m pip install --upgrade pip\n pip install --upgrade git+https://github.com/NASA-AMMOS/slim-detect-secrets.git@exp\n pip install --upgrade jq\n - name: Create baseline config\n run: |\n if [ ! -f .secrets.baseline ] ; \n then\n # This generated baseline file will only be temporarily available on the GitHub side and will not appear in the user\'s local files.\n # Scanning an empty folder to generate an initial .secrets.baseline without secrets in the results.\n echo "\u26a0\ufe0f No existing .secrets.baseline file detected. Creating a new blank baseline file."\n mkdir empty-dir\n detect-secrets scan empty-dir > .secrets.baseline\n echo "\u2705 Blank .secrets.baseline file created successfully."\n rm -r empty-dir\n else\n echo "\u2705 Existing .secrets.baseline file detected. No new baseline file will be created."\n fi\n - name: Scan\n run: |\n # scripts scan repository for new secrets\n # backup list of known secrets\n cp -pr .secrets.baseline .secrets.new\n # find secrets in the repository\n detect-secrets scan --disable-plugin AbsolutePathDetectorExperimental --baseline .secrets.new \\\n --exclude-files \'\\.secrets..*\' \\\n --exclude-files \'\\.git.*\' \\\n --exclude-files \'\\.mypy_cache\' \\\n --exclude-files \'\\.pytest_cache\' \\\n --exclude-files \'\\.tox\' \\\n --exclude-files \'\\.venv\' \\\n --exclude-files \'venv\' \\\n --exclude-files \'dist\' \\\n --exclude-files \'build\' \\\n --exclude-files \'.*\\.egg-info\'\n # break build when new secrets discovered\n # function compares baseline/new secrets w/o listing results -- success(0) when new secret found\n 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) | grep -q \'>\' ; }\n # test baseline versus new secret files\n if compare_secrets .secrets.baseline .secrets.new; \n then\n echo "\u26a0\ufe0f Attention Required! \u26a0\ufe0f" >&2\n 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\n echo "" >&2\n echo "Please follow the steps below on your local machine to reveal and handle the secrets:" >&2\n echo "" >&2\n echo "1\ufe0f\u20e3 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\n echo "" >&2\n echo "2\ufe0f\u20e3 After cleaning up the secrets, commit your changes and re-push your update to the repository." >&2\n echo "" >&2\n echo "Your efforts to maintain the security of our codebase are greatly appreciated!" >&2\n exit 1\n else\n echo "\ud83d\udfe2 Secrets tests PASSED! \ud83d\udfe2" >&1\n echo "No new secrets were detected in comparison to any baseline configurations." >&1\n exit 0\n fi \n')),(0,i.kt)("pre",null,(0,i.kt)("code",{parentName:"pre"}," > \u2139\ufe0f 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.\n")),(0,i.kt)("p",null,"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."),(0,i.kt)("blockquote",null,(0,i.kt)("p",{parentName:"blockquote"},"\u26a0\ufe0f Warning: The check ensures specific lines of code that may contain sensitive information are not disclosed publicly. In GitHub Action logs only a yes/no indication of sensitive information appears. However, the surface area exists for potential attackers to readily identify sensitive information. Monitor your pull requests actively to respond and always ensure your team actively uses ",(0,i.kt)("a",{parentName:"p",href:"#layer-1-full-scan-and-audit-client-side"},"Layer 1")," and ",(0,i.kt)("a",{parentName:"p",href:"#layer-2-git-commit-scan-client-side"},"Layer 2")," to mitigate issues in the first place. ")),(0,i.kt)("hr",null),(0,i.kt)("h3",{id:"frequently-asked-questions-faq"},"Frequently Asked Questions (FAQ)"),(0,i.kt)("ul",null,(0,i.kt)("li",{parentName:"ul"},(0,i.kt)("p",{parentName:"li"},"Q: ",(0,i.kt)("strong",{parentName:"p"},"If secrets are detected in my code, what should I do?")),(0,i.kt)("p",{parentName:"li"},"A: Follow these steps:"),(0,i.kt)("ul",{parentName:"li"},(0,i.kt)("li",{parentName:"ul"},(0,i.kt)("em",{parentName:"li"},"Identify and Confirm:")," Review the identified secrets in the ",(0,i.kt)("inlineCode",{parentName:"li"},".secrets.baseline")," or any other report generated. Ensure that they are indeed secrets and not false positives."),(0,i.kt)("li",{parentName:"ul"},(0,i.kt)("em",{parentName:"li"},"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 ",(0,i.kt)("a",{parentName:"li",href:"https://github.com/Yelp/detect-secrets#inline-allowlisting-1"},"here"),". "),(0,i.kt)("li",{parentName:"ul"},(0,i.kt)("em",{parentName:"li"},"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."),(0,i.kt)("li",{parentName:"ul"},(0,i.kt)("em",{parentName:"li"},"Rerun Scans:")," After you've made the necessary changes, run the ",(0,i.kt)("inlineCode",{parentName:"li"},"detect-secrets")," tool again to ensure no secrets remain."),(0,i.kt)("li",{parentName:"ul"},(0,i.kt)("em",{parentName:"li"},"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."),(0,i.kt)("li",{parentName:"ul"},(0,i.kt)("em",{parentName:"li"},"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."))),(0,i.kt)("li",{parentName:"ul"},(0,i.kt)("p",{parentName:"li"},"Q: ",(0,i.kt)("strong",{parentName:"p"},"Does detect-secrets scan the entire Git history?")),(0,i.kt)("p",{parentName:"li"},"A: No, it's designed to scan the current state of a project for efficiency.")),(0,i.kt)("li",{parentName:"ul"},(0,i.kt)("p",{parentName:"li"},"Q: ",(0,i.kt)("strong",{parentName:"p"},"How are commits containing secrets removed permanently from Git history?")),(0,i.kt)("p",{parentName:"li"},"A: The process of scrubbing errant commits and their content involves a destructive rewrite of repository commit history. Backups are essential and changes must be handled with precision and caution. One solution is to start a new repository from scratch with only the latest cleaned code, thereby negating the need to change existing repository content. Solutions involving more entropy include Git filter commands or well-known cleaning applications, such as ",(0,i.kt)("a",{parentName:"p",href:"https://rtyley.github.io/bfg-repo-cleaner/"},"BFG Repo-Cleaner"),". Because of the risks involved in mutating repository history and content, such changes ",(0,i.kt)("em",{parentName:"p"},"always")," must be handled with backups, expertise and extreme care.")),(0,i.kt)("li",{parentName:"ul"},(0,i.kt)("p",{parentName:"li"},"Q: ",(0,i.kt)("strong",{parentName:"p"},"Where can I find more configurations and options for detect-secrets?")),(0,i.kt)("p",{parentName:"li"},"A: Refer to the official documentation for ",(0,i.kt)("a",{parentName:"p",href:"https://github.com/Yelp/detect-secrets"},"detect-secrets")," and ",(0,i.kt)("a",{parentName:"p",href:"https://pre-commit.com/"},"pre-commit"),"."))),(0,i.kt)("hr",null),(0,i.kt)("h2",{id:"credits"},"Credits"),(0,i.kt)("p",null,(0,i.kt)("strong",{parentName:"p"},"Authorship"),":"),(0,i.kt)("ul",null,(0,i.kt)("li",{parentName:"ul"},"Jingchao Zhong ",(0,i.kt)("a",{parentName:"li",href:"https://github.com/perryzjc"},"@perryzjc")),(0,i.kt)("li",{parentName:"ul"},"Rishi Verma ",(0,i.kt)("a",{parentName:"li",href:"https://github.com/riverma"},"@riverma")),(0,i.kt)("li",{parentName:"ul"},"John Engelke ",(0,i.kt)("a",{parentName:"li",href:"http://github.com/jpl-jengelke"},"@jpl-jengelke"))),(0,i.kt)("p",null,(0,i.kt)("strong",{parentName:"p"},"Acknowledgements"),":"),(0,i.kt)("ul",null,(0,i.kt)("li",{parentName:"ul"},(0,i.kt)("a",{parentName:"li",href:"https://github.com/Yelp/detect-secrets"},"Yelp's detect-secrets maintainers")),(0,i.kt)("li",{parentName:"ul"},(0,i.kt)("a",{parentName:"li",href:"https://github.com/nutjob4life"},"@nutjob4life")," for detect-secrets usage tips")),(0,i.kt)("hr",null),(0,i.kt)("h2",{id:"feedback-and-contributions"},"Feedback and Contributions"),(0,i.kt)("p",null,"We value your feedback and contributions. Enhance and expand this guide by referring to our ",(0,i.kt)("a",{parentName:"p",href:"https://nasa-ammos.github.io/slim/docs/contribute/contributing/"},"contribution guidelines"),"."))}m.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/684aec4d.fcc6bc30.js b/assets/js/684aec4d.fcc6bc30.js deleted file mode 100644 index 01af480c0..000000000 --- a/assets/js/684aec4d.fcc6bc30.js +++ /dev/null @@ -1 +0,0 @@ -"use strict";(self.webpackChunkdocusaurus=self.webpackChunkdocusaurus||[]).push([[4103],{3905:(e,t,n)=>{n.d(t,{Zo:()=>p,kt:()=>h});var s=n(7294);function i(e,t,n){return t in e?Object.defineProperty(e,t,{value:n,enumerable:!0,configurable:!0,writable:!0}):e[t]=n,e}function a(e,t){var n=Object.keys(e);if(Object.getOwnPropertySymbols){var s=Object.getOwnPropertySymbols(e);t&&(s=s.filter((function(t){return Object.getOwnPropertyDescriptor(e,t).enumerable}))),n.push.apply(n,s)}return n}function r(e){for(var t=1;t=0||(i[n]=e[n]);return i}(e,t);if(Object.getOwnPropertySymbols){var a=Object.getOwnPropertySymbols(e);for(s=0;s=0||Object.prototype.propertyIsEnumerable.call(e,n)&&(i[n]=e[n])}return i}var l=s.createContext({}),c=function(e){var t=s.useContext(l),n=t;return e&&(n="function"==typeof e?e(t):r(r({},t),e)),n},p=function(e){var t=c(e.components);return s.createElement(l.Provider,{value:t},e.children)},u="mdxType",d={inlineCode:"code",wrapper:function(e){var t=e.children;return s.createElement(s.Fragment,{},t)}},m=s.forwardRef((function(e,t){var n=e.components,i=e.mdxType,a=e.originalType,l=e.parentName,p=o(e,["components","mdxType","originalType","parentName"]),u=c(n),m=i,h=u["".concat(l,".").concat(m)]||u[m]||d[m]||a;return n?s.createElement(h,r(r({ref:t},p),{},{components:n})):s.createElement(h,r({ref:t},p))}));function h(e,t){var n=arguments,i=t&&t.mdxType;if("string"==typeof e||i){var a=n.length,r=new Array(a);r[0]=m;var o={};for(var l in t)hasOwnProperty.call(t,l)&&(o[l]=t[l]);o.originalType=e,o[u]="string"==typeof e?e:i,r[1]=o;for(var c=2;c{n.r(t),n.d(t,{assets:()=>l,contentTitle:()=>r,default:()=>d,frontMatter:()=>a,metadata:()=>o,toc:()=>c});var s=n(7462),i=(n(7294),n(3905));const a={},r="Secrets Detection",o={unversionedId:"guides/software-lifecycle/security/secrets-detection/README",id:"guides/software-lifecycle/security/secrets-detection/README",title:"Secrets Detection",description:"We recommend 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,",source:"@site/docs/guides/software-lifecycle/security/secrets-detection/README.md",sourceDirName:"guides/software-lifecycle/security/secrets-detection",slug:"/guides/software-lifecycle/security/secrets-detection/",permalink:"/slim/docs/guides/software-lifecycle/security/secrets-detection/",draft:!1,editUrl:"https://github.com/nasa-ammos/slim/tree/main/docs/guides/software-lifecycle/security/secrets-detection/README.md",tags:[],version:"current",frontMatter:{},sidebar:"guidesSidebar",previous:{title:"GitHub Security Best Practices",permalink:"/slim/docs/guides/software-lifecycle/security/github-security/"},next:{title:"Continuous Integration",permalink:"/slim/docs/guides/software-lifecycle/continuous-integration/"}},l={},c=[{value:"Layer 1: Full Scan and Audit (Client-side)",id:"layer-1-full-scan-and-audit-client-side",level:2},{value:"Layer 2: Git Commit Scan (Client-side)",id:"layer-2-git-commit-scan-client-side",level:2},{value:"Layer 3: Server-side Push to GitHub.com",id:"layer-3-server-side-push-to-githubcom",level:2},{value:"Attention for using Detect Secrets",id:"attention-for-using-detect-secrets",level:2},{value:"Recommended Workflow",id:"recommended-workflow",level:2},{value:"More Configurations",id:"more-configurations",level:2}],p={toc:c},u="wrapper";function d(e){let{components:t,...n}=e;return(0,i.kt)(u,(0,s.Z)({},p,n,{components:t,mdxType:"MDXLayout"}),(0,i.kt)("h1",{id:"secrets-detection"},"Secrets Detection"),(0,i.kt)("p",null,"We recommend ",(0,i.kt)("a",{parentName:"p",href:"https://github.com/Yelp/detect-secrets"},"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,\nit operates swiftly, making it ideal for continuous integration pipelines. Leveraging the concept of a "baseline file" (',(0,i.kt)("inlineCode",{parentName:"p"},".secrets.baseline"),"), it enables easy handling of known secrets and false positives, facilitating its gradual integration into existing projects. "),(0,i.kt)("p",null,(0,i.kt)("img",{parentName:"p",src:"https://github.com/NASA-AMMOS/slim/assets/3129134/58ecb3de-0ab4-4302-b546-e9cd1de8e52f",alt:"detect-secrets-wordcloud"})),(0,i.kt)("p",null,"Our application of ",(0,i.kt)("inlineCode",{parentName:"p"},"detect-secrets")," embraces a tri-layered approach, bolstered by customized plugins (",(0,i.kt)("a",{parentName:"p",href:"https://github.com/NASA-AMMOS/slim-detect-secrets/tree/exp#viewing-all-enabled-plugins"},"full list of plugins available here"),"), to provide robust protection against potential secret leaks at the earliest stage.\nThis page proposes three layers of secret scanning to help prevent secrets from being leaked on GitHub"),(0,i.kt)("p",null,"Three layers of protection are:"),(0,i.kt)("ol",null,(0,i.kt)("li",{parentName:"ol"},"Client-side full scan of existing code base"),(0,i.kt)("li",{parentName:"ol"},"Client-side scan of updated code upon Git commit"),(0,i.kt)("li",{parentName:"ol"},"Server-side push to GitHub.com from client")),(0,i.kt)("p",null,"Each layer has its own advantages and disadvantages. The full use of these three layers of protection is recommended to minimize human negligence."),(0,i.kt)("mermaid",{value:'flowchart TB\n User([fa:fa-user User])\n\n subgraph UserWorkflow["User Workflow to Secure Secrets"]\n Layer1["Layer 1: Full scan (client-side)"]\n Layer2["Layer 2: Git commit scan (client-side)"]\n Layer3["Layer 3: GitHub.com (server-side)"]\n\n Layer1 --\x3e|If Secrets Detected| Clean1[Clean local file directly.]\n Layer2 --\x3e|If Secrets Detected| Clean2[Clean local file directly.
Don\'t need to worry about cleaning commit history]\n Layer3 --\x3e|If Secrets Detected| Clean3[Purge or Fix the commit manually]\n \n SaveTime["It saves your time. And secrets are safe from GitHub"]\n Clean1 --\x3e SaveTime\n Clean2 --\x3e SaveTime\n\n Secure["Only GitHub-Protected branch is in safe.
Secrets are leaked on other branch before cleaning"]\n Clean3--\x3e Secure\n end\n\n User --\x3e|At least use| Layer1\n User --\x3e|Helpful to use| Layer2\n User --\x3e|Optional to use| Layer3\n\n style User fill:#F6F5F3,stroke:#333,stroke-width:1px\n style UserWorkflow fill:#AF7AC5,stroke:#333,stroke-width:2px\n style Layer1 fill:#F3B044,stroke:#333,stroke-width:2px,stroke-dasharray: 5 5\n style Layer2 fill:#F3B044,stroke:#333,stroke-width:2px,stroke-dasharray: 5 5\n style Layer3 fill:#F3B044,stroke:#333,stroke-width:2px,stroke-dasharray: 5 5\n style Clean1 fill:#5A88ED,stroke:#333,stroke-width:2px\n style Clean2 fill:#5A88ED,stroke:#333,stroke-width:2px\n style Clean3 fill:#5A88ED,stroke:#333,stroke-width:2px\n style SaveTime fill:#5ABF9B,stroke:#333,stroke-width:2px\n style Secure fill:#AF3034,stroke:#333,stroke-width:2px\n'}),(0,i.kt)("blockquote",null,(0,i.kt)("p",{parentName:"blockquote"},(0,i.kt)("strong",{parentName:"p"},"Note"),": Below three layers, are running on experimental version ",(0,i.kt)("a",{parentName:"p",href:"https://github.com/NASA-AMMOS/slim-detect-secrets/tree/exp"},"slim-detect-secrets")," which supports additional secret detection ",(0,i.kt)("a",{parentName:"p",href:"https://github.com/NASA-AMMOS/slim-detect-secrets/tree/exp#viewing-all-enabled-plugins"},"plugins"),"."),(0,i.kt)("p",{parentName:"blockquote"},"They are:"),(0,i.kt)("blockquote",{parentName:"blockquote"},(0,i.kt)("ul",{parentName:"blockquote"},(0,i.kt)("li",{parentName:"ul"},"AWS sensitive information"),(0,i.kt)("li",{parentName:"ul"},"Public IP Address"),(0,i.kt)("li",{parentName:"ul"},"Absolute Path"),(0,i.kt)("li",{parentName:"ul"},"Email Address")),(0,i.kt)("p",{parentName:"blockquote"},"Link to their ",(0,i.kt)("a",{parentName:"p",href:"https://github.com/NASA-AMMOS/slim-detect-secrets/tree/exp/detect_secrets/plugins"},"implementation")," and ",(0,i.kt)("a",{parentName:"p",href:"https://github.com/NASA-AMMOS/slim-detect-secrets/tree/exp/tests/plugins"},"test suites"))),(0,i.kt)("p",{parentName:"blockquote"},"It is being tested by both ",(0,i.kt)("a",{parentName:"p",href:"https://github.com/NASA-AMMOS/slim"},"NASA-AMMOS/slim")," team and ",(0,i.kt)("a",{parentName:"p",href:"https://github.com/Yelp/detect-secrets"},"Yelp/detect-secrets")," team.\nEventually, it will be merged into Yelp/detect-secrets."),(0,i.kt)("p",{parentName:"blockquote"},"At that time, this document will be updated to use the official version of detect-secrets.")),(0,i.kt)("h2",{id:"layer-1-full-scan-and-audit-client-side"},"Layer 1: Full Scan and Audit (Client-side)"),(0,i.kt)("p",null,"The first layer initiates a direct scan on the developer's local environment. This is achieved through the ",(0,i.kt)("inlineCode",{parentName:"p"},"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."),(0,i.kt)("mermaid",{value:"sequenceDiagram\n participant Dev as Developer\n participant Env as Local Environment\n participant DS as Detect-Secrets\n participant File as Baseline File\n participant Audit as Audit Tool\n\n Note over Dev,Env: Developer initiates a direct scan for secrets\n Dev->>+Env: Triggers direct scan\n Env->>+DS: Requests scan on the codebase\n DS->>DS: Performs secret scanning\n DS->>File: Generates new baseline file\n File->>DS: Acknowledges file creation\n DS--\x3e>-Env: Returns scan results and new baseline file\n Env--\x3e>Dev: Presents scan results and new baseline file\n Note over Dev,File: Developer may audit the new baseline file\n Dev->>Audit: Initiates audit on the new baseline file\n Audit->>File: Fetches details from the baseline file\n File->>Audit: Returns secret details\n Audit--\x3e>Dev: Presents detailed information of detected secrets\n"}),(0,i.kt)("p",null,"Starter Kit:"),(0,i.kt)("ol",null,(0,i.kt)("li",{parentName:"ol"},"Install experimental version of ",(0,i.kt)("a",{parentName:"li",href:"https://github.com/NASA-AMMOS/slim-detect-secrets/tree/exp"},"slim-detect-secrets"))),(0,i.kt)("pre",null,(0,i.kt)("code",{parentName:"pre",className:"language-bash"},"pip install git+https://github.com/NASA-AMMOS/slim-detect-secrets.git@exp\n")),(0,i.kt)("ol",{start:2},(0,i.kt)("li",{parentName:"ol"},"Scan all local files from current directory and output the result as a baseline file")),(0,i.kt)("pre",null,(0,i.kt)("code",{parentName:"pre",className:"language-bash"},"detect-secrets scan ./ --all-files --disable-plugin AbsolutePathDetectorExperimental --exclude-files '.secrets.*' --exclude-files '.git*' > .secrets.baseline\n")),(0,i.kt)("p",null,"Here it scans all the local files from current directory, but excludes ",(0,i.kt)("inlineCode",{parentName:"p"},".git")," directory and ",(0,i.kt)("inlineCode",{parentName:"p"},".secrets")," baseline files from scanning to reduce false positive. Make modifications when necessary."),(0,i.kt)("ol",{start:3},(0,i.kt)("li",{parentName:"ol"},"Check result in the baseline file")),(0,i.kt)("pre",null,(0,i.kt)("code",{parentName:"pre",className:"language-bash"},"cat .secrets.baseline\n")),(0,i.kt)("blockquote",null,(0,i.kt)("p",{parentName:"blockquote"},"This command is supported in Unix-like system. For Windows, you can use other command, such as ",(0,i.kt)("inlineCode",{parentName:"p"},"type .secrets.baseline"),'\nIf any secrets are detected, the result will be located at the "results:" of the file.')),(0,i.kt)("p",null,"For example,"),(0,i.kt)("pre",null,(0,i.kt)("code",{parentName:"pre",className:"language-json"},'"results": {\n "Sample/sample-develop.sh": [\n {\n "type": "AWS Sensitive Information",\n "filename": "Sample/sample-develop.sh",\n "hashed_secret": "d3f72b97cd8756fe12345678bdf96aef1ac23b7d",\n "is_verified": false,\n "line_number": 39\n},\n')),(0,i.kt)("p",null,"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."),(0,i.kt)("ol",{start:4},(0,i.kt)("li",{parentName:"ol"},"Analyze results by ",(0,i.kt)("inlineCode",{parentName:"li"},"audit")," tool")),(0,i.kt)("pre",null,(0,i.kt)("code",{parentName:"pre",className:"language-bash"},"detect-secrets audit .secrets.baseline\n")),(0,i.kt)("blockquote",null,(0,i.kt)("p",{parentName:"blockquote"},"detect-secrets audit tool can provide you an interactive interface to view the actual secret based on the line number\nand label it as false positive or true positive.")),(0,i.kt)("p",null,"For example,"),(0,i.kt)("img",{width:"564",src:"https://github.com/NASA-AMMOS/slim/assets/92573736/0fb25452-1ada-4979-9873-a1ca615701b5"}),(0,i.kt)("p",null,"It also provides other ways to present the result. For more information, please refer to ",(0,i.kt)("a",{parentName:"p",href:"https://github.com/Yelp/detect-secrets#auditing-secrets-in-baseline"},"Auditing Secrets in Baseline")),(0,i.kt)("p",null,(0,i.kt)("strong",{parentName:"p"},(0,i.kt)("em",{parentName:"strong"},"Note"))," if you have marked any detected secrets as true positives, its best to first remove all references to those secrets in your code and then rerun a full scan to generate a fresh audit report that you can compare against to ensure you only have false-positives (white-listed secrets) in your ",(0,i.kt)("inlineCode",{parentName:"p"},".secrets.baseline")," - this is especially important for Layer 2."),(0,i.kt)("h2",{id:"layer-2-git-commit-scan-client-side"},"Layer 2: Git Commit Scan (Client-side)"),(0,i.kt)("p",null,"The second layer is a pre-commit hook implemented in the local environment. This hook utilizes a ",(0,i.kt)("inlineCode",{parentName:"p"},".pre-commit-config.yaml")," file to config the pre-commit hook. The hook is triggered when the developer attempts to commit changes. The hook will scan the changes and ",(0,i.kt)("strong",{parentName:"p"},"compare")," them to the baseline file generated in the first layer. If any ",(0,i.kt)("strong",{parentName:"p"},"new secrets")," are detected, the hook will prevent the commit and report the detected secrets to the developer."),(0,i.kt)("mermaid",{value:"sequenceDiagram\n participant User as Developer\n participant Local as Local Environment\n participant Config as .pre-commit-config.yaml\n participant PCH as Pre-commit Hook\n participant DS as Detect-Secrets\n participant File as Baseline File\n\n Note over User,Local: Developer attempts to commit\n User->>+Local: Request commit\n Local->>+Config: Fetches pre-commit config\n Config->>PCH: Returns config with Detect-Secrets setup\n PCH->>DS: Request secret scan with existing baseline\n DS->>File: Fetches baseline file\n File->>DS: Returns baseline file\n DS->>DS: Scans changes for secrets with custom plugins\n alt New Secrets Detected\n DS--\x3e>PCH: Returns detected secrets\n PCH--\x3e>Local: Prevents commit & reports detected secrets\n Local--\x3e>User: Prevents commit & reports detected secrets\n else No New Secrets Detected\n DS--\x3e>PCH: Returns clean result\n PCH--\x3e>Local: Allows commit\n Local--\x3e>User: Commits changes\n end\n"}),(0,i.kt)("p",null,"Starter Kit:"),(0,i.kt)("ol",null,(0,i.kt)("li",{parentName:"ol"},"Install ",(0,i.kt)("a",{parentName:"li",href:"https://pre-commit.com/#install"},"pre-commit"))),(0,i.kt)("pre",null,(0,i.kt)("code",{parentName:"pre",className:"language-bash"},"pip install pre-commit\n")),(0,i.kt)("p",null,"This tool is used to install pre-commit hook in your local git repository."),(0,i.kt)("ol",{start:2},(0,i.kt)("li",{parentName:"ol"},"Create ",(0,i.kt)("inlineCode",{parentName:"li"},".pre-commit-config.yaml")," file in root directory of your project with the following contents")),(0,i.kt)("pre",null,(0,i.kt)("code",{parentName:"pre",className:"language-yaml"},"repos:\n - repo: https://github.com/NASA-AMMOS/slim-detect-secrets\n # using commit id for now, will change to tag when official version is released\n rev: 91e097ad4559ae6ab785c883dc5ed989202c7fbe\n hooks:\n - id: detect-secrets\n args:\n - '--baseline'\n - '.secrets.baseline'\n - '--exclude-files'\n - '.git*'\n - '--exclude-files'\n - '.secrets.*' \n\n")),(0,i.kt)("p",null,"This file is used to config the pre-commit hook. In this example, we use the experimental version of ",(0,i.kt)("inlineCode",{parentName:"p"},"slim-detect-secrets")," tool. The ",(0,i.kt)("inlineCode",{parentName:"p"},"--baseline")," argument is used to specify the baseline file generated in the first layer. The ",(0,i.kt)("inlineCode",{parentName:"p"},"--exclude-files")," argument is used to exclude the ",(0,i.kt)("inlineCode",{parentName:"p"},".git")," directory and ",(0,i.kt)("inlineCode",{parentName:"p"},".secrets")," baseline files from scanning to reduce false positives. Make modifications when necessary."),(0,i.kt)("ol",{start:3},(0,i.kt)("li",{parentName:"ol"},"Install pre-commit hook")),(0,i.kt)("pre",null,(0,i.kt)("code",{parentName:"pre",className:"language-bash"},"pre-commit install\n")),(0,i.kt)("p",null,"This command reads the ",(0,i.kt)("inlineCode",{parentName:"p"},".pre-commit-config.yaml")," file and installs the pre-commit hook in your local git repository.\nAfter this, you can see a ",(0,i.kt)("inlineCode",{parentName:"p"},".git/hooks/pre-commit")," file is created in your local git repository."),(0,i.kt)("ol",{start:4},(0,i.kt)("li",{parentName:"ol"},"Add the baseline file ",(0,i.kt)("inlineCode",{parentName:"li"},".secrets.baseline")," in your local Git repository under the following conditions only:",(0,i.kt)("ol",{parentName:"li"},(0,i.kt)("li",{parentName:"ol"},"You wish to share white-listed secrets with other team members"),(0,i.kt)("li",{parentName:"ol"},"You've removed any references in your code to sensitive secrets detected that are not white-listed, i.e. find and modify code referenced in you ",(0,i.kt)("inlineCode",{parentName:"li"},".secrets.baseline")," with flag ",(0,i.kt)("inlineCode",{parentName:"li"},"is_secret: true")),(0,i.kt)("li",{parentName:"ol"},"You've re-run a fresh ",(0,i.kt)("inlineCode",{parentName:"li"},"detect-secrets scan")," followed by a ",(0,i.kt)("inlineCode",{parentName:"li"},"detect-secrets audit")," and your ",(0,i.kt)("inlineCode",{parentName:"li"},".secrets.baseline")," ONLY now contains white-listed entries, i.e. ",(0,i.kt)("inlineCode",{parentName:"li"},"is_secret: false"))))),(0,i.kt)("p",null,(0,i.kt)("strong",{parentName:"p"},"Warning"),": Adding your ",(0,i.kt)("inlineCode",{parentName:"p"},".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!"),(0,i.kt)("ol",{start:5},(0,i.kt)("li",{parentName:"ol"},"Commit your changes")),(0,i.kt)("p",null,"Now, you can commit your changes as usual. If any ",(0,i.kt)("strong",{parentName:"p"},"new secrets")," are detected, the commit will be prevented and the secrets will be reported."),(0,i.kt)("p",null,"For example,"),(0,i.kt)("img",{width:"559",alt:"Screen Shot 2023-04-20 at 7 32 10 AM",src:"https://user-images.githubusercontent.com/92573736/233398613-6e189322-4d97-47c3-b3ba-bd700a716cf6.png"}),(0,i.kt)("blockquote",null,(0,i.kt)("p",{parentName:"blockquote"},(0,i.kt)("strong",{parentName:"p"},"Note"),": The pre-commit hook blocks a commit by comparing new secrets with the results in the ",(0,i.kt)("inlineCode",{parentName:"p"},".secrets.baseline")," file. If new secrets are introduced, the hook will report them, but it does not automatically update the ",(0,i.kt)("inlineCode",{parentName:"p"},".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.")),(0,i.kt)("blockquote",null,(0,i.kt)("p",{parentName:"blockquote"},(0,i.kt)("strong",{parentName:"p"},"Note"),": during commit checks, detect secrets may not display all secrets present within a single file during a single scan. This can be to ",(0,i.kt)("a",{parentName:"p",href:"https://github.com/Yelp/detect-secrets/blob/master/docs/design.md#potentialsecret"},"minimize noise"),", 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."),(0,i.kt)("p",{parentName:"blockquote"},"You can create an empty result baseline file by running this command at a directory without secrets.")),(0,i.kt)("h2",{id:"layer-3-server-side-push-to-githubcom"},"Layer 3: Server-side Push to GitHub.com"),(0,i.kt)("p",null,"The final layer of our solution is a server-side pre-commit scan powered by ",(0,i.kt)("a",{parentName:"p",href:"https://github.com/features/actions"},"GitHub Action"),". 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 ",(0,i.kt)("strong",{parentName:"p"},"protected")," branch. This layer protects the protected branch from being polluted by secrets, but secrets can still be pushed to other branches."),(0,i.kt)("mermaid",{value:"sequenceDiagram\n participant User as Developer\n participant GH as GitHub\n participant Workflow as detect-secrets.yaml\n participant GA as GitHub Action\n participant DS as Detect-Secrets\n\n Note over User,GH: Developer creates pull request or pushes to branch\n User->>+GH: Creates pull request / pushes to branch\n GH->>+Workflow: Triggers GitHub Action workflow\n Workflow->>GA: Sets up and runs Detect-Secrets scan\n GA->>DS: Requests secret scan\n DS->>DS: Scans repository for secrets\n alt Secrets Detected\n DS--\x3e>GA: Returns detected secrets\n GA--\x3e>GH: Fails status check\n GH--\x3e>User: Prevents merge / push & sends email notification\n else No Secrets Detected\n DS--\x3e>GA: Returns clean result\n GA--\x3e>GH: Passes status check\n GH--\x3e>User: Allows merge / push\n end\n"}),(0,i.kt)("p",null,"Starter Kit:"),(0,i.kt)("ol",null,(0,i.kt)("li",{parentName:"ol"},"Create a workflow file ",(0,i.kt)("inlineCode",{parentName:"li"},"detect-secrets.yaml")," in ",(0,i.kt)("inlineCode",{parentName:"li"},".github/workflows")," directory from your repository root.")),(0,i.kt)("pre",null,(0,i.kt)("code",{parentName:"pre",className:"language-yaml"},'name: Secret Detection Workflow\non:\n push:\n branches:\n - main\n pull_request:\n branches:\n - main\n\njobs:\n secret-detection:\n runs-on: ubuntu-latest\n steps:\n - name: Checkout code\n uses: actions/checkout@v2\n\n - name: Install necessary packages\n run: |\n # This is the experimental version of slim-detect-secrets.\n # It will be updated to the official Yelp/detect-secrets version once the customized plugins are merged.\n # For more information about slim/detect-secrets, check the following:\n # 1. https://github.com/NASA-AMMOS/slim-detect-secrets/tree/exp\n # 2. https://github.com/NASA-AMMOS/slim/blob/d20ee6134a0dc0e0dab11d2d2570e358ef7e4550/continuous-testing/starter-kits/README.md#detect-secrets\n pip install git+https://github.com/NASA-AMMOS/slim-detect-secrets.git@exp\n # This library is used for JSON operations.\n pip install jq\n \n - name: Create an initial .secrets.baseline if .secrets.baseline does not exist\n run: |\n if [ ! -f .secrets.baseline ]; then\n # This generated baseline file will only be temporarily available on the GitHub side and will not appear in the user\'s local files.\n # Scanning an empty folder to generate an initial .secrets.baseline without secrets in the results.\n echo "\u26a0\ufe0f No existing .secrets.baseline file detected. Creating a new blank baseline file."\n mkdir empty-dir\n detect-secrets scan empty-dir > .secrets.baseline\n echo "\u2705 Blank .secrets.baseline file created successfully."\n rm -r empty-dir\n else\n echo "\u2705 Existing .secrets.baseline file detected. No new baseline file will be created."\n fi\n\n - name: Scan repository for secrets\n run: |\n # scripts to scan repository for new secrets\n \n # backup the list of known secrets\n cp .secrets.baseline .secrets.new\n\n # find the secrets in the repository\n detect-secrets scan --disable-plugin AbsolutePathDetectorExperimental --baseline .secrets.new --exclude-files \'.secrets.*\' --exclude-files \'.git*\'\n \n # if there is any difference between the known and newly detected secrets, break the build\n # Function to compare secrets without listing them\n 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; }\n \n # Check if there\'s any difference between the known and newly detected secrets\n if ! compare_secrets .secrets.baseline .secrets.new; then\n echo "\u26a0\ufe0f Attention Required! \u26a0\ufe0f" >&2\n 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\n echo "" >&2\n echo "Please follow the steps below on your local machine to reveal and handle the secrets:" >&2\n echo "" >&2\n echo "1\ufe0f\u20e3 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\n echo "" >&2\n echo "2\ufe0f\u20e3 After cleaning up the secrets, commit your changes and re-push your update to the repository." >&2\n echo "" >&2\n echo "Your efforts to maintain the security of our codebase are greatly appreciated!" >&2\n exit 1\n fi\n\n')),(0,i.kt)("p",null,(0,i.kt)("strong",{parentName:"p"},"Explanation")),(0,i.kt)("p",null,"The Detect Secrets Action follows these steps to ensure the security of your code:"),(0,i.kt)("ul",null,(0,i.kt)("li",{parentName:"ul"},(0,i.kt)("strong",{parentName:"li"},"Checkout Code"),": Utilizes GitHub's checkout action to access the repository. This is the code that will be scanned for secrets."),(0,i.kt)("li",{parentName:"ul"},(0,i.kt)("strong",{parentName:"li"},"Install Necessary Packages"),": Deploys the required Python packages, including the experimental version of ",(0,i.kt)("inlineCode",{parentName:"li"},"slim-detect-secrets")," and ",(0,i.kt)("inlineCode",{parentName:"li"},"jq"),". These packages enable the primary functionality of the Action."),(0,i.kt)("li",{parentName:"ul"},(0,i.kt)("strong",{parentName:"li"},"Check Existence of .secrets.baseline"),": Ensures the Action remains operational even if no baseline file exists yet. If the ",(0,i.kt)("inlineCode",{parentName:"li"},".secrets.baseline")," file is not found, the action creates an initial baseline file by scanning an empty directory."),(0,i.kt)("li",{parentName:"ul"},(0,i.kt)("strong",{parentName:"li"},"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 ",(0,i.kt)("inlineCode",{parentName:"li"},"detect-secrets")," tool.")),(0,i.kt)("p",null,"After this, GitHub will automatically run the workflow when you push to the branch or create a pull request."),(0,i.kt)("p",null,"This workflow will run the ",(0,i.kt)("inlineCode",{parentName:"p"},"detect-secrets")," tool on the GitHub server. If any new secrets are detected, it will:"),(0,i.kt)("ul",null,(0,i.kt)("li",{parentName:"ul"},(0,i.kt)("p",{parentName:"li"},"Fail the status check"),(0,i.kt)("img",{width:"507",src:"https://github.com/NASA-AMMOS/slim/assets/92573736/bc7670f8-5bbb-414c-b9af-803be05efd67"})),(0,i.kt)("li",{parentName:"ul"},(0,i.kt)("p",{parentName:"li"},'Print a message in the "Details" with instructions on how to resolve the issue'),(0,i.kt)("img",{width:"1627",src:"https://github.com/NASA-AMMOS/slim/assets/92573736/7e884d60-c972-46f2-9785-31b09cebb93f"})),(0,i.kt)("li",{parentName:"ul"},(0,i.kt)("p",{parentName:"li"},"Send an email notification to the user"),(0,i.kt)("img",{width:"1192",src:"https://github.com/NASA-AMMOS/slim/assets/92573736/142e0693-f3f8-42c8-92d7-deb653bdb09c"}))),(0,i.kt)("ol",{start:2},(0,i.kt)("li",{parentName:"ol"},(0,i.kt)("a",{parentName:"li",href:"https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/managing-a-branch-protection-rule"},"Protect your branch"))),(0,i.kt)("img",{width:"1107",src:"https://github.com/NASA-AMMOS/slim/assets/92573736/5a430b2f-7f9b-4ba0-a06a-7c53b300f08b"}),(0,i.kt)("p",null,"After this, if status check fails, GitHub will prevent the merge or push to the protected branch."),(0,i.kt)("img",{width:"918",src:"https://github.com/NASA-AMMOS/slim/assets/92573736/9f8b6239-840a-4ba4-9458-d795f46d7acd"}),(0,i.kt)("h2",{id:"attention-for-using-detect-secrets"},"Attention for using Detect Secrets"),(0,i.kt)("blockquote",null,(0,i.kt)("p",{parentName:"blockquote"},"1.It does not ",(0,i.kt)("a",{parentName:"p",href:"https://github.com/Yelp/detect-secrets/blob/master/docs/design.md#potentialsecret"},"show all the same type of secrets in a same file to minimize noise")),(0,i.kt)("p",{parentName:"blockquote"},"This means sometimes it will only show one secret in a file even if there are multiple ",(0,i.kt)("strong",{parentName:"p"},"same type of secrets")," in the same file.\nAudit tool will not show all the secrets due to this reason."),(0,i.kt)("p",{parentName:"blockquote"},(0,i.kt)("strong",{parentName:"p"},"->")," Thus, when you see a secret is detected, best practice is to ",(0,i.kt)("strong",{parentName:"p"},"manually")," check that file.")),(0,i.kt)("blockquote",null,(0,i.kt)("p",{parentName:"blockquote"},"2.Even though detect-secrets has strong secret-detect ability compared to other tools, it is still possible that detect-secrets will not show you a file that contains secrets due to a new type of secret not capable by current plugins."),(0,i.kt)("p",{parentName:"blockquote"},(0,i.kt)("strong",{parentName:"p"},"->")," Thus, the best practice is always to be careful as a developer and ",(0,i.kt)("strong",{parentName:"p"},"manually")," check the files that you think might contain secrets."),(0,i.kt)("blockquote",{parentName:"blockquote"},(0,i.kt)("p",{parentName:"blockquote"},(0,i.kt)("strong",{parentName:"p"},"Note"),": ",(0,i.kt)("inlineCode",{parentName:"p"},"detect-secrets")," is a backup approach to minimize the chance of pushing secrets to the cloud."))),(0,i.kt)("h2",{id:"recommended-workflow"},"Recommended Workflow"),(0,i.kt)("ol",null,(0,i.kt)("li",{parentName:"ol"},"At least use layer 3 (Server-side push to GitHub.com) to protect the main branch from being pushed or merged if any secrets are detected."),(0,i.kt)("li",{parentName:"ol"},"If any secrets are detected during layer 3, you can:",(0,i.kt)("ul",{parentName:"li"},(0,i.kt)("li",{parentName:"ul"},"Clean the commit history of the branch",(0,i.kt)("ul",{parentName:"li"},(0,i.kt)("li",{parentName:"ul"},"To find out the files that needs clean, you can use layer 1's auditing feature as assistance"),(0,i.kt)("li",{parentName:"ul"},"If a secret has already been committed, visit\n",(0,i.kt)("a",{parentName:"li",href:"https://help.github.com/articles/removing-sensitive-data-from-a-repository"},"https://help.github.com/articles/removing-sensitive-data-from-a-repository")))))),(0,i.kt)("li",{parentName:"ol"},"Recommend to set up layer 2 (Git commit scan, client-side) for every developer",(0,i.kt)("ul",{parentName:"li"},(0,i.kt)("li",{parentName:"ul"},"It can minimize the chance of pushing secrets to the cloud"),(0,i.kt)("li",{parentName:"ul"},"Local files are easier to clean than GitHub commit history"))),(0,i.kt)("li",{parentName:"ol"},"Layer 1 (Full scan and audit, client-side) can be involved during each stage",(0,i.kt)("ul",{parentName:"li"},(0,i.kt)("li",{parentName:"ul"},"It helps you generate, update or analyze baseline file for layer 2 and 3")))),(0,i.kt)("mermaid",{value:'sequenceDiagram\n participant Dev as Developer\n participant GH as GitHub\n participant DS as Detect-Secrets\n participant L1 as Layer 1 (Full Scan & Audit)\n participant L2 as Layer 2 (Git Commit Scan)\n participant L3 as Layer 3 (Server-side Push to GitHub)\n\n Dev->>L3: Push/Merge to Main Branch\n L3->>DS: Scan for Secrets\n alt Secrets Detected in L3\n DS--\x3e>Dev: Secrets Detected\n Dev->>L1: Use Auditing Feature to Identify Files for Cleaning\n Note over L1: Assists in identifying files that need to be cleaned.
Recommend to manully double check detected files
due to "minimize noise" feature from detect-secrets\n Dev->>Dev: Clean Commit History\n Note over Dev: If a secret has already been committed, refer:
https://help.github.com/articles/removing-sensitive-data-from-a-repository\n Dev->>L2: Set Up Git Commit Scan\n Note over Dev, L2: Minimizes chances of pushing secrets
Easier to clean local files than GitHub commit history\n Dev->>L1: Use Full Scan & Audit at Each Stage\n Note over Dev, L1: Assists in generating, updating or analyzing baseline file for L2 and L3\n Dev->>L3: Retry Push/Merge to Main Branch\n else No Secrets Detected\n DS--\x3e>GH: No Secrets Detected\n GH->>Dev: Allows Push/Merge to Main Branch\n end\n'}),(0,i.kt)("h2",{id:"more-configurations"},"More Configurations"),(0,i.kt)("p",null,"Check out"),(0,i.kt)("ol",null,(0,i.kt)("li",{parentName:"ol"},(0,i.kt)("a",{parentName:"li",href:"https://github.com/Yelp/detect-secrets"},"detect-secrets")),(0,i.kt)("li",{parentName:"ol"},(0,i.kt)("a",{parentName:"li",href:"https://pre-commit.com/"},"pre-commit"))))}d.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/935f2afb.59a9bb66.js b/assets/js/935f2afb.cf15af51.js similarity index 98% rename from assets/js/935f2afb.59a9bb66.js rename to assets/js/935f2afb.cf15af51.js index c2742e3fd..d5b2f6475 100644 --- a/assets/js/935f2afb.59a9bb66.js +++ b/assets/js/935f2afb.cf15af51.js @@ -1 +1 @@ -"use strict";(self.webpackChunkdocusaurus=self.webpackChunkdocusaurus||[]).push([[53],{1109:e=>{e.exports=JSON.parse('{"pluginId":"default","version":"current","label":"Next","banner":null,"badge":false,"noIndex":false,"className":"docs-version-current","isLast":true,"docsSidebars":{"guidesSidebar":[{"type":"link","label":"Guides","href":"/slim/docs/guides/search","docId":"guides/search"},{"type":"category","label":"Software Lifecycle","collapsible":true,"collapsed":true,"items":[{"type":"category","label":"Application Starter Kits","collapsible":true,"collapsed":true,"items":[{"type":"link","label":"Python Starter Kit","href":"/slim/docs/guides/software-lifecycle/application-starter-kits/python-starter-kit/","docId":"guides/software-lifecycle/application-starter-kits/python-starter-kit/README"}],"href":"/slim/docs/category/application-starter-kits"},{"type":"category","label":"Security","collapsible":true,"collapsed":true,"items":[{"type":"link","label":"GitHub Security Best Practices","href":"/slim/docs/guides/software-lifecycle/security/github-security/","docId":"guides/software-lifecycle/security/github-security/README"},{"type":"link","label":"Secrets Detection","href":"/slim/docs/guides/software-lifecycle/security/secrets-detection/","docId":"guides/software-lifecycle/security/secrets-detection/README"}],"href":"/slim/docs/category/security"},{"type":"category","label":"Continuous Integration","collapsible":true,"collapsed":true,"items":[{"type":"link","label":"CI Tools and Frameworks","href":"/slim/docs/guides/software-lifecycle/continuous-integration/continuous-integration-frameworks","docId":"guides/software-lifecycle/continuous-integration/continuous-integration-frameworks"},{"type":"link","label":"CI Reference Architectures","href":"/slim/docs/guides/software-lifecycle/continuous-integration/reference-architecture","docId":"guides/software-lifecycle/continuous-integration/reference-architecture"}],"href":"/slim/docs/guides/software-lifecycle/continuous-integration/"},{"type":"category","label":"Continuous Testing","collapsible":true,"collapsed":true,"items":[{"type":"link","label":"Testing Frameworks","href":"/slim/docs/guides/software-lifecycle/continuous-testing/testing-frameworks","docId":"guides/software-lifecycle/continuous-testing/testing-frameworks"}],"href":"/slim/docs/guides/software-lifecycle/continuous-testing/"},{"type":"link","label":"Metrics","href":"/slim/docs/guides/software-lifecycle/metrics/","docId":"guides/software-lifecycle/metrics/README"}],"href":"/slim/docs/category/software-lifecycle"},{"type":"category","label":"Governance","collapsible":true,"collapsed":true,"items":[{"type":"category","label":"Contributions","collapsible":true,"collapsed":true,"items":[{"type":"link","label":"Code of Conduct","href":"/slim/docs/guides/governance/contributions/code-of-conduct/","docId":"guides/governance/contributions/code-of-conduct/README"},{"type":"category","label":"Contributing Guide","collapsible":true,"collapsed":true,"items":[{"type":"link","label":"CONTRIBUTING","href":"/slim/docs/guides/governance/contributions/contributing-guide/CONTRIBUTING","docId":"guides/governance/contributions/contributing-guide/CONTRIBUTING"}],"href":"/slim/docs/guides/governance/contributions/contributing-guide/"},{"type":"category","label":"Issue Templates","collapsible":true,"collapsed":true,"items":[{"type":"category","label":"Bug Reports","collapsible":true,"collapsed":true,"items":[{"type":"link","label":"bug_report","href":"/slim/docs/guides/governance/contributions/issue-templates/bug-reports/bug_report","docId":"guides/governance/contributions/issue-templates/bug-reports/bug_report"},{"type":"link","label":"bug_report.yml","href":"/slim/docs/guides/governance/contributions/issue-templates/bug-reports/bug_report.yml","docId":"guides/governance/contributions/issue-templates/bug-reports/bug_report.yml"}]},{"type":"category","label":"New Features","collapsible":true,"collapsed":true,"items":[{"type":"link","label":"new_feature","href":"/slim/docs/guides/governance/contributions/issue-templates/features/new_feature","docId":"guides/governance/contributions/issue-templates/features/new_feature"},{"type":"link","label":"new_feature.yml","href":"/slim/docs/guides/governance/contributions/issue-templates/features/new_feature.yml","docId":"guides/governance/contributions/issue-templates/features/new_feature.yml"}]}],"href":"/slim/docs/guides/governance/contributions/issue-templates/"},{"type":"category","label":"Pull Requests","collapsible":true,"collapsed":true,"items":[{"type":"link","label":"PULL_REQUEST_TEMPLATE","href":"/slim/docs/guides/governance/contributions/pull-requests/PULL_REQUEST_TEMPLATE","docId":"guides/governance/contributions/pull-requests/PULL_REQUEST_TEMPLATE"}],"href":"/slim/docs/guides/governance/contributions/pull-requests/"}],"href":"/slim/docs/category/contributions"},{"type":"category","label":"Governance Model","collapsible":true,"collapsed":true,"items":[{"type":"link","label":"GOVERNANCE-TEMPLATE","href":"/slim/docs/guides/governance/governance-model/GOVERNANCE-TEMPLATE","docId":"guides/governance/governance-model/GOVERNANCE-TEMPLATE"},{"type":"link","label":"governance-template-small-team","href":"/slim/docs/guides/governance/governance-model/governance-template-small-team","docId":"guides/governance/governance-model/governance-template-small-team"}],"href":"/slim/docs/guides/governance/governance-model/"}],"href":"/slim/docs/category/governance"},{"type":"category","label":"Documentation","collapsible":true,"collapsed":true,"items":[{"type":"link","label":"Change Log","href":"/slim/docs/guides/documentation/change-log/","docId":"guides/documentation/change-log/README"},{"type":"category","label":"Documentation Hosting","collapsible":true,"collapsed":true,"items":[{"type":"link","label":"Docs Hosting Trade Study","href":"/slim/docs/guides/documentation/documentation-hosts/trade-study-hostingdocs-user","docId":"guides/documentation/documentation-hosts/trade-study-hostingdocs-user"},{"type":"link","label":"Docs Use Cases","href":"/slim/docs/guides/documentation/documentation-hosts/use-cases","docId":"guides/documentation/documentation-hosts/use-cases"}],"href":"/slim/docs/guides/documentation/documentation-hosts/"},{"type":"category","label":"READMEs","collapsible":true,"collapsed":true,"items":[{"type":"link","label":"README Template","href":"/slim/docs/guides/documentation/readme/README-TEMPLATE","docId":"guides/documentation/readme/README-TEMPLATE"}],"href":"/slim/docs/guides/documentation/readme/"}],"href":"/slim/docs/category/documentation"}],"aboutSidebar":[{"type":"link","label":"About","href":"/slim/docs/about/","docId":"about/README"},{"type":"link","label":"Code of Conduct","href":"/slim/docs/about/CODE_OF_CONDUCT","docId":"about/CODE_OF_CONDUCT"},{"type":"link","label":"SLIM Project Governance","href":"/slim/docs/about/GOVERNANCE","docId":"about/GOVERNANCE"}],"contributeSidebar":[{"type":"link","label":"Submit a Best Practice Guide","href":"/slim/docs/contribute/submit-best-practice","docId":"contribute/submit-best-practice"},{"type":"category","label":"Contributing 101","collapsible":true,"collapsed":true,"items":[{"type":"link","label":"Introduction","href":"/slim/docs/contribute/contributing/introduction","docId":"contribute/contributing/introduction"},{"type":"link","label":"Know Before you Contribute","href":"/slim/docs/contribute/contributing/know-before-contribute","docId":"contribute/contributing/know-before-contribute"},{"type":"link","label":"Our Development Process","href":"/slim/docs/contribute/contributing/development-process","docId":"contribute/contributing/development-process"},{"type":"link","label":"Ways to Contribute","href":"/slim/docs/contribute/contributing/ways-to-contribute","docId":"contribute/contributing/ways-to-contribute"}],"href":"/slim/docs/contribute/contributing/"}]},"docs":{"about/CODE_OF_CONDUCT":{"id":"about/CODE_OF_CONDUCT","title":"Code of Conduct","description":"Our Pledge","sidebar":"aboutSidebar"},"about/GOVERNANCE":{"id":"about/GOVERNANCE","title":"SLIM Project Governance","description":"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 SLIM community and beyond, including from private organizations, universities, government organizations, and international organizations.","sidebar":"aboutSidebar"},"about/README":{"id":"about/README","title":"About","description":"A shared resource for discussing, iterating and referencing best practices in software lifecycle process improvements for multi-mission space and ground software","sidebar":"aboutSidebar"},"contribute/contributing/development-process":{"id":"contribute/contributing/development-process","title":"Our Development Process","description":"Our project integrates contributions from many people, and so we\'d like to outline a process you can use to visualize how your contributions may be integrated if you provide something.","sidebar":"contributeSidebar"},"contribute/contributing/index":{"id":"contribute/contributing/index","title":"Contributing 101","description":"Thanks for taking the time to consider contributing! We very much appreciate your time and effort. This document outlines the many ways you can contribute to our project, and provides detailed guidance on best practices. We look forward to your help!","sidebar":"contributeSidebar"},"contribute/contributing/introduction":{"id":"contribute/contributing/introduction","title":"Introduction","description":"SLIM is a joint, community-based effort at collective software process improvements. Therefore, we need your help! Here\'s the basics on contributing:","sidebar":"contributeSidebar"},"contribute/contributing/know-before-contribute":{"id":"contribute/contributing/know-before-contribute","title":"Know Before you Contribute","description":"Before you begin contributing to our project, it\'ll be a good idea to ensure you\'ve satisfied the below pre-requisites.","sidebar":"contributeSidebar"},"contribute/contributing/ways-to-contribute":{"id":"contribute/contributing/ways-to-contribute","title":"Ways to Contribute","description":"\ud83d\udcd6 Best Practice Guides","sidebar":"contributeSidebar"},"contribute/submit-best-practice":{"id":"contribute/submit-best-practice","title":"Submit a Best Practice Guide","description":"Are you interested in submitting a best practice guide to the SLIM project? You\'ve come to the right place!","sidebar":"contributeSidebar"},"guides/documentation/change-log/README":{"id":"guides/documentation/change-log/README","title":"Change Log","description":"A guide for setting up a log to document software changes in a human-centric format.","sidebar":"guidesSidebar"},"guides/documentation/documentation-hosts/README":{"id":"guides/documentation/documentation-hosts/README","title":"Documentation Hosting","description":"Guidance on selecting and implementing documentation hosting tools.","sidebar":"guidesSidebar"},"guides/documentation/documentation-hosts/trade-study-hostingdocs-user":{"id":"guides/documentation/documentation-hosts/trade-study-hostingdocs-user","title":"Docs Hosting Trade Study","description":"| 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 |","sidebar":"guidesSidebar"},"guides/documentation/documentation-hosts/use-cases":{"id":"guides/documentation/documentation-hosts/use-cases","title":"Docs Use Cases","description":"* Documentation Best Practices","sidebar":"guidesSidebar"},"guides/documentation/readme/index":{"id":"guides/documentation/readme/index","title":"READMEs","description":"A guide to constructing an effective and impressive README for your project.","sidebar":"guidesSidebar"},"guides/documentation/readme/README-TEMPLATE":{"id":"guides/documentation/readme/README-TEMPLATE","title":"README Template","description":"","sidebar":"guidesSidebar"},"guides/governance/contributions/code-of-conduct/README":{"id":"guides/governance/contributions/code-of-conduct/README","title":"Code of Conduct","description":"A walkthrough on setting up a code-of-conduct policy for your project.","sidebar":"guidesSidebar"},"guides/governance/contributions/contributing-guide/CONTRIBUTING":{"id":"guides/governance/contributions/contributing-guide/CONTRIBUTING","title":"CONTRIBUTING","description":"","sidebar":"guidesSidebar"},"guides/governance/contributions/contributing-guide/README":{"id":"guides/governance/contributions/contributing-guide/README","title":"Contributing Guide","description":"Fast track developing a contribution guide for your new contributors.","sidebar":"guidesSidebar"},"guides/governance/contributions/issue-templates/bug-reports/bug_report":{"id":"guides/governance/contributions/issue-templates/bug-reports/bug_report","title":"bug_report","description":"","sidebar":"guidesSidebar"},"guides/governance/contributions/issue-templates/bug-reports/bug_report.yml":{"id":"guides/governance/contributions/issue-templates/bug-reports/bug_report.yml","title":"bug_report.yml","description":"","sidebar":"guidesSidebar"},"guides/governance/contributions/issue-templates/features/new_feature":{"id":"guides/governance/contributions/issue-templates/features/new_feature","title":"new_feature","description":"","sidebar":"guidesSidebar"},"guides/governance/contributions/issue-templates/features/new_feature.yml":{"id":"guides/governance/contributions/issue-templates/features/new_feature.yml","title":"new_feature.yml","description":"","sidebar":"guidesSidebar"},"guides/governance/contributions/issue-templates/README":{"id":"guides/governance/contributions/issue-templates/README","title":"Issue Templates","description":"Make issue tracking clear and consistent with structured issue templates for your contributors.","sidebar":"guidesSidebar"},"guides/governance/contributions/pull-requests/PULL_REQUEST_TEMPLATE":{"id":"guides/governance/contributions/pull-requests/PULL_REQUEST_TEMPLATE","title":"PULL_REQUEST_TEMPLATE","description":"","sidebar":"guidesSidebar"},"guides/governance/contributions/pull-requests/README":{"id":"guides/governance/contributions/pull-requests/README","title":"Pull Requests","description":"A walk-through on using our standardized template for pull requests.","sidebar":"guidesSidebar"},"guides/governance/governance-model/GOVERNANCE-TEMPLATE":{"id":"guides/governance/governance-model/GOVERNANCE-TEMPLATE","title":"GOVERNANCE-TEMPLATE","description":"","sidebar":"guidesSidebar"},"guides/governance/governance-model/governance-template-small-team":{"id":"guides/governance/governance-model/governance-template-small-team","title":"governance-template-small-team","description":"","sidebar":"guidesSidebar"},"guides/governance/governance-model/README":{"id":"guides/governance/governance-model/README","title":"Governance Model","description":"Establish a project guide for effective open source governance.","sidebar":"guidesSidebar"},"guides/search":{"id":"guides/search","title":"Guides","description":"Explore our guides via the categories below or the left-hand navigation. You may also search our guides.","sidebar":"guidesSidebar"},"guides/software-lifecycle/application-starter-kits/python-starter-kit/README":{"id":"guides/software-lifecycle/application-starter-kits/python-starter-kit/README","title":"Python Starter Kit","description":"A deployment-ready Python 3 application template for quick, standards-based project setup.","sidebar":"guidesSidebar"},"guides/software-lifecycle/continuous-integration/continuous-integration-frameworks":{"id":"guides/software-lifecycle/continuous-integration/continuous-integration-frameworks","title":"CI Tools and Frameworks","description":"* Continuous Integration","sidebar":"guidesSidebar"},"guides/software-lifecycle/continuous-integration/README":{"id":"guides/software-lifecycle/continuous-integration/README","title":"Continuous Integration","description":"A guide for implementing continuous integration in software projects.","sidebar":"guidesSidebar"},"guides/software-lifecycle/continuous-integration/reference-architecture":{"id":"guides/software-lifecycle/continuous-integration/reference-architecture","title":"CI Reference Architectures","description":"Overview","sidebar":"guidesSidebar"},"guides/software-lifecycle/continuous-testing/README":{"id":"guides/software-lifecycle/continuous-testing/README","title":"Continuous Testing","description":"Use Cases and Frameworks","sidebar":"guidesSidebar"},"guides/software-lifecycle/continuous-testing/testing-frameworks":{"id":"guides/software-lifecycle/continuous-testing/testing-frameworks","title":"Testing Frameworks","description":"* Continuous Testing","sidebar":"guidesSidebar"},"guides/software-lifecycle/metrics/README":{"id":"guides/software-lifecycle/metrics/README","title":"Metrics","description":"A Guide for Configuring and Deploying Software Lifecycle Metrics Tracking.","sidebar":"guidesSidebar"},"guides/software-lifecycle/security/github-security/README":{"id":"guides/software-lifecycle/security/github-security/README","title":"GitHub Security Best Practices","description":"Recommendations for enabling GitHub security features for your repositories.","sidebar":"guidesSidebar"},"guides/software-lifecycle/security/secrets-detection/README":{"id":"guides/software-lifecycle/security/secrets-detection/README","title":"Secrets Detection","description":"We recommend 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,","sidebar":"guidesSidebar"}}}')}}]); \ No newline at end of file +"use strict";(self.webpackChunkdocusaurus=self.webpackChunkdocusaurus||[]).push([[53],{1109:e=>{e.exports=JSON.parse('{"pluginId":"default","version":"current","label":"Next","banner":null,"badge":false,"noIndex":false,"className":"docs-version-current","isLast":true,"docsSidebars":{"guidesSidebar":[{"type":"link","label":"Guides","href":"/slim/docs/guides/search","docId":"guides/search"},{"type":"category","label":"Software Lifecycle","collapsible":true,"collapsed":true,"items":[{"type":"category","label":"Application Starter Kits","collapsible":true,"collapsed":true,"items":[{"type":"link","label":"Python Starter Kit","href":"/slim/docs/guides/software-lifecycle/application-starter-kits/python-starter-kit/","docId":"guides/software-lifecycle/application-starter-kits/python-starter-kit/README"}],"href":"/slim/docs/category/application-starter-kits"},{"type":"category","label":"Security","collapsible":true,"collapsed":true,"items":[{"type":"link","label":"GitHub Security Best Practices","href":"/slim/docs/guides/software-lifecycle/security/github-security/","docId":"guides/software-lifecycle/security/github-security/README"},{"type":"link","label":"Secrets Detection","href":"/slim/docs/guides/software-lifecycle/security/secrets-detection/","docId":"guides/software-lifecycle/security/secrets-detection/README"}],"href":"/slim/docs/category/security"},{"type":"category","label":"Continuous Integration","collapsible":true,"collapsed":true,"items":[{"type":"link","label":"CI Tools and Frameworks","href":"/slim/docs/guides/software-lifecycle/continuous-integration/continuous-integration-frameworks","docId":"guides/software-lifecycle/continuous-integration/continuous-integration-frameworks"},{"type":"link","label":"CI Reference Architectures","href":"/slim/docs/guides/software-lifecycle/continuous-integration/reference-architecture","docId":"guides/software-lifecycle/continuous-integration/reference-architecture"}],"href":"/slim/docs/guides/software-lifecycle/continuous-integration/"},{"type":"category","label":"Continuous Testing","collapsible":true,"collapsed":true,"items":[{"type":"link","label":"Testing Frameworks","href":"/slim/docs/guides/software-lifecycle/continuous-testing/testing-frameworks","docId":"guides/software-lifecycle/continuous-testing/testing-frameworks"}],"href":"/slim/docs/guides/software-lifecycle/continuous-testing/"},{"type":"link","label":"Metrics","href":"/slim/docs/guides/software-lifecycle/metrics/","docId":"guides/software-lifecycle/metrics/README"}],"href":"/slim/docs/category/software-lifecycle"},{"type":"category","label":"Governance","collapsible":true,"collapsed":true,"items":[{"type":"category","label":"Contributions","collapsible":true,"collapsed":true,"items":[{"type":"link","label":"Code of Conduct","href":"/slim/docs/guides/governance/contributions/code-of-conduct/","docId":"guides/governance/contributions/code-of-conduct/README"},{"type":"category","label":"Contributing Guide","collapsible":true,"collapsed":true,"items":[{"type":"link","label":"CONTRIBUTING","href":"/slim/docs/guides/governance/contributions/contributing-guide/CONTRIBUTING","docId":"guides/governance/contributions/contributing-guide/CONTRIBUTING"}],"href":"/slim/docs/guides/governance/contributions/contributing-guide/"},{"type":"category","label":"Issue Templates","collapsible":true,"collapsed":true,"items":[{"type":"category","label":"Bug Reports","collapsible":true,"collapsed":true,"items":[{"type":"link","label":"bug_report","href":"/slim/docs/guides/governance/contributions/issue-templates/bug-reports/bug_report","docId":"guides/governance/contributions/issue-templates/bug-reports/bug_report"},{"type":"link","label":"bug_report.yml","href":"/slim/docs/guides/governance/contributions/issue-templates/bug-reports/bug_report.yml","docId":"guides/governance/contributions/issue-templates/bug-reports/bug_report.yml"}]},{"type":"category","label":"New Features","collapsible":true,"collapsed":true,"items":[{"type":"link","label":"new_feature","href":"/slim/docs/guides/governance/contributions/issue-templates/features/new_feature","docId":"guides/governance/contributions/issue-templates/features/new_feature"},{"type":"link","label":"new_feature.yml","href":"/slim/docs/guides/governance/contributions/issue-templates/features/new_feature.yml","docId":"guides/governance/contributions/issue-templates/features/new_feature.yml"}]}],"href":"/slim/docs/guides/governance/contributions/issue-templates/"},{"type":"category","label":"Pull Requests","collapsible":true,"collapsed":true,"items":[{"type":"link","label":"PULL_REQUEST_TEMPLATE","href":"/slim/docs/guides/governance/contributions/pull-requests/PULL_REQUEST_TEMPLATE","docId":"guides/governance/contributions/pull-requests/PULL_REQUEST_TEMPLATE"}],"href":"/slim/docs/guides/governance/contributions/pull-requests/"}],"href":"/slim/docs/category/contributions"},{"type":"category","label":"Governance Model","collapsible":true,"collapsed":true,"items":[{"type":"link","label":"GOVERNANCE-TEMPLATE","href":"/slim/docs/guides/governance/governance-model/GOVERNANCE-TEMPLATE","docId":"guides/governance/governance-model/GOVERNANCE-TEMPLATE"},{"type":"link","label":"governance-template-small-team","href":"/slim/docs/guides/governance/governance-model/governance-template-small-team","docId":"guides/governance/governance-model/governance-template-small-team"}],"href":"/slim/docs/guides/governance/governance-model/"}],"href":"/slim/docs/category/governance"},{"type":"category","label":"Documentation","collapsible":true,"collapsed":true,"items":[{"type":"link","label":"Change Log","href":"/slim/docs/guides/documentation/change-log/","docId":"guides/documentation/change-log/README"},{"type":"category","label":"Documentation Hosting","collapsible":true,"collapsed":true,"items":[{"type":"link","label":"Docs Hosting Trade Study","href":"/slim/docs/guides/documentation/documentation-hosts/trade-study-hostingdocs-user","docId":"guides/documentation/documentation-hosts/trade-study-hostingdocs-user"},{"type":"link","label":"Docs Use Cases","href":"/slim/docs/guides/documentation/documentation-hosts/use-cases","docId":"guides/documentation/documentation-hosts/use-cases"}],"href":"/slim/docs/guides/documentation/documentation-hosts/"},{"type":"category","label":"READMEs","collapsible":true,"collapsed":true,"items":[{"type":"link","label":"README Template","href":"/slim/docs/guides/documentation/readme/README-TEMPLATE","docId":"guides/documentation/readme/README-TEMPLATE"}],"href":"/slim/docs/guides/documentation/readme/"}],"href":"/slim/docs/category/documentation"}],"aboutSidebar":[{"type":"link","label":"About","href":"/slim/docs/about/","docId":"about/README"},{"type":"link","label":"Code of Conduct","href":"/slim/docs/about/CODE_OF_CONDUCT","docId":"about/CODE_OF_CONDUCT"},{"type":"link","label":"SLIM Project Governance","href":"/slim/docs/about/GOVERNANCE","docId":"about/GOVERNANCE"}],"contributeSidebar":[{"type":"link","label":"Submit a Best Practice Guide","href":"/slim/docs/contribute/submit-best-practice","docId":"contribute/submit-best-practice"},{"type":"category","label":"Contributing 101","collapsible":true,"collapsed":true,"items":[{"type":"link","label":"Introduction","href":"/slim/docs/contribute/contributing/introduction","docId":"contribute/contributing/introduction"},{"type":"link","label":"Know Before you Contribute","href":"/slim/docs/contribute/contributing/know-before-contribute","docId":"contribute/contributing/know-before-contribute"},{"type":"link","label":"Our Development Process","href":"/slim/docs/contribute/contributing/development-process","docId":"contribute/contributing/development-process"},{"type":"link","label":"Ways to Contribute","href":"/slim/docs/contribute/contributing/ways-to-contribute","docId":"contribute/contributing/ways-to-contribute"}],"href":"/slim/docs/contribute/contributing/"}]},"docs":{"about/CODE_OF_CONDUCT":{"id":"about/CODE_OF_CONDUCT","title":"Code of Conduct","description":"Our Pledge","sidebar":"aboutSidebar"},"about/GOVERNANCE":{"id":"about/GOVERNANCE","title":"SLIM Project Governance","description":"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 SLIM community and beyond, including from private organizations, universities, government organizations, and international organizations.","sidebar":"aboutSidebar"},"about/README":{"id":"about/README","title":"About","description":"A shared resource for discussing, iterating and referencing best practices in software lifecycle process improvements for multi-mission space and ground software","sidebar":"aboutSidebar"},"contribute/contributing/development-process":{"id":"contribute/contributing/development-process","title":"Our Development Process","description":"Our project integrates contributions from many people, and so we\'d like to outline a process you can use to visualize how your contributions may be integrated if you provide something.","sidebar":"contributeSidebar"},"contribute/contributing/index":{"id":"contribute/contributing/index","title":"Contributing 101","description":"Thanks for taking the time to consider contributing! We very much appreciate your time and effort. This document outlines the many ways you can contribute to our project, and provides detailed guidance on best practices. We look forward to your help!","sidebar":"contributeSidebar"},"contribute/contributing/introduction":{"id":"contribute/contributing/introduction","title":"Introduction","description":"SLIM is a joint, community-based effort at collective software process improvements. Therefore, we need your help! Here\'s the basics on contributing:","sidebar":"contributeSidebar"},"contribute/contributing/know-before-contribute":{"id":"contribute/contributing/know-before-contribute","title":"Know Before you Contribute","description":"Before you begin contributing to our project, it\'ll be a good idea to ensure you\'ve satisfied the below pre-requisites.","sidebar":"contributeSidebar"},"contribute/contributing/ways-to-contribute":{"id":"contribute/contributing/ways-to-contribute","title":"Ways to Contribute","description":"\ud83d\udcd6 Best Practice Guides","sidebar":"contributeSidebar"},"contribute/submit-best-practice":{"id":"contribute/submit-best-practice","title":"Submit a Best Practice Guide","description":"Are you interested in submitting a best practice guide to the SLIM project? You\'ve come to the right place!","sidebar":"contributeSidebar"},"guides/documentation/change-log/README":{"id":"guides/documentation/change-log/README","title":"Change Log","description":"A guide for setting up a log to document software changes in a human-centric format.","sidebar":"guidesSidebar"},"guides/documentation/documentation-hosts/README":{"id":"guides/documentation/documentation-hosts/README","title":"Documentation Hosting","description":"Guidance on selecting and implementing documentation hosting tools.","sidebar":"guidesSidebar"},"guides/documentation/documentation-hosts/trade-study-hostingdocs-user":{"id":"guides/documentation/documentation-hosts/trade-study-hostingdocs-user","title":"Docs Hosting Trade Study","description":"| 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 |","sidebar":"guidesSidebar"},"guides/documentation/documentation-hosts/use-cases":{"id":"guides/documentation/documentation-hosts/use-cases","title":"Docs Use Cases","description":"* Documentation Best Practices","sidebar":"guidesSidebar"},"guides/documentation/readme/index":{"id":"guides/documentation/readme/index","title":"READMEs","description":"A guide to constructing an effective and impressive README for your project.","sidebar":"guidesSidebar"},"guides/documentation/readme/README-TEMPLATE":{"id":"guides/documentation/readme/README-TEMPLATE","title":"README Template","description":"","sidebar":"guidesSidebar"},"guides/governance/contributions/code-of-conduct/README":{"id":"guides/governance/contributions/code-of-conduct/README","title":"Code of Conduct","description":"A walkthrough on setting up a code-of-conduct policy for your project.","sidebar":"guidesSidebar"},"guides/governance/contributions/contributing-guide/CONTRIBUTING":{"id":"guides/governance/contributions/contributing-guide/CONTRIBUTING","title":"CONTRIBUTING","description":"","sidebar":"guidesSidebar"},"guides/governance/contributions/contributing-guide/README":{"id":"guides/governance/contributions/contributing-guide/README","title":"Contributing Guide","description":"Fast track developing a contribution guide for your new contributors.","sidebar":"guidesSidebar"},"guides/governance/contributions/issue-templates/bug-reports/bug_report":{"id":"guides/governance/contributions/issue-templates/bug-reports/bug_report","title":"bug_report","description":"","sidebar":"guidesSidebar"},"guides/governance/contributions/issue-templates/bug-reports/bug_report.yml":{"id":"guides/governance/contributions/issue-templates/bug-reports/bug_report.yml","title":"bug_report.yml","description":"","sidebar":"guidesSidebar"},"guides/governance/contributions/issue-templates/features/new_feature":{"id":"guides/governance/contributions/issue-templates/features/new_feature","title":"new_feature","description":"","sidebar":"guidesSidebar"},"guides/governance/contributions/issue-templates/features/new_feature.yml":{"id":"guides/governance/contributions/issue-templates/features/new_feature.yml","title":"new_feature.yml","description":"","sidebar":"guidesSidebar"},"guides/governance/contributions/issue-templates/README":{"id":"guides/governance/contributions/issue-templates/README","title":"Issue Templates","description":"Make issue tracking clear and consistent with structured issue templates for your contributors.","sidebar":"guidesSidebar"},"guides/governance/contributions/pull-requests/PULL_REQUEST_TEMPLATE":{"id":"guides/governance/contributions/pull-requests/PULL_REQUEST_TEMPLATE","title":"PULL_REQUEST_TEMPLATE","description":"","sidebar":"guidesSidebar"},"guides/governance/contributions/pull-requests/README":{"id":"guides/governance/contributions/pull-requests/README","title":"Pull Requests","description":"A walk-through on using our standardized template for pull requests.","sidebar":"guidesSidebar"},"guides/governance/governance-model/GOVERNANCE-TEMPLATE":{"id":"guides/governance/governance-model/GOVERNANCE-TEMPLATE","title":"GOVERNANCE-TEMPLATE","description":"","sidebar":"guidesSidebar"},"guides/governance/governance-model/governance-template-small-team":{"id":"guides/governance/governance-model/governance-template-small-team","title":"governance-template-small-team","description":"","sidebar":"guidesSidebar"},"guides/governance/governance-model/README":{"id":"guides/governance/governance-model/README","title":"Governance Model","description":"Establish a project guide for effective open source governance.","sidebar":"guidesSidebar"},"guides/search":{"id":"guides/search","title":"Guides","description":"Explore our guides via the categories below or the left-hand navigation. You may also search our guides.","sidebar":"guidesSidebar"},"guides/software-lifecycle/application-starter-kits/python-starter-kit/README":{"id":"guides/software-lifecycle/application-starter-kits/python-starter-kit/README","title":"Python Starter Kit","description":"A deployment-ready Python 3 application template for quick, standards-based project setup.","sidebar":"guidesSidebar"},"guides/software-lifecycle/continuous-integration/continuous-integration-frameworks":{"id":"guides/software-lifecycle/continuous-integration/continuous-integration-frameworks","title":"CI Tools and Frameworks","description":"* Continuous Integration","sidebar":"guidesSidebar"},"guides/software-lifecycle/continuous-integration/README":{"id":"guides/software-lifecycle/continuous-integration/README","title":"Continuous Integration","description":"A guide for implementing continuous integration in software projects.","sidebar":"guidesSidebar"},"guides/software-lifecycle/continuous-integration/reference-architecture":{"id":"guides/software-lifecycle/continuous-integration/reference-architecture","title":"CI Reference Architectures","description":"Overview","sidebar":"guidesSidebar"},"guides/software-lifecycle/continuous-testing/README":{"id":"guides/software-lifecycle/continuous-testing/README","title":"Continuous Testing","description":"Use Cases and Frameworks","sidebar":"guidesSidebar"},"guides/software-lifecycle/continuous-testing/testing-frameworks":{"id":"guides/software-lifecycle/continuous-testing/testing-frameworks","title":"Testing Frameworks","description":"* Continuous Testing","sidebar":"guidesSidebar"},"guides/software-lifecycle/metrics/README":{"id":"guides/software-lifecycle/metrics/README","title":"Metrics","description":"A Guide for Configuring and Deploying Software Lifecycle Metrics Tracking.","sidebar":"guidesSidebar"},"guides/software-lifecycle/security/github-security/README":{"id":"guides/software-lifecycle/security/github-security/README","title":"GitHub Security Best Practices","description":"Recommendations for enabling GitHub security features for your repositories.","sidebar":"guidesSidebar"},"guides/software-lifecycle/security/secrets-detection/README":{"id":"guides/software-lifecycle/security/secrets-detection/README","title":"Secrets Detection","description":"Guide to identify and automatically prevent leaking of sensitive information into your codebase.","sidebar":"guidesSidebar"}}}')}}]); \ No newline at end of file diff --git a/assets/js/runtime~main.7db9f74e.js b/assets/js/runtime~main.585d56fd.js similarity index 72% rename from assets/js/runtime~main.7db9f74e.js rename to assets/js/runtime~main.585d56fd.js index 5be2ad5eb..790417c27 100644 --- a/assets/js/runtime~main.7db9f74e.js +++ b/assets/js/runtime~main.585d56fd.js @@ -1 +1 @@ -(()=>{"use strict";var e,a,c,f,d,b={},t={};function r(e){var a=t[e];if(void 0!==a)return a.exports;var c=t[e]={id:e,loaded:!1,exports:{}};return b[e].call(c.exports,c,c.exports,r),c.loaded=!0,c.exports}r.m=b,r.c=t,e=[],r.O=(a,c,f,d)=>{if(!c){var b=1/0;for(i=0;i=d)&&Object.keys(r.O).every((e=>r.O[e](c[o])))?c.splice(o--,1):(t=!1,d0&&e[i-1][2]>d;i--)e[i]=e[i-1];e[i]=[c,f,d]},r.n=e=>{var a=e&&e.__esModule?()=>e.default:()=>e;return r.d(a,{a:a}),a},c=Object.getPrototypeOf?e=>Object.getPrototypeOf(e):e=>e.__proto__,r.t=function(e,f){if(1&f&&(e=this(e)),8&f)return e;if("object"==typeof e&&e){if(4&f&&e.__esModule)return e;if(16&f&&"function"==typeof e.then)return e}var d=Object.create(null);r.r(d);var b={};a=a||[null,c({}),c([]),c(c)];for(var t=2&f&&e;"object"==typeof t&&!~a.indexOf(t);t=c(t))Object.getOwnPropertyNames(t).forEach((a=>b[a]=()=>e[a]));return b.default=()=>e,r.d(d,b),d},r.d=(e,a)=>{for(var c in a)r.o(a,c)&&!r.o(e,c)&&Object.defineProperty(e,c,{enumerable:!0,get:a[c]})},r.f={},r.e=e=>Promise.all(Object.keys(r.f).reduce(((a,c)=>(r.f[c](e,a),a)),[])),r.u=e=>"assets/js/"+({46:"ca705c4a",53:"935f2afb",150:"32de2db0",292:"1937bb63",380:"22251b09",493:"ed7f1a16",874:"8276c122",948:"8717b14a",1757:"cd95f078",1914:"d9f32620",2031:"8c4308b7",2049:"2bc4934e",2052:"69878e35",2081:"73e4d764",2119:"c612d4a7",2213:"39680a00",2249:"f26fc996",2267:"59362658",2362:"e273c56f",2475:"1375824b",2535:"814f3328",2608:"d52baca9",2774:"6d6ba527",3021:"c36b7e6b",3085:"1f391b9e",3089:"a6aa9e1f",3514:"73664a40",3608:"9e4087bc",3662:"b76a362f",3689:"c441f7d5",3842:"4317fbf7",4013:"01a85c17",4024:"6fb1fe71",4081:"719b1851",4103:"684aec4d",4173:"3b327884",4195:"c4f5d8e4",4227:"d5decc06",4555:"e0d5b996",4642:"b741a796",5178:"d07f8614",5242:"de1ef56c",5288:"4c9dd493",5307:"f1e6a692",5620:"e9025b0e",5680:"c2f4afbb",6004:"a729c412",6047:"5a59ea68",6103:"ccc49370",6189:"91db1580",6677:"2f60f69a",7075:"be00f8f0",7170:"cb227d72",7275:"b4deb335",7352:"41244d51",7414:"393be207",7649:"da286ece",7890:"51f4fcc3",7918:"17896441",7972:"c2d7cd96",8059:"7a337337",8361:"3cc55dcd",8400:"21821687",8558:"1fb8531c",8610:"6875c492",8636:"f4f34a3a",8671:"325c7275",8780:"8facacb8",8793:"403f595d",9003:"925b3f96",9278:"cdace248",9402:"64fc4b83",9510:"0ee94099",9514:"1be78505",9554:"ac7d2b3d",9642:"7661071f",9721:"3b13db8a",9817:"14eb3368",9959:"f25b6166"}[e]||e)+"."+{46:"42cbb196",53:"59a9bb66",150:"ef9e1596",292:"c01fcc43",380:"d8a93ec4",493:"6470d80e",874:"b8e4706e",948:"914d35ec",1098:"06d2c692",1757:"88e6a440",1914:"8aa602a6",2031:"98e99271",2049:"63c5560d",2052:"f01ce896",2081:"eda107b5",2119:"d79501aa",2213:"7d42604e",2249:"ded78440",2267:"4445c936",2362:"0e41ec1f",2475:"0eff4db0",2529:"36c3bab3",2535:"743a3596",2608:"93fe4de6",2774:"40d4b3b5",3021:"dfc94606",3085:"b260a6c5",3089:"a59b6240",3514:"a2ef6c76",3608:"fd66296e",3662:"fbd93ba2",3689:"fb308300",3842:"06fa1c2c",4013:"298b1a20",4024:"1edfdccc",4081:"5489bd4c",4103:"fcc6bc30",4173:"0732cef7",4195:"814258f0",4227:"fb746336",4555:"d9db6088",4642:"e68df027",4972:"71e74212",5178:"7b874a4b",5242:"3c4d2b0b",5288:"791558f2",5307:"1a0ccef4",5620:"57b28c92",5680:"0277c7b0",6004:"06e106c5",6047:"4c43887d",6103:"a04a9b88",6189:"7a4c742e",6316:"e253b8dd",6677:"ab253a10",7075:"3f5f6938",7170:"4bffee7f",7275:"4d0a6c31",7352:"c4bd9d9b",7414:"2b6bec03",7649:"af8db11e",7724:"1ce4c8a5",7890:"b298b17c",7918:"c879fc52",7972:"321d5c84",8059:"fdddc084",8361:"49174da4",8400:"5cce832b",8558:"6ee91e0a",8610:"7dbfa267",8636:"ec4f7a24",8671:"ca7f10df",8780:"af109432",8793:"fbcc0f20",9003:"39c96a76",9278:"98c4f9dd",9402:"8763c510",9487:"1902e0d9",9510:"d97cafc7",9514:"8f5a31ba",9554:"72fe38ed",9620:"b536c143",9642:"4eb2b4ef",9721:"9606fcc4",9817:"7e910f19",9959:"c6d206b1"}[e]+".js",r.miniCssF=e=>{},r.g=function(){if("object"==typeof globalThis)return globalThis;try{return this||new Function("return this")()}catch(e){if("object"==typeof window)return window}}(),r.o=(e,a)=>Object.prototype.hasOwnProperty.call(e,a),f={},d="docusaurus:",r.l=(e,a,c,b)=>{if(f[e])f[e].push(a);else{var t,o;if(void 0!==c)for(var n=document.getElementsByTagName("script"),i=0;i{t.onerror=t.onload=null,clearTimeout(s);var d=f[e];if(delete f[e],t.parentNode&&t.parentNode.removeChild(t),d&&d.forEach((e=>e(c))),a)return a(c)},s=setTimeout(l.bind(null,void 0,{type:"timeout",target:t}),12e4);t.onerror=l.bind(null,t.onerror),t.onload=l.bind(null,t.onload),o&&document.head.appendChild(t)}},r.r=e=>{"undefined"!=typeof Symbol&&Symbol.toStringTag&&Object.defineProperty(e,Symbol.toStringTag,{value:"Module"}),Object.defineProperty(e,"__esModule",{value:!0})},r.p="/slim/",r.gca=function(e){return e={17896441:"7918",21821687:"8400",59362658:"2267",ca705c4a:"46","935f2afb":"53","32de2db0":"150","1937bb63":"292","22251b09":"380",ed7f1a16:"493","8276c122":"874","8717b14a":"948",cd95f078:"1757",d9f32620:"1914","8c4308b7":"2031","2bc4934e":"2049","69878e35":"2052","73e4d764":"2081",c612d4a7:"2119","39680a00":"2213",f26fc996:"2249",e273c56f:"2362","1375824b":"2475","814f3328":"2535",d52baca9:"2608","6d6ba527":"2774",c36b7e6b:"3021","1f391b9e":"3085",a6aa9e1f:"3089","73664a40":"3514","9e4087bc":"3608",b76a362f:"3662",c441f7d5:"3689","4317fbf7":"3842","01a85c17":"4013","6fb1fe71":"4024","719b1851":"4081","684aec4d":"4103","3b327884":"4173",c4f5d8e4:"4195",d5decc06:"4227",e0d5b996:"4555",b741a796:"4642",d07f8614:"5178",de1ef56c:"5242","4c9dd493":"5288",f1e6a692:"5307",e9025b0e:"5620",c2f4afbb:"5680",a729c412:"6004","5a59ea68":"6047",ccc49370:"6103","91db1580":"6189","2f60f69a":"6677",be00f8f0:"7075",cb227d72:"7170",b4deb335:"7275","41244d51":"7352","393be207":"7414",da286ece:"7649","51f4fcc3":"7890",c2d7cd96:"7972","7a337337":"8059","3cc55dcd":"8361","1fb8531c":"8558","6875c492":"8610",f4f34a3a:"8636","325c7275":"8671","8facacb8":"8780","403f595d":"8793","925b3f96":"9003",cdace248:"9278","64fc4b83":"9402","0ee94099":"9510","1be78505":"9514",ac7d2b3d:"9554","7661071f":"9642","3b13db8a":"9721","14eb3368":"9817",f25b6166:"9959"}[e]||e,r.p+r.u(e)},(()=>{var e={1303:0,532:0};r.f.j=(a,c)=>{var f=r.o(e,a)?e[a]:void 0;if(0!==f)if(f)c.push(f[2]);else if(/^(1303|532)$/.test(a))e[a]=0;else{var d=new Promise(((c,d)=>f=e[a]=[c,d]));c.push(f[2]=d);var b=r.p+r.u(a),t=new Error;r.l(b,(c=>{if(r.o(e,a)&&(0!==(f=e[a])&&(e[a]=void 0),f)){var d=c&&("load"===c.type?"missing":c.type),b=c&&c.target&&c.target.src;t.message="Loading chunk "+a+" failed.\n("+d+": "+b+")",t.name="ChunkLoadError",t.type=d,t.request=b,f[1](t)}}),"chunk-"+a,a)}},r.O.j=a=>0===e[a];var a=(a,c)=>{var f,d,b=c[0],t=c[1],o=c[2],n=0;if(b.some((a=>0!==e[a]))){for(f in t)r.o(t,f)&&(r.m[f]=t[f]);if(o)var i=o(r)}for(a&&a(c);n{"use strict";var e,a,c,d,f,b={},t={};function r(e){var a=t[e];if(void 0!==a)return a.exports;var c=t[e]={id:e,loaded:!1,exports:{}};return b[e].call(c.exports,c,c.exports,r),c.loaded=!0,c.exports}r.m=b,r.c=t,e=[],r.O=(a,c,d,f)=>{if(!c){var b=1/0;for(i=0;i=f)&&Object.keys(r.O).every((e=>r.O[e](c[o])))?c.splice(o--,1):(t=!1,f0&&e[i-1][2]>f;i--)e[i]=e[i-1];e[i]=[c,d,f]},r.n=e=>{var a=e&&e.__esModule?()=>e.default:()=>e;return r.d(a,{a:a}),a},c=Object.getPrototypeOf?e=>Object.getPrototypeOf(e):e=>e.__proto__,r.t=function(e,d){if(1&d&&(e=this(e)),8&d)return e;if("object"==typeof e&&e){if(4&d&&e.__esModule)return e;if(16&d&&"function"==typeof e.then)return e}var f=Object.create(null);r.r(f);var b={};a=a||[null,c({}),c([]),c(c)];for(var t=2&d&&e;"object"==typeof t&&!~a.indexOf(t);t=c(t))Object.getOwnPropertyNames(t).forEach((a=>b[a]=()=>e[a]));return b.default=()=>e,r.d(f,b),f},r.d=(e,a)=>{for(var c in a)r.o(a,c)&&!r.o(e,c)&&Object.defineProperty(e,c,{enumerable:!0,get:a[c]})},r.f={},r.e=e=>Promise.all(Object.keys(r.f).reduce(((a,c)=>(r.f[c](e,a),a)),[])),r.u=e=>"assets/js/"+({46:"ca705c4a",53:"935f2afb",150:"32de2db0",292:"1937bb63",380:"22251b09",493:"ed7f1a16",874:"8276c122",948:"8717b14a",1757:"cd95f078",1914:"d9f32620",2031:"8c4308b7",2049:"2bc4934e",2052:"69878e35",2081:"73e4d764",2119:"c612d4a7",2213:"39680a00",2249:"f26fc996",2267:"59362658",2362:"e273c56f",2475:"1375824b",2535:"814f3328",2608:"d52baca9",2774:"6d6ba527",3021:"c36b7e6b",3085:"1f391b9e",3089:"a6aa9e1f",3514:"73664a40",3608:"9e4087bc",3662:"b76a362f",3689:"c441f7d5",3842:"4317fbf7",4013:"01a85c17",4024:"6fb1fe71",4081:"719b1851",4103:"684aec4d",4173:"3b327884",4195:"c4f5d8e4",4227:"d5decc06",4555:"e0d5b996",4642:"b741a796",5178:"d07f8614",5242:"de1ef56c",5288:"4c9dd493",5307:"f1e6a692",5620:"e9025b0e",5680:"c2f4afbb",6004:"a729c412",6047:"5a59ea68",6103:"ccc49370",6189:"91db1580",6677:"2f60f69a",7075:"be00f8f0",7170:"cb227d72",7275:"b4deb335",7352:"41244d51",7414:"393be207",7649:"da286ece",7890:"51f4fcc3",7918:"17896441",7972:"c2d7cd96",8059:"7a337337",8361:"3cc55dcd",8400:"21821687",8558:"1fb8531c",8610:"6875c492",8636:"f4f34a3a",8671:"325c7275",8780:"8facacb8",8793:"403f595d",9003:"925b3f96",9278:"cdace248",9402:"64fc4b83",9510:"0ee94099",9514:"1be78505",9554:"ac7d2b3d",9642:"7661071f",9721:"3b13db8a",9817:"14eb3368",9959:"f25b6166"}[e]||e)+"."+{46:"42cbb196",53:"cf15af51",150:"ef9e1596",292:"c01fcc43",380:"d8a93ec4",493:"6470d80e",874:"b8e4706e",948:"914d35ec",1098:"06d2c692",1757:"88e6a440",1914:"8aa602a6",2031:"98e99271",2049:"63c5560d",2052:"f01ce896",2081:"eda107b5",2119:"d79501aa",2213:"7d42604e",2249:"ded78440",2267:"4445c936",2362:"0e41ec1f",2475:"0eff4db0",2529:"36c3bab3",2535:"743a3596",2608:"93fe4de6",2774:"40d4b3b5",3021:"dfc94606",3085:"b260a6c5",3089:"a59b6240",3514:"a2ef6c76",3608:"fd66296e",3662:"fbd93ba2",3689:"fb308300",3842:"06fa1c2c",4013:"298b1a20",4024:"1edfdccc",4081:"5489bd4c",4103:"88251110",4173:"0732cef7",4195:"814258f0",4227:"fb746336",4555:"d9db6088",4642:"e68df027",4972:"71e74212",5178:"7b874a4b",5242:"3c4d2b0b",5288:"791558f2",5307:"1a0ccef4",5620:"57b28c92",5680:"0277c7b0",6004:"06e106c5",6047:"4c43887d",6103:"a04a9b88",6189:"7a4c742e",6316:"e253b8dd",6677:"ab253a10",7075:"3f5f6938",7170:"4bffee7f",7275:"4d0a6c31",7352:"c4bd9d9b",7414:"2b6bec03",7649:"af8db11e",7724:"1ce4c8a5",7890:"b298b17c",7918:"c879fc52",7972:"321d5c84",8059:"fdddc084",8361:"49174da4",8400:"5cce832b",8558:"6ee91e0a",8610:"7dbfa267",8636:"ec4f7a24",8671:"ca7f10df",8780:"af109432",8793:"fbcc0f20",9003:"39c96a76",9278:"98c4f9dd",9402:"8763c510",9487:"1902e0d9",9510:"d97cafc7",9514:"8f5a31ba",9554:"72fe38ed",9620:"b536c143",9642:"4eb2b4ef",9721:"9606fcc4",9817:"7e910f19",9959:"c6d206b1"}[e]+".js",r.miniCssF=e=>{},r.g=function(){if("object"==typeof globalThis)return globalThis;try{return this||new Function("return this")()}catch(e){if("object"==typeof window)return window}}(),r.o=(e,a)=>Object.prototype.hasOwnProperty.call(e,a),d={},f="docusaurus:",r.l=(e,a,c,b)=>{if(d[e])d[e].push(a);else{var t,o;if(void 0!==c)for(var n=document.getElementsByTagName("script"),i=0;i{t.onerror=t.onload=null,clearTimeout(s);var f=d[e];if(delete d[e],t.parentNode&&t.parentNode.removeChild(t),f&&f.forEach((e=>e(c))),a)return a(c)},s=setTimeout(l.bind(null,void 0,{type:"timeout",target:t}),12e4);t.onerror=l.bind(null,t.onerror),t.onload=l.bind(null,t.onload),o&&document.head.appendChild(t)}},r.r=e=>{"undefined"!=typeof Symbol&&Symbol.toStringTag&&Object.defineProperty(e,Symbol.toStringTag,{value:"Module"}),Object.defineProperty(e,"__esModule",{value:!0})},r.p="/slim/",r.gca=function(e){return e={17896441:"7918",21821687:"8400",59362658:"2267",ca705c4a:"46","935f2afb":"53","32de2db0":"150","1937bb63":"292","22251b09":"380",ed7f1a16:"493","8276c122":"874","8717b14a":"948",cd95f078:"1757",d9f32620:"1914","8c4308b7":"2031","2bc4934e":"2049","69878e35":"2052","73e4d764":"2081",c612d4a7:"2119","39680a00":"2213",f26fc996:"2249",e273c56f:"2362","1375824b":"2475","814f3328":"2535",d52baca9:"2608","6d6ba527":"2774",c36b7e6b:"3021","1f391b9e":"3085",a6aa9e1f:"3089","73664a40":"3514","9e4087bc":"3608",b76a362f:"3662",c441f7d5:"3689","4317fbf7":"3842","01a85c17":"4013","6fb1fe71":"4024","719b1851":"4081","684aec4d":"4103","3b327884":"4173",c4f5d8e4:"4195",d5decc06:"4227",e0d5b996:"4555",b741a796:"4642",d07f8614:"5178",de1ef56c:"5242","4c9dd493":"5288",f1e6a692:"5307",e9025b0e:"5620",c2f4afbb:"5680",a729c412:"6004","5a59ea68":"6047",ccc49370:"6103","91db1580":"6189","2f60f69a":"6677",be00f8f0:"7075",cb227d72:"7170",b4deb335:"7275","41244d51":"7352","393be207":"7414",da286ece:"7649","51f4fcc3":"7890",c2d7cd96:"7972","7a337337":"8059","3cc55dcd":"8361","1fb8531c":"8558","6875c492":"8610",f4f34a3a:"8636","325c7275":"8671","8facacb8":"8780","403f595d":"8793","925b3f96":"9003",cdace248:"9278","64fc4b83":"9402","0ee94099":"9510","1be78505":"9514",ac7d2b3d:"9554","7661071f":"9642","3b13db8a":"9721","14eb3368":"9817",f25b6166:"9959"}[e]||e,r.p+r.u(e)},(()=>{var e={1303:0,532:0};r.f.j=(a,c)=>{var d=r.o(e,a)?e[a]:void 0;if(0!==d)if(d)c.push(d[2]);else if(/^(1303|532)$/.test(a))e[a]=0;else{var f=new Promise(((c,f)=>d=e[a]=[c,f]));c.push(d[2]=f);var b=r.p+r.u(a),t=new Error;r.l(b,(c=>{if(r.o(e,a)&&(0!==(d=e[a])&&(e[a]=void 0),d)){var f=c&&("load"===c.type?"missing":c.type),b=c&&c.target&&c.target.src;t.message="Loading chunk "+a+" failed.\n("+f+": "+b+")",t.name="ChunkLoadError",t.type=f,t.request=b,d[1](t)}}),"chunk-"+a,a)}},r.O.j=a=>0===e[a];var a=(a,c)=>{var d,f,b=c[0],t=c[1],o=c[2],n=0;if(b.some((a=>0!==e[a]))){for(d in t)r.o(t,d)&&(r.m[d]=t[d]);if(o)var i=o(r)}for(a&&a(c);n Archive | SLIM - +

Archive

Archive

2019

2021

Resources
Community
More
Copyright © 2024 California Institute of Technology ("Caltech"). U.S. Government sponsorship acknowledged. Contents licensed under Apache License Version 2.0.
- + \ No newline at end of file diff --git a/blog/first-blog-post/index.html b/blog/first-blog-post/index.html index e0b6bfa2d..371091703 100644 --- a/blog/first-blog-post/index.html +++ b/blog/first-blog-post/index.html @@ -5,13 +5,13 @@ First Blog Post | SLIM - +

First Blog Post

· One min read
Gao Wei

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet

Resources
Community
More
Copyright © 2024 California Institute of Technology ("Caltech"). U.S. Government sponsorship acknowledged. Contents licensed under Apache License Version 2.0.
- + \ No newline at end of file diff --git a/blog/index.html b/blog/index.html index 8bebbd802..db489e427 100644 --- a/blog/index.html +++ b/blog/index.html @@ -5,13 +5,13 @@ Blog | SLIM - +

· One min read
Sébastien Lorber
Yangshun Tay

Docusaurus blogging features are powered by the blog plugin.

Simply add Markdown files (or folders) to the blog directory.

Regular blog authors can be added to authors.yml.

The blog post date can be extracted from filenames, such as:

  • 2019-05-30-welcome.md
  • 2019-05-30-welcome/index.md

A blog post folder can be convenient to co-locate blog post images:

Docusaurus Plushie

The blog supports tags as well!

And if you don't want a blog: just delete this directory, and use blog: false in your Docusaurus config.

· One min read
Gao Wei

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet

Resources
Community
More
Copyright © 2024 California Institute of Technology ("Caltech"). U.S. Government sponsorship acknowledged. Contents licensed under Apache License Version 2.0.
- + \ No newline at end of file diff --git a/blog/long-blog-post/index.html b/blog/long-blog-post/index.html index 47a6d80de..50c769fa9 100644 --- a/blog/long-blog-post/index.html +++ b/blog/long-blog-post/index.html @@ -5,13 +5,13 @@ Long Blog Post | SLIM - +

Long Blog Post

· 3 min read
Endilie Yacop Sucipto

This is the summary of a very long blog post,

Use a <!-- truncate --> comment to limit blog post size in the list view.

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet

Resources
Community
More
Copyright © 2024 California Institute of Technology ("Caltech"). U.S. Government sponsorship acknowledged. Contents licensed under Apache License Version 2.0.
- + \ No newline at end of file diff --git a/blog/mdx-blog-post/index.html b/blog/mdx-blog-post/index.html index bc0c09bd2..2413fd764 100644 --- a/blog/mdx-blog-post/index.html +++ b/blog/mdx-blog-post/index.html @@ -5,13 +5,13 @@ MDX Blog Post | SLIM - +
Resources
Community
More
Copyright © 2024 California Institute of Technology ("Caltech"). U.S. Government sponsorship acknowledged. Contents licensed under Apache License Version 2.0.
- + \ No newline at end of file diff --git a/blog/tags/docusaurus/index.html b/blog/tags/docusaurus/index.html index 500bfce27..0c2437288 100644 --- a/blog/tags/docusaurus/index.html +++ b/blog/tags/docusaurus/index.html @@ -5,13 +5,13 @@ 4 posts tagged with "docusaurus" | SLIM - +

4 posts tagged with "docusaurus"

View All Tags

· One min read
Sébastien Lorber
Yangshun Tay

Docusaurus blogging features are powered by the blog plugin.

Simply add Markdown files (or folders) to the blog directory.

Regular blog authors can be added to authors.yml.

The blog post date can be extracted from filenames, such as:

  • 2019-05-30-welcome.md
  • 2019-05-30-welcome/index.md

A blog post folder can be convenient to co-locate blog post images:

Docusaurus Plushie

The blog supports tags as well!

And if you don't want a blog: just delete this directory, and use blog: false in your Docusaurus config.

· One min read
Gao Wei

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet

Resources
Community
More
Copyright © 2024 California Institute of Technology ("Caltech"). U.S. Government sponsorship acknowledged. Contents licensed under Apache License Version 2.0.
- + \ No newline at end of file diff --git a/blog/tags/facebook/index.html b/blog/tags/facebook/index.html index f6997e9ae..32f2f9963 100644 --- a/blog/tags/facebook/index.html +++ b/blog/tags/facebook/index.html @@ -5,13 +5,13 @@ One post tagged with "facebook" | SLIM - +

One post tagged with "facebook"

View All Tags

· One min read
Sébastien Lorber
Yangshun Tay

Docusaurus blogging features are powered by the blog plugin.

Simply add Markdown files (or folders) to the blog directory.

Regular blog authors can be added to authors.yml.

The blog post date can be extracted from filenames, such as:

  • 2019-05-30-welcome.md
  • 2019-05-30-welcome/index.md

A blog post folder can be convenient to co-locate blog post images:

Docusaurus Plushie

The blog supports tags as well!

And if you don't want a blog: just delete this directory, and use blog: false in your Docusaurus config.

Resources
Community
More
Copyright © 2024 California Institute of Technology ("Caltech"). U.S. Government sponsorship acknowledged. Contents licensed under Apache License Version 2.0.
- + \ No newline at end of file diff --git a/blog/tags/hello/index.html b/blog/tags/hello/index.html index 7308639c5..d44cf6955 100644 --- a/blog/tags/hello/index.html +++ b/blog/tags/hello/index.html @@ -5,13 +5,13 @@ 2 posts tagged with "hello" | SLIM - +

2 posts tagged with "hello"

View All Tags

· One min read
Sébastien Lorber
Yangshun Tay

Docusaurus blogging features are powered by the blog plugin.

Simply add Markdown files (or folders) to the blog directory.

Regular blog authors can be added to authors.yml.

The blog post date can be extracted from filenames, such as:

  • 2019-05-30-welcome.md
  • 2019-05-30-welcome/index.md

A blog post folder can be convenient to co-locate blog post images:

Docusaurus Plushie

The blog supports tags as well!

And if you don't want a blog: just delete this directory, and use blog: false in your Docusaurus config.

Resources
Community
More
Copyright © 2024 California Institute of Technology ("Caltech"). U.S. Government sponsorship acknowledged. Contents licensed under Apache License Version 2.0.
- + \ No newline at end of file diff --git a/blog/tags/hola/index.html b/blog/tags/hola/index.html index 77488c8de..678104c69 100644 --- a/blog/tags/hola/index.html +++ b/blog/tags/hola/index.html @@ -5,13 +5,13 @@ One post tagged with "hola" | SLIM - +

One post tagged with "hola"

View All Tags

· One min read
Gao Wei

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet

Resources
Community
More
Copyright © 2024 California Institute of Technology ("Caltech"). U.S. Government sponsorship acknowledged. Contents licensed under Apache License Version 2.0.
- + \ No newline at end of file diff --git a/blog/tags/index.html b/blog/tags/index.html index 5284c5ad9..a47acc105 100644 --- a/blog/tags/index.html +++ b/blog/tags/index.html @@ -5,13 +5,13 @@ Tags | SLIM - +

Tags

Resources
Community
More
Copyright © 2024 California Institute of Technology ("Caltech"). U.S. Government sponsorship acknowledged. Contents licensed under Apache License Version 2.0.
- + \ No newline at end of file diff --git a/blog/welcome/index.html b/blog/welcome/index.html index 48dabe84d..75b891c05 100644 --- a/blog/welcome/index.html +++ b/blog/welcome/index.html @@ -5,13 +5,13 @@ Welcome | SLIM - +

Welcome

· One min read
Sébastien Lorber
Yangshun Tay

Docusaurus blogging features are powered by the blog plugin.

Simply add Markdown files (or folders) to the blog directory.

Regular blog authors can be added to authors.yml.

The blog post date can be extracted from filenames, such as:

  • 2019-05-30-welcome.md
  • 2019-05-30-welcome/index.md

A blog post folder can be convenient to co-locate blog post images:

Docusaurus Plushie

The blog supports tags as well!

And if you don't want a blog: just delete this directory, and use blog: false in your Docusaurus config.

Resources
Community
More
Copyright © 2024 California Institute of Technology ("Caltech"). U.S. Government sponsorship acknowledged. Contents licensed under Apache License Version 2.0.
- + \ No newline at end of file diff --git a/docs/about/CODE_OF_CONDUCT/index.html b/docs/about/CODE_OF_CONDUCT/index.html index 41c3d4901..c613cd79a 100644 --- a/docs/about/CODE_OF_CONDUCT/index.html +++ b/docs/about/CODE_OF_CONDUCT/index.html @@ -5,7 +5,7 @@ Code of Conduct | SLIM - + @@ -59,7 +59,7 @@ Mozilla's code of conduct enforcement ladder.

For answers to common questions about this code of conduct, see the FAQ at https://www.contributor-covenant.org/faq. Translations are available at https://www.contributor-covenant.org/translations.

Resources
Community
More
Copyright © 2024 California Institute of Technology ("Caltech"). U.S. Government sponsorship acknowledged. Contents licensed under Apache License Version 2.0.
- + \ No newline at end of file diff --git a/docs/about/GOVERNANCE/index.html b/docs/about/GOVERNANCE/index.html index fed552175..921318c97 100644 --- a/docs/about/GOVERNANCE/index.html +++ b/docs/about/GOVERNANCE/index.html @@ -5,13 +5,13 @@ SLIM Project Governance | SLIM - +

SLIM 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 SLIM 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 governing committees (e.g. technical steering, project steering) are set up to ensure the project's direction is in-line with requirements / goals while supporting flexibility for future growth and membership. Technical decision making will primarily be made through a "consensus-seeking" approach within the respective governing committees.

Roles​

RoleRestricted ToDescriptionRead/ClonePropose Pull RequestComment in Tickets / DiscussionsTriageReviewCommitTechnical DecisionsProject Decisions
UserNoneAnyone downloading, deploying, or operating the software to meet a specific objective.✅✅✅❌❌❌❌❌
ContributorNoneAnyone providing input to the project, including: code, issues, documentation, graphics, etc.✅✅✅❌❌❌❌❌
TriagerContributorSubset of contributors demonstrating a strong familiarity with the project.✅✅✅✅❌❌❌❌
CollaboratorContributorSubset of contributors granted write access to one or more of the project repositories upon selection by TSC✅✅✅✅✅✅❌❌
Technical Steering Committee MemberCollaboratorA subset of collaborators having technical decision making authority and admin privileges✅✅✅✅✅✅✅❌
Project Steering Committee MemberStakeholdersSponsor organization representatives (i.e. those providing funding to the project) and key stakeholders with authority to guide project based on requirements, budget, schedule, etc.✅✅✅✅✅✅✅✅
Product ManagerStakeholdersOverall manager of project with final authority over all key decisions when consensus cannot be reached✅✅✅✅✅✅✅✅

User​

Anyone who has downloaded, deployed, or operated SLIM to meet a specific objective. This project was primarily designed for developing, iterating, and disseminating software process improvements, 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 or submitting an Issue.

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

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 https://github.com/riverma/

List of current collaborators

Technical Steering Committee Member​

A subset of the collaborators forms the Technical Steering Committee (TSC). The TSC has authority over the following aspects of this project:

  • Technical direction and guidance
  • Committee governance and process
  • Contribution policy
  • Conduct guidelines
  • Maintaining the list of collaborators

TSC Committee Members​

Emeriti

TSC Emeriti​

#### Scope

The TSC is primarily responsible for the following project repositories:

However, the TSC also has the responsibility to interface with and monitor third-party dependencies of the project for key changes impacting SLIM. These third-party dependencies include:

  • N/A

Decision Making Process​

Any community member can create an issue or comment asking the TSC to review something. Prior to implementing a substantial contribution, the design of that contribution should be reviewed by at least one member of the TSC. If consensus-seeking fails during the review of a pull request or in design discussions, the issue will be addressed by the TSC to make a determination on direction. TSC members will meet regularly and will keep track of decisions made when consensus was not met.

The TSC can nominate new members at any time. Candidates for membership tend to be collaborators who have shown great dedication to the project and/or experts in a particular domain or project component. TSC members are expected to be active contributors or members who have made significant contributions within the past 12 months.

Project Management Committee (PMC) Member​

The Project Management Committee (PMC) is made up of sponsor organization representatives (i.e. those providing funding to the project) and key stakeholders who rely or plan to rely on the project to meet a critical need. The PMC has the following responsibilities:

  • Maintaining the overall project roadmap
  • Determining project requirements and commitments to sponsors and stakeholders
  • Assessing available resources and allocating them across the project
  • Monitoring and reporting on progress against the roadmap
  • On-boarding new sponsors and stakeholders
  • Overall project governance (including this policy)
  • Addressing any legal considerations

PMC Committee Members​

Emeriti

PMC Emeriti​

Scope​

The PMC has management authority over the same project repositories over which the TSC has technical authority over.

Decision Making Process​

The PMC will consist of a product manager and additional representative from sponsors and key stakeholders. The PMC or sponsoring organizations can nominate new members at any time. Care should be taken not to include too many members from a single stakeholder project or organization.

Regular stakeholder meetings are held to discuss current project status and propose changes to the project roadmap. If stakeholder representatives and sponsors concur with these proposals during the meeting, they will be immediately adopted. A member of the PMC will ensure the changes have been captured and recorded. Regular stakeholder meetings will be open to the entire community, but only members of the PMC have decision making authority.

Additional meetings may be held if consensus is not met or to discuss significant changes to the roadmap due to changes in stakeholder priorities or available resources. Any decision made outside of stakeholder meetings must still be approved by all sponsors and stakeholders. If full consensus cannot be made, the product manager has the final authority to determine project direction. Any non-concurrences from stakeholders or sponsors will be noted.

Product Manager​

Overall manager of the project with final authority over all key decisions when consensus cannot be reached within the TSC or PSC. The product manager is often chosen at the onset of project initiation and can be reassigned by the PMC (with institutional approval, if applicable).

Acknowledgements

Much of this governance model was adapted from the other notable open source projects including node.js, OpenSSL, PostgresQL, and OpenMCT. We would like to thank those projects for setting the foundation upon which this model was built.

Resources
Community
More
Copyright © 2024 California Institute of Technology ("Caltech"). U.S. Government sponsorship acknowledged. Contents licensed under Apache License Version 2.0.
- + \ No newline at end of file diff --git a/docs/about/index.html b/docs/about/index.html index d6f7bf501..45134ccb5 100644 --- a/docs/about/index.html +++ b/docs/about/index.html @@ -5,14 +5,14 @@ About | SLIM - +

About

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)

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.

Our Focus​

There are three key areas within the software development lifecycle improvement space that SLIM focuses on providing best practice guidance for:

SLIM-scope

Our Process​

1. Ask Our Community​

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. That being said, any external contributors are free to propose best practice guides to our project at any time in the form of a contribution. See our /slim/docs/contribute/submit-best-practice for more details.

You can see our current prioritized list of community-ranked best practice development ideas in our planning board.

2. Develop Standards & Best Practices​

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 SLIM community member projects. This way, we are actually able to scale out our best practice dissemination widely to many projects at once. For best practices that are not patchable to repositories, we ask our contributors to develop automation that can be run as a script or set of commands - and deploy these to SLIM community members through issue-tickets.

SLIM-dev-process

More information on our development process for best practice guides can be found in our Contributing Guide.

3. Publish Best Practices​

As mentioned above, we operate under a "standards-as-code" philosophy, which means that newly developed standards and best practices are directly infused into member projects through pull requests or issue tickets. This hands-on approach ensures that improvements are easily infusable into the SLIM community member repositories.

To see the current adoption status and how these practices are being integrated into various SLIM community member projects, check out our leaderboard pages:

Our Community Members​

What does it mean to be a community member of SLIM? The following ideas apply to community member projects:

  • Has a representative (a point-of-contact) who interfaces with the SLIM effort
  • Openness and willingness to infuse SLIM best practices
  • Prioritizes contributing back to the SLIM project with best practice guides

The following list of public projects are currently SLIM community members:

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) as well as contribute and help shape our future work. We're excited to welcome new contributors and users.

Some ways you can get involved with SLIM:

Use Our Guides​

The fastest way to start using SLIM process improvement solutions is to take a look at our best practice guides, specifically our starter kits. Starter kits provide plug-and-play solutions to process improvement needs. To complement our starter kits, take a look at use cases to understand the context of the starter kit solutions, trade studies to understand tool / solution trade-offs, and reference architectures to understand how tool / solutions interact in an actual working environment.

We recommend creating pull-requests using our starter kits against your own repositories. Reach out to our contributor communication channels for questions if you're unsure how to create pull requests. An excellent tool to automate the infusion of starter kits in your repositories (especially if you have many) is to use a tool like multi-gitter if you're using Git to create pull-requests.

Finally, if you use any of our guides - please consider adding the following badge to your README.md: SLIM

Contribute to Our Guides​

We'd be delighted to see your contribution! Please see our Contributing Guide on details for how to contribute. We accept many non-code contributions as well, so feel free to think creatively.

Join Our Community of Projects​

Interested in becoming a part of the SLIM community? We welcome new project members who are keen on improving software lifecycle processes within their projects. Joining is simple:

  1. Publicly: Start a Discussion: Head over to our discussion forum and file a new thread expressing your interest in joining SLIM. This is a great way to introduce your project and outline how you think SLIM could benefit you.

  2. Privately: Contact Us: You can directly contact @riverma or the @slim-steering group on GitHub to express your desire to join. We'll have a chat, and try to identify which repositories in your project make sense for best practice infusion as well as identify a point-of-contact.

Becoming a part of SLIM means not just receiving updates regarding our best practices and standards, but also receiving pull-requests and issue tickets that help streamline SLIM best practices more easily to your project (at no cost!).

Spread the Word​

The more people & projects using, contributing, and maintaining SLIM, the more robust and long-term this effort will last.

You can help by:

Socializing on GitHub​

⭐ Star our Repo

👀 Watch our Repo

😀 Discuss our Repo

Website​

Share our website (https://nasa-ammos.github.io/slim) with your friends and colleagues

Resources
Community
More
Copyright © 2024 California Institute of Technology ("Caltech"). U.S. Government sponsorship acknowledged. Contents licensed under Apache License Version 2.0.
- + \ No newline at end of file diff --git a/docs/category/application-starter-kits/index.html b/docs/category/application-starter-kits/index.html index 1be693f67..a1d2f78dd 100644 --- a/docs/category/application-starter-kits/index.html +++ b/docs/category/application-starter-kits/index.html @@ -5,13 +5,13 @@ Application Starter Kits | SLIM - +

Application Starter Kits

Check out our below list of guides on language-specific application starter kits / repository templates.

Resources
Community
More
Copyright © 2024 California Institute of Technology ("Caltech"). U.S. Government sponsorship acknowledged. Contents licensed under Apache License Version 2.0.
- + \ No newline at end of file diff --git a/docs/category/contributions/index.html b/docs/category/contributions/index.html index 14df51e83..56ef851b8 100644 --- a/docs/category/contributions/index.html +++ b/docs/category/contributions/index.html @@ -5,13 +5,13 @@ Contributions | SLIM - +

Contributions

Contributing Best Practices.

Resources
Community
More
Copyright © 2024 California Institute of Technology ("Caltech"). U.S. Government sponsorship acknowledged. Contents licensed under Apache License Version 2.0.
- + \ No newline at end of file diff --git a/docs/category/documentation/index.html b/docs/category/documentation/index.html index b564fd317..636d1452c 100644 --- a/docs/category/documentation/index.html +++ b/docs/category/documentation/index.html @@ -5,13 +5,13 @@ Documentation | SLIM - +

Documentation

Check out our below list of guides and sub-sections related to documentation best practices.

Resources
Community
More
Copyright © 2024 California Institute of Technology ("Caltech"). U.S. Government sponsorship acknowledged. Contents licensed under Apache License Version 2.0.
- + \ No newline at end of file diff --git a/docs/category/governance/index.html b/docs/category/governance/index.html index 87d545c15..4a5df1db2 100644 --- a/docs/category/governance/index.html +++ b/docs/category/governance/index.html @@ -5,13 +5,13 @@ Governance | SLIM - +

Governance

Check out our below list of guides and sub-sections related to governance best practices.

Resources
Community
More
Copyright © 2024 California Institute of Technology ("Caltech"). U.S. Government sponsorship acknowledged. Contents licensed under Apache License Version 2.0.
- + \ No newline at end of file diff --git a/docs/category/security/index.html b/docs/category/security/index.html index 924343305..af093a3e2 100644 --- a/docs/category/security/index.html +++ b/docs/category/security/index.html @@ -5,13 +5,13 @@ Security | SLIM - +
-

Security

Security Best Practices.

Resources
Community
More
Copyright © 2024 California Institute of Technology ("Caltech"). U.S. Government sponsorship acknowledged. Contents licensed under Apache License Version 2.0.
- +

Security

Security Best Practices.

Resources
Community
More
Copyright © 2024 California Institute of Technology ("Caltech"). U.S. Government sponsorship acknowledged. Contents licensed under Apache License Version 2.0.
+ \ No newline at end of file diff --git a/docs/category/software-lifecycle/index.html b/docs/category/software-lifecycle/index.html index b3a79b721..98d612cb2 100644 --- a/docs/category/software-lifecycle/index.html +++ b/docs/category/software-lifecycle/index.html @@ -5,13 +5,13 @@ Software Lifecycle | SLIM - +

Software Lifecycle

Check out our below list of guides and sub-sections related to software lifecycle best practices.

Resources
Community
More
Copyright © 2024 California Institute of Technology ("Caltech"). U.S. Government sponsorship acknowledged. Contents licensed under Apache License Version 2.0.
- + \ No newline at end of file diff --git a/docs/contribute/contributing/development-process/index.html b/docs/contribute/contributing/development-process/index.html index 7dc01611b..392ac6aaf 100644 --- a/docs/contribute/contributing/development-process/index.html +++ b/docs/contribute/contributing/development-process/index.html @@ -5,13 +5,13 @@ Our Development Process | SLIM - +

Our Development Process

Our project integrates contributions from many people, and so we'd like to outline a process you can use to visualize how your contributions may be integrated if you provide something.

Fork our Repository​

Forking our repository, as opposed to directly committing to a branch is the preferred way to propose changes.

See this GitHub guide on forking for information specific to GitHub.com

Find or File an Issue​

Make sure people are aware you're working on a patch! Check out our issue tracking system and find an open issue you'd like to work against, or alternatively file a new issue and mention you're working on a patch.

Choose the Right Branch to Fork​

Our project typically has the following branches available, make sure to fork either the default branch or a branch someone else already tagged with a particular issue ticket you're working with.

  • main - default branch, and contains mature SLIM deliverables and should be the typical branch you fork
  • gh-pages - live rendering of SLIM website, auto-generated by changes committed to main branch via a GitHub Action

Make your Modifications​

Within your local development environment, this is the stage at which you'll propose your changes, and commit those changes back to version control. See the README.md or development guide for more specifics on what you'll need as prerequisites to setup your local development environment.

Commit Messages​

Commit messages to version control should reference a ticket in their title / summary line:

Issue #248 - Show an example commit message title

This makes sure that tickets are updated on GitHub with references to commits that are related to them.

Commit should always be atomic. Keep solutions isolated whenever possible. Filler commits such as "clean up white space" or "fix typo" should be merged together before making a pull request, and significant sub-feature branches should be rebased to preserve commit history. Please ensure your commit history is clean and meaningful!

Additionally, remember to "Sign-Off" on your commits to align with our Developer Certificate of Origin (DCO) policy.

Submit a Pull Request​

Pull requests are the core way our project will receive your patch contributions. Navigate to your branch on your own fork within the version control system, and submit a pull request or submit the patch text to our project.

Please make sure to provide a meaningful text description to your pull requests, whenever submitted. Our pull-request template will be auto-generated for you when you create your pull-request. See the template here.

Working on your first Pull Request? See guide: How to Contribute to an Open Source Project on GitHub

Reviewing your Pull Request​

Reviewing pull-requests, or any kinds of proposed patch changes, is an art. That being said, we follow the following best practices:

  • Intent - is the purpose of your pull-request clearly stated?
  • Solution - is your pull-request doing what you want it to?
  • Correctness - is your pull-request doing what you want it to correctly?
  • Small Patches - is your patch of a level of complexity and brevity that it can actually be reviewed by a human being? Or is does it involve too much content for one pull request?
  • Coding best practices - are you following best practices in the coding / contribution language being used?
  • Readability - is your patch readable, and ultimately maintainable, by others?
  • Reproducibility - is your patch reproducible by others?
  • Tests - do you have or have conducted meaningful tests?
Resources
Community
More
Copyright © 2024 California Institute of Technology ("Caltech"). U.S. Government sponsorship acknowledged. Contents licensed under Apache License Version 2.0.
- + \ No newline at end of file diff --git a/docs/contribute/contributing/index.html b/docs/contribute/contributing/index.html index 9896006c8..21027b1a9 100644 --- a/docs/contribute/contributing/index.html +++ b/docs/contribute/contributing/index.html @@ -5,13 +5,13 @@ Contributing 101 | SLIM - +

Contributing 101

Thanks for taking the time to consider contributing! We very much appreciate your time and effort. This document outlines the many ways you can contribute to our project, and provides detailed guidance on best practices. We look forward to your help!

Resources
Community
More
Copyright © 2024 California Institute of Technology ("Caltech"). U.S. Government sponsorship acknowledged. Contents licensed under Apache License Version 2.0.
- + \ No newline at end of file diff --git a/docs/contribute/contributing/introduction/index.html b/docs/contribute/contributing/introduction/index.html index eb7d3f496..7730d0474 100644 --- a/docs/contribute/contributing/introduction/index.html +++ b/docs/contribute/contributing/introduction/index.html @@ -5,13 +5,13 @@ Introduction | SLIM - +

Introduction

SLIM is a joint, community-based effort at collective software process improvements. Therefore, we need your help! Here's the basics on contributing:

  • Anyone can contribute!
  • You can contribute at any time
  • You can contribute in any way (code, documentation, discussion topics, issue ticket discussions, etc.)

We plan out our work into fiscal quarters (i.e. Oct - Dec as Q1, Jan - Mar as Q2, etc.). This helps our stakeholders (the folks using our process improvements) plan to incorporate process improvements better into their schedules. See our Planning Board for our most up-to-date plan. Generally speaking, we try to get together with our stakeholders and our community contributors at the start of every fiscal quarter to plan out what we should work on. That being said, since we're an open source project, we also accept and encourage ad-hoc contributions at any time - just note it may take some time to review / decide whether to incorporate.

Resources
Community
More
Copyright © 2024 California Institute of Technology ("Caltech"). U.S. Government sponsorship acknowledged. Contents licensed under Apache License Version 2.0.
- + \ No newline at end of file diff --git a/docs/contribute/contributing/know-before-contribute/index.html b/docs/contribute/contributing/know-before-contribute/index.html index 7e6f99b97..f13ebe6fd 100644 --- a/docs/contribute/contributing/know-before-contribute/index.html +++ b/docs/contribute/contributing/know-before-contribute/index.html @@ -5,13 +5,13 @@ Know Before you Contribute | SLIM - +

Know Before you Contribute

Before you begin contributing to our project, it'll be a good idea to ensure you've satisfied the below pre-requisites.

License​

Our project has our licensing terms, including rules governing redistribution, documented in our LICENSE file. Please take a look at that file and ensure you understand the terms. This will impact how we, or others, use your contributions.

Code of Conduct​

Our Code of Conduct helps facilitate a positive interaction environment for everyone involved with the team, and provides guidance on what to do if you experience problematic behavior. Read more in our CODE_OF_CONDUCT.md, and make sure you agree to its terms.

Developer Environment​

For patch contributions, see our Developer Documentation (TBD) for more details on how to set up your local environment, to best contribute to our project.

At a minimum however to submit patches (if using Git), you'll want to ensure you have:

  1. An account on the Version Control System our project uses (i.e. GitHub).
  2. The Version Control System client (i.e. Git) installed on your local machine.
  3. The ability to edit, build, and test our project on your local machine. Again, see our README.md or detailed developer guide for more details

Communication Channels​

Before contributing changes to our project, it's a great idea to be familiar with our communication channels and to socialize your potential contributions to get feedback early. This will help give you context for your contributions, no matter their form.

Our communication channels are:

  • Issue tracking system - a regularly monitored area to report issues with our software or propose changes
  • Discussion board - an permanently archived place to hold conversations related to our project, and to propose as well as show+tell topics to the contributor team. This resource can be searched for old discussions.
Resources
Community
More
Copyright © 2024 California Institute of Technology ("Caltech"). U.S. Government sponsorship acknowledged. Contents licensed under Apache License Version 2.0.
- + \ No newline at end of file diff --git a/docs/contribute/contributing/ways-to-contribute/index.html b/docs/contribute/contributing/ways-to-contribute/index.html index 80d8ecbed..fa29f9cd0 100644 --- a/docs/contribute/contributing/ways-to-contribute/index.html +++ b/docs/contribute/contributing/ways-to-contribute/index.html @@ -5,13 +5,13 @@ Ways to Contribute | SLIM - +

Ways to Contribute

📖 Best Practice Guides​

Please see our Submit a Best Practice Guide for more details.

⚠️ Issue Tickets​

Do you like to talk about new features, changes, requests?

Issue tickets are a very simple way to get involved in our project. It also helps new contributors get an understanding of the project more comprehensively. This is a great place to get started with the project if you're not sure where to start.

See our list of issues at: https://github.com/NASA-AMMOS/slim/issues

Cleaning up Duplicate Issues​

Often we receive duplicate issues that can confuse project members on which issue ticket to hold conversations upon.

Here's how you can help:

  1. Scan the list of open issue tickets for duplicate titles, or internal wording
  2. If you find duplicates, copy / paste the below message on the conversation thread of the issue ticket that has less participants involved
This is a duplicate issue. Please migrate conversations over to [issue-XYZ](hyperlink to issue)

Good First Issues​

Issue tickets can vary in complexity, and issues labeled with good first issue labels are often a great way to get started with the project as a newcomer.

Take a look at our issue tracking system, and filter by good first issue for issues that are low-complexity, and that will help you get familiar with our issue tracking and patch submission process.

Suggesting New Issue Labels​

Labels within our issue tracking system are a great way to quickly sort through tickets. The project may not yet have labels to cover the full variety of issue tickets. Take a look through our list of issues, and if you notice a set of issue tickets that seem similar but are not categorized with an existing label, go ahead submit a request within one of the issues you've looked at with the following text:

I've noticed several other issues that are of the same category as this issue. Shall we make a new label for these types of issues?

Submitting Bug Issues​

Resolving bugs is a priority for our project. We welcome bug reports. However, please make sure to do the following prior to submitting a bug report:

  • Check for duplicates - there may be a bug report already describing your issue, so check the issue tracking system first.

Here's some guidance on submitting a bug issue:

  1. Navigate to our issue tracking system and file a new issue
  2. Select a bug template (if available) for your issue
    1. Fill out the template fields to the best of your ability, including output snippets or screenshots where applicable
  3. Follow the general guidelines below for extra information about your bug
    1. Include a code snippet if you have it showcasing the bug
    2. Provide reproducible steps of how to recreate the bug
    3. If the bug triggers an exception or error message, include the full message or stacktrace
    4. Provide information about your operating system and the version of our project you're using

📀 Media​

Media, such as such as images, videos, sound files, etc., are an excellent way to explain documentation to a wider audience more easily. Include media in your contributions as often as possible.

When including media into our version-control system, it is recommended to use formats such as:

  • Diagrams: Mermaid format
  • Images: JPEG format
  • Videos: H264 MPEG format
  • Sounds: MP3 format

❓ Questions​

Answering questions is an excellent way to learn more about our project, as well as get better known in our project community.

Here are just a few ways you can help answer questions for our project:

When answering questions, keep the following in mind:

  • Be polite and friendly. See our Code of Conduct recommendations as you interact with others in the team.
  • Repeat the specific question you are answering, followed by your suggestion.
  • If suggesting code, repeat the line of code that needs to be altered, followed by your alteration
  • Include any post-steps or checks to verify your answer can be reproduced

🎨 Design​

Design files can help to guide new features and new areas of expansion for our project. We welcome these kinds of contributions.

Here are just a few ways you can help provide design recommendations for our project:

  • Create visual mockups or diagrams to increase usability of our project applications. This can apply to user interfaces, documentation structuring, or even code architecture diagrams.
  • Conduct user research to understand user needs better. Save your findings within spreadsheets that the project team / contributors can review.
  • Create art, such as logos or icons, to support the user experience for the project

Each of the above can be contributed directly to repository code, and you should use our development process to contribute your additions.

🎟️ Meetups​

A great way to contribute towards our project goals is to socialize and encourage people to meet and learn more about each other. Consider ideas like:

  • Propose workshops or meetups regarding some topic within our project
  • Help point project contributors and community members to conferences and publications where they may socialize their unique innovations
  • Schedule in-person or virtual happy-hours to help create a more social atmosphere within the project community

For the above ideas, use our communication channels to propose get-togethers.

Resources
Community
More
Copyright © 2024 California Institute of Technology ("Caltech"). U.S. Government sponsorship acknowledged. Contents licensed under Apache License Version 2.0.
- + \ No newline at end of file diff --git a/docs/contribute/submit-best-practice/index.html b/docs/contribute/submit-best-practice/index.html index 91cd61457..a94229593 100644 --- a/docs/contribute/submit-best-practice/index.html +++ b/docs/contribute/submit-best-practice/index.html @@ -5,13 +5,13 @@ Submit a Best Practice Guide | SLIM - +

Submit a Best Practice Guide

Are you interested in submitting a best practice guide to the SLIM project? You've come to the right place!

Below, we outline the important steps involved - including things like making a ticket, making your contribution, and reviewing / disseminating it.

See Our Process for a high-level overview of how SLIM best practice guides are developed. We use the open source contribution model to ideate, develop, review, and disseminate best practice guides and standards.

1⃣️ Find or Make a Ticket​

The first step in making a contribution to SLIM is to make or select a ticket. This is important so that you don't inadvertently duplicate work that's already done / being done and help communicate your idea with the community. Also, not every best practice solution is appropriate for SLIM; therefore, its always a good idea to talk to the community first before you make a pull request.

To create an issue for the NASA-AMMOS/slim repository:

  1. Go to 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")
    • NOTE: the "New Process Improvement Need" ticket type is intended for documenting needs only, rather than solution ideas.
  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

Follow GitHub best practices: be clear and concise.

2⃣️ Initialize a Draft Pull Request​

To submit your solution to the 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! We also recommend making a fork for the SLIM repository to ensure you can demo your guide easily from your own GitHub account when the guide is ready.

  1. Fork NASA-AMMOS/slim
  2. Clone your fork (git clone https://github.com/YourUsername/slim.git) on your local machine
  3. Use the main branch on your fork - this allows you to host a copy of, and demo the SLIM website at https://<your-username>.github.io/slim
  4. Develop, iterate and commit your solution as it grows (see Step 3 below Develop Your Contribution)
  5. 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 while you iterate so the community knowns you're still working on the contribution.
  6. 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.
  7. Keep your fork synchronized with the original repo using git fetch upstream and git merge upstream/main

3⃣️ Develop Your Contribution​

When developing your contribution to the NASA-AMMOS/slim repository, consider the following sub-sections:

Think about Automation​

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.

Read more about our automation philosophy in Develop Standards & Best Practices.

Adhere to Folder Structure​

To maintain organization and consistency within the repository, create a new folder for your best practice guide. Place this folder within the appropriate sub-folder in the docs/guides directory of the NASA-AMMOS/slim 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

Use our Standard Guide Template​

To maintain uniformity and ease of understanding, contributors are urged to utilize the below template when submitting their best practice guides. This structured format ensures clarity, beginning with a concise title and a one-liner description to capture the essence of the proposal. The Introduction sets the context, Prerequisites identify essential tools or knowledge, and the Step-by-Step Guide offers a methodical walkthrough, enhanced optionally with illustrative images. An FAQ section addresses potential queries, and appropriate credits acknowledge contributors and inspirations. This standard layout not only ensures that each guide retains consistency and comprehensibility, but it also facilitates smoother automation and integration within the SLIM ecosystem.

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
# _Title Goes Here_

<pre align="center">One sentence description of your best practice solution.</pre>

## 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._
![Optional Image for Step 1](imageURL_for_step1)

2. **Step 2**: _Brief description of the step._
![Optional Image for Step 2](imageURL_for_step2)

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 and have your best practice show up in our search page, add a JSON entry to the file data/slim-registry.json within the NASA-AMMOS/slim repository. Fill out the following fields in the example below:

{
  "title": "README.md",
  "uri": "/docs/guides/documentation/readme",
  "category": "documentation",
  "description": "A template that can be used to help developers and users understand your repository's project code concisely and clearly.",
  "tags": [
    "documentation",
    "repository-setup",
    "project-template"
  ],
  "last-updated": "2023-04-27"
}

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.

4⃣️ Get Feedback For Your Contribution​

Once you've created a contribution you're happy about, it's important to gather feedback from the SLIM community. This will help ensure that your contribution aligns with the project's standards and meets the community's needs.

First ensure your pull-request is ready for review:

  1. Ensure your contribution is viewable via https://<your-username>.github.io/slim. You may need to visit your Settings page for the repository and the "Pages" sub-section to configure GitHub Pages hosting. This should be automatically set up for you, but if you need help troubleshooting please visit Docusaurus' Deploying to GitHub Pages.
  2. Within your fork (created in step 2 above) on GitHub.com, click the "Contribute" button. Choose to submit a pull request and fill in details and reference any related issues. Provide a link to the live, demo website guide page on your fork!

It's now important to request feedback from the community. To request feedback, you can do the following:

  • SLIM Reviewers: Tag @slim-community or @slim-committers in your pull request for feedback for faster responses.

  • Slack/E-mail/Discussions: Post a message in the Slack channels, over e-mail, or other mediums. Use the provided template below as a guide for your message. Don't forget to include a link to your pull request or issue for easy reference.

    As part of the Software Lifecycle Improvement & Modernization (SLIM) project, we’ve recently created a pull request (PR) introducing best practices for [INSERT GUIDE NAME HERE]. The goal is to [INSERT BRIEF GOAL HERE].

    **Purpose of this Message:**
    I'm reaching out to you all to get your thoughts on [INSERT GUIDE NAME HERE] for the SLIM project.
    The goal for the guide is to [INSERT BRIEF GOAL STATEMENT HERE].

    **Proposal Details:**
    Pull Request: [INSERT PULL REQUEST URL HERE]
    Live Demo Here: [INSERT URL TO YOUR LIVE DEMO OF THE PROPOSED GUIDE (USUALLY ON YOUR GITHUB FORK)]

    **Your Input Matters:**
    Your comments and insights would be extremely valuable. Please consider adding a comment to the PR about your thoughts!
    Thank you in advance for your support and feedback!

Feedback from the community is crucial for the refinement of your contribution and ensures its successful integration into the SLIM project.

5⃣️ Merge Your Contribution​

The final step in the contribution process involves the review and potential merging of your pull request by SLIM committers and reviewers. This process includes:

  1. Review by SLIM Committers and Reviewers: Your pull request will be thoroughly reviewed by the project's committers and reviewers. They will provide feedback, suggest improvements, or approve the changes.

  2. Iterate as Required: Based on the feedback, you may need to make further adjustments to your contribution. Promptly addressing these suggestions is crucial for the progression of your pull request.

  3. Final Decision: Once your pull request meets all the criteria and standards of the SLIM project, the committers will decide to merge your contribution into the main branch. Alternatively, they might request additional changes if needed.

This process ensures that every contribution is in line with the project's goals, standards, and quality expectations, contributing to the overall excellence and reliability of the SLIM project.

Resources
Community
More
Copyright © 2024 California Institute of Technology ("Caltech"). U.S. Government sponsorship acknowledged. Contents licensed under Apache License Version 2.0.
- + \ No newline at end of file diff --git a/docs/guides/documentation/change-log/index.html b/docs/guides/documentation/change-log/index.html index 3e93eb922..cbc1b866d 100644 --- a/docs/guides/documentation/change-log/index.html +++ b/docs/guides/documentation/change-log/index.html @@ -5,13 +5,13 @@ Change Log | SLIM - +

Change Log

A guide for setting up a log to document software changes in a human-centric format.

Introduction​

Background: A change log is a vital tool for documenting significant changes in software over time in a format accessible to humans. It plays a critical role in conveying the evolution of software, including additions, deprecations, and removals. This guide outlines the best practices for maintaining a CHANGELOG.md file, complementing release pages and enhancing software distribution transparency.

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

Prerequisites​

  • Familiarity with semantic versioning and release cycles.
  • Basic knowledge of Markdown formatting.

Quick Start​

⬇️ Keep a Changelog

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 or Demo 2 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:

Acknowledgements:

  • This guide draws from the "Keep a Changelog" standard and examples from various open source projects.

Feedback and Contributions​

Feedback and contributions are encouraged to refine this guide. See our contribution guidelines.

Resources
Community
More
Copyright © 2024 California Institute of Technology ("Caltech"). U.S. Government sponsorship acknowledged. Contents licensed under Apache License Version 2.0.
- + \ No newline at end of file diff --git a/docs/guides/documentation/documentation-hosts/index.html b/docs/guides/documentation/documentation-hosts/index.html index d684caaf2..c47573453 100644 --- a/docs/guides/documentation/documentation-hosts/index.html +++ b/docs/guides/documentation/documentation-hosts/index.html @@ -5,13 +5,13 @@ Documentation Hosting | SLIM - +

Documentation Hosting

Guidance on selecting and implementing documentation hosting tools.

Introduction​

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.

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.

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

See various use cases and then select corresponding tools for hosting different types of documentation.

📔 Trade Study on Hosting Frameworks

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 document.
  2. Choose Appropriate Tools: Refer to the Trade Study on Hosting Frameworks 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:

Feedback and Contributions​

Feedback and contributions are welcome to enhance this guide. Visit our contribution guidelines.

Resources
Community
More
Copyright © 2024 California Institute of Technology ("Caltech"). U.S. Government sponsorship acknowledged. Contents licensed under Apache License Version 2.0.
- + \ No newline at end of file diff --git a/docs/guides/documentation/documentation-hosts/trade-study-hostingdocs-user/index.html b/docs/guides/documentation/documentation-hosts/trade-study-hostingdocs-user/index.html index 0356f9658..5ce04f5a4 100644 --- a/docs/guides/documentation/documentation-hosts/trade-study-hostingdocs-user/index.html +++ b/docs/guides/documentation/documentation-hosts/trade-study-hostingdocs-user/index.html @@ -5,13 +5,13 @@ Docs Hosting Trade Study | SLIM - +

Docs Hosting Trade Study

Tool NameLicensingRender TimeVCS Stored ContentSelf-HostingManaged HostingAPI ActionsGenerate API DocsWYSIWYG EditingMarkdown SupportEmbedded ContentHierarchial StructureTemplating SupportRolesComment SupportSearchImport From Other FormatsExport Other FormatsAnchor LinksDraft ContentVersion ControlInternationalizationFile UploadsDiagram EditingUsage AnalyticsExtension Support
GitBookFree for OSS / $$$FastYesNoYesYesYesYesYesYesYesYesYesYesYesYesYesYesYesYesYesYesNoYesNo
ConfluenceFree for OSS / $$SlowNoNoYesYesNo (only non-free plugins)YesPartial (for embedded content)YesYesYesYesYesYesYesYesYesYesYesNoYesNo (only non-free plugins)No (non-free plans only)Yes
ReadTheDocsFree (with ads)SlowYesNoYesYesNoNoYesYesYesYesYesNoYesLimitedYesYesNoYes including doc packagesYesNo (embed/links only)Yes (with plugins)YesYes
mdBookFree (Mozilla Public License 2.0)FastYesYesNo (static hosts only)NoNoNoYesNoYesYesNoNoYesNoNoYesNoYesNoNo (embed/links only)Yes (as a preprocessor)No (third-party only)Yes
DocusaurusFree MIT LicenseFastYesYesYes (with static site hosts like Vercel, Netlify)NoYes (with plugins)NoYesYesYesYesNoNoYesNoNo (but can be done with external tools)YesNoNoYesNo (embed/links only)Yes (with plugins)No (third-party only)Yes
DocsifyFree MIT LicenseFastYesYesYes (with static site hosts like GitHub Pages, Netlify)NoNoNo (Markdown-based)YesYesYesNoNoNoYes (with plugins)NoNoYesNoNoNoNo (embed/links only)Partial (with plugins)No (third-party only)Yes
Resources
Community
More
Copyright © 2024 California Institute of Technology ("Caltech"). U.S. Government sponsorship acknowledged. Contents licensed under Apache License Version 2.0.
- + \ No newline at end of file diff --git a/docs/guides/documentation/documentation-hosts/use-cases/index.html b/docs/guides/documentation/documentation-hosts/use-cases/index.html index 2e3e59023..81dddfd47 100644 --- a/docs/guides/documentation/documentation-hosts/use-cases/index.html +++ b/docs/guides/documentation/documentation-hosts/use-cases/index.html @@ -5,13 +5,13 @@ Docs Use Cases | SLIM - +

Docs Use Cases

Resources
Community
More
Copyright © 2024 California Institute of Technology ("Caltech"). U.S. Government sponsorship acknowledged. Contents licensed under Apache License Version 2.0.
- + \ No newline at end of file diff --git a/docs/guides/documentation/readme/README-TEMPLATE/index.html b/docs/guides/documentation/readme/README-TEMPLATE/index.html index c71218cdc..d62ef0a59 100644 --- a/docs/guides/documentation/readme/README-TEMPLATE/index.html +++ b/docs/guides/documentation/readme/README-TEMPLATE/index.html @@ -5,13 +5,13 @@ README Template | SLIM - +

README Template

<!-- Header block for project -->
<hr>

<div align="center">

[INSERT YOUR LOGO IMAGE HERE (IF APPLICABLE)]
<!-- ☝️ Replace with your logo (if applicable) via ![](https://uri-to-your-logo-image) ☝️ -->
<!-- ☝️ If you see logo rendering errors, make sure you're not using indentation, or try an HTML IMG tag -->

<h1 align="center">[INSERT YOUR REPO / PROJ NAME HERE]</h1>
<!-- ☝️ Replace with your repo name ☝️ -->

</div>

<pre align="center">[INSERT A SINGLE SENTENCE DESCRIBING THE PURPOSE OF YOUR REPO / PROJ]</pre>
<!-- ☝️ Replace with a single sentence describing the purpose of your repo / proj ☝️ -->

<!-- Header block for project -->

[INSERT YOUR BADGES HERE (SEE: https://shields.io)] [![SLIM](https://img.shields.io/badge/Best%20Practices%20from-SLIM-blue)](https://nasa-ammos.github.io/slim/)
<!-- ☝️ Add badges via: https://shields.io e.g. ![](https://img.shields.io/github/your_chosen_action/your_org/your_repo) ☝️ -->

[INSERT SCREENSHOT OF YOUR SOFTWARE, IF APPLICABLE]
<!-- ☝️ Screenshot of your software (if applicable) via ![](https://uri-to-your-screenshot) ☝️ -->

[INSERT MORE DETAILED DESCRIPTION OF YOUR REPOSITORY HERE]
<!-- ☝️ Replace with a more detailed description of your repository, including why it was made and whom its intended for.  ☝️ -->

[INSERT LIST OF IMPORTANT PROJECT / REPO LINKS HERE]
<!-- example links>
[Website](INSERT WEBSITE LINK HERE) | [Docs/Wiki](INSERT DOCS/WIKI SITE LINK HERE) | [Discussion Board](INSERT DISCUSSION BOARD LINK HERE) | [Issue Tracker](INSERT ISSUE TRACKER LINK HERE)
-->

## Features

* [INSERT LIST OF FEATURES IMPORTANT TO YOUR USERS HERE]
  
<!-- ☝️ Replace with a bullet-point list of your features ☝️ -->

## Contents

* [Quick Start](#quick-start)
* [Changelog](#changelog)
* [FAQ](#frequently-asked-questions-faq)
* [Contributing Guide](#contributing)
* [License](#license)
* [Support](#support)

## Quick Start

This guide provides a quick way to get started with our project. Please see our [docs]([INSERT LINK TO DOCS SITE / WIKI HERE]) for a more comprehensive overview.

### Requirements

* [INSERT LIST OF REQUIREMENTS HERE]
  
<!-- ☝️ Replace with a numbered list of your requirements, including hardware if applicable ☝️ -->

### Setup Instructions

1. [INSERT STEP-BY-STEP SETUP INSTRUCTIONS HERE, WITH OPTIONAL SCREENSHOTS]
   
<!-- ☝️ Replace with a numbered list of how to set up your software prior to running ☝️ -->

### Run Instructions

1. [INSERT STEP-BY-STEP RUN INSTRUCTIONS HERE, WITH OPTIONAL SCREENSHOTS]

<!-- ☝️ Replace with a numbered list of your run instructions, including expected results ☝️ -->

### Usage Examples

* [INSERT LIST OF COMMON USAGE EXAMPLES HERE, WITH OPTIONAL SCREENSHOTS]

<!-- ☝️ Replace with a list of your usage examples, including screenshots if possible, and link to external documentation for details ☝️ -->

### Build Instructions (if applicable)

1. [INSERT STEP-BY-STEP BUILD INSTRUCTIONS HERE, WITH OPTIONAL SCREENSHOTS]

<!-- ☝️ Replace with a numbered list of your build instructions, including expected results / outputs with optional screenshots ☝️ -->

### Test Instructions (if applicable)

1. [INSERT STEP-BY-STEP TEST INSTRUCTIONS HERE, WITH OPTIONAL SCREENSHOTS]

<!-- ☝️ Replace with a numbered list of your test instructions, including expected results / outputs with optional screenshots ☝️ -->

## Changelog

See our [CHANGELOG.md](CHANGELOG.md) for a history of our changes.

See our [releases page]([INSERT LINK TO YOUR RELEASES PAGE]) for our key versioned releases.

<!-- ☝️ Replace with links to your changelog and releases page ☝️ -->

## Frequently Asked Questions (FAQ)

[INSERT LINK TO FAQ PAGE OR PROVIDE FAQ INLINE HERE]
<!-- example link to FAQ PAGE>
Questions about our project? Please see our: [FAQ]([INSERT LINK TO FAQ / DISCUSSION BOARD])
-->

<!-- example FAQ inline format>
1. Question 1
   - Answer to question 1
2. Question 2
   - Answer to question 2
-->

<!-- example FAQ inline with no questions yet>
No questions yet. Propose a question to be added here by reaching out to our contributors! See support section below.
-->

<!-- ☝️ Replace with a list of frequently asked questions from your project, or post a link to your FAQ on a discussion board ☝️ -->

## Contributing

[INSERT LINK TO CONTRIBUTING GUIDE OR FILL INLINE HERE]
<!-- example link to CONTRIBUTING.md>
Interested in contributing to our project? Please see our: [CONTRIBUTING.md](CONTRIBUTING.md)
-->

<!-- example inline contributing guide>
1. Create an GitHub issue ticket describing what changes you need (e.g. issue-1)
2. [Fork](INSERT LINK TO YOUR REPO FORK PAGE HERE, e.g. https://github.com/my_org/my_repo/fork) this repo
3. Make your modifications in your own fork
4. Make a pull-request in this repo with the code in your fork and tag the repo owner / largest contributor as a reviewer

**Working on your first pull request?** See guide: [How to Contribute to an Open Source Project on GitHub](https://kcd.im/pull-request)
-->

[INSERT LINK TO YOUR CODE_OF_CONDUCT.md OR SHARE TEXT HERE]
<!-- example link to CODE_OF_CONDUCT.md>
For guidance on how to interact with our team, please see our code of conduct located at: [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md)
-->

<!-- ☝️ Replace with a text describing how people may contribute to your project, or link to your contribution guide directly ☝️ -->

[INSERT LINK TO YOUR GOVERNANCE.md OR SHARE TEXT HERE]
<!-- example link to GOVERNANCE.md>
For guidance on our governance approach, including decision-making process and our various roles, please see our governance model at: [GOVERNANCE.md](GOVERNANCE.md)
-->

## License

See our: [LICENSE](LICENSE)
<!-- ☝️ Replace with the text of your copyright and license, or directly link to your license file ☝️ -->

## Support

[INSERT CONTACT INFORMATION OR PROFILE LINKS TO MAINTAINERS AMONG COMMITTER LIST]

<!-- example list of contacts>
Key points of contact are: [@github-user-1](link to github profile) [@github-user-2](link to github profile)
-->

<!-- ☝️ Replace with the key individuals who should be contacted for questions ☝️ -->
Resources
Community
More
Copyright © 2024 California Institute of Technology ("Caltech"). U.S. Government sponsorship acknowledged. Contents licensed under Apache License Version 2.0.
- + \ No newline at end of file diff --git a/docs/guides/documentation/readme/index.html b/docs/guides/documentation/readme/index.html index f58c268dc..555053f28 100644 --- a/docs/guides/documentation/readme/index.html +++ b/docs/guides/documentation/readme/index.html @@ -5,13 +5,13 @@ READMEs | SLIM - +

READMEs

A guide to constructing an effective and impressive README for your project.

Introduction​

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.

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

Prerequisites​

  • Basic knowledge of Markdown formatting.
  • Understanding of your project's key features and usage.

Quick Start​

⬇️ 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.
  2. Customize the Template:
    • Copy the 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:

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.

Resources
Community
More
Copyright © 2024 California Institute of Technology ("Caltech"). U.S. Government sponsorship acknowledged. Contents licensed under Apache License Version 2.0.
- + \ No newline at end of file diff --git a/docs/guides/governance/contributions/code-of-conduct/index.html b/docs/guides/governance/contributions/code-of-conduct/index.html index 24ce1471f..6eb7890c0 100644 --- a/docs/guides/governance/contributions/code-of-conduct/index.html +++ b/docs/guides/governance/contributions/code-of-conduct/index.html @@ -5,13 +5,13 @@ Code of Conduct | SLIM - +

Code of Conduct

A walkthrough on setting up a code-of-conduct policy for your project.

Introduction​

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.

Use Cases:

  • Establishing a respectful and inclusive team culture.
  • Providing clear guidelines on acceptable behaviors and handling grievances.

Prerequisites​

  • Understanding of community management and team dynamics.
  • Familiarity with Markdown for editing documentation.

Quick Start​

⬇️ Contributor Covenant Template

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.
      [![Contributor Covenant](https://img.shields.io/badge/Contributor%20Covenant-2.1-4baaaa.svg)](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:

Acknowledgements:

Feedback and Contributions​

Your feedback and contributions are welcome to enhance this guide. See our contribution guidelines.

Resources
Community
More
Copyright © 2024 California Institute of Technology ("Caltech"). U.S. Government sponsorship acknowledged. Contents licensed under Apache License Version 2.0.
- + \ No newline at end of file diff --git a/docs/guides/governance/contributions/contributing-guide/CONTRIBUTING/index.html b/docs/guides/governance/contributions/contributing-guide/CONTRIBUTING/index.html index 86b9ee598..afe3f6f5c 100644 --- a/docs/guides/governance/contributions/contributing-guide/CONTRIBUTING/index.html +++ b/docs/guides/governance/contributions/contributing-guide/CONTRIBUTING/index.html @@ -5,13 +5,13 @@ CONTRIBUTING | SLIM - +

CONTRIBUTING

# Contributing Guide

Thanks for taking the time to consider contributing! We very much appreciate your time and effort. This document outlines the many ways you can contribute to our project, and provides detailed guidance on best practices. We look forward to your help!

## Prerequisites

Before you begin contributing to our project, it'll be a good idea to ensure you've satisfied the below pre-requisites. 

### License

Our project has our licensing terms, including rules governing redistribution, documented in our [LICENSE](LICENSE) file. Please take a look at that file and ensure you understand the terms. This will impact how we, or others, use your contributions.

### Code of Conduct

Our Code of Conduct helps facilitate a positive interaction environment for everyone involved with the team, and provides guidance on what to do if you experience problematic behavior. Read more in our [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md), and make sure you agree to its terms. 

### Developer Environment

For patch contributions, see our [Developer Documentation]([INSERT YOUR DEVELOPMENT GUIDE LINK HERE]) for more details on how to set up your local environment, to best contribute to our project. 

At a minimum however to submit patches (if using Git), you'll want to ensure you have:
1. An account on the Version Control System our project uses (i.e. GitHub).
2. The Version Control System client (i.e. Git) installed on your local machine.
3. The ability to edit, build, and test our project on your local machine. Again, see our [README.md](README.md) or detailed developer guide for more details 

### Communication Channels

Before contributing changes to our project, it's a great idea to be familiar with our communication channels and to socialize your potential contributions to get feedback early. This will help give you context for your contributions, no matter their form.

Our communication channels are:
- [Issue tracking system]([INSERT LINK TO ISSUE TRACKING SYSTEM]) - a regularly monitored area to report issues with our software or propose changes
- [Discussion board]([INSERT LINK TO DISCUSSION BOARD OR MAILING LIST]) - an permanently archived place to hold conversations related to our project, and to propose as well as show+tell topics to the contributor team. This resource can be searched for old discussions.
- [INSERT ADDITIONAL COMMUNICATION CHANNELS FOR YOUR PROJECT, EX: SLACK, TWITTER, YOUTUBE, ETC.]

### Communication Channels

Before contributing changes to our project, it's a great idea to be familiar with our communication channels and to socialize your potential contributions to get feedback early. This will help give you context for your contributions, no matter their form.

Our communication channels are:
- [Issue tracking system]([INSERT LINK TO ISSUE TRACKING SYSTEM]) - a regularly monitored area to report issues with our software or propose changes
- [Discussion board](INSERT LINK TO DISCUSSION BOARD OR MAILING LIST) - an permanently archived place to hold conversations related to our project, and to propose as well as show+tell topics to the contributor team. This resource can be searched for old discussions.
- [INSERT ADDITIONAL COMMUNICATION CHANNELS FOR YOUR PROJECT, EX: SLACK, TWITTER, YOUTUBE, ETC.]

## Our Development Process

Our project integrates contributions from many people, and so we'd like to outline a process you can use to visualize how your contributions may be integrated if you provide something. 

```mermaid
flowchart TD
    repo_proj[(Our Repository)]-->|Fork|repo_fork[(Your Forked Repository)]
    repo_fork-->|Make|patch(Your Changes)
    patch-->|Submit|pr(Pull Request)
    pr==>|Approved|repo_proj
    pr-->|Changes Requested|repo_fork
```

### Fork our Repository

Forking our repository, as opposed to directly committing to a branch is the preferred way to propose changes. 

See [this GitHub guide](https://docs.github.com/en/get-started/quickstart/fork-a-repo) on forking for information specific to GitHub.com

#### Find or File an Issue

Make sure people are aware you're working on a patch! Check out our [issue tracking system]([INSERT LINK TO YOUR ISSUE TRACKING SYSTEM]) and find an open issue you'd like to work against, or alternatively file a new issue and mention you're working on a patch.

#### Choose the Right Branch to Fork

Our project typically has the following branches available, make sure to fork either the default branch or a branch someone else already tagged with a particular issue ticket you're working with.
- `main`[INSERT DEFAULT VCS BRANCH NAME HERE] - default branch
- [INSERT ADDITIONAL TYPICAL VCS BRANCH NAMES HERE] - 

### Make your Modifications

Within your local development environment, this is the stage at which you'll propose your changes, and commit those changes back to version control. See the [README.md](README.md) or development guide for more specifics on what you'll need as prerequisites to setup your local development environment.

#### Commit Messages

Commit messages to version control should reference a ticket in their title / summary line:

```
Issue #248 - Show an example commit message title
```

This makes sure that tickets are updated on GitHub with references to commits that are related to them.

Commit should always be atomic. Keep solutions isolated whenever possible. Filler commits such as "clean up white space" or "fix typo" should be merged together before making a pull request, and significant sub-feature branches should be [rebased](https://www.youtube.com/results?search_query=git+rebase) to preserve commit history. Please ensure your commit history is clean and meaningful!

### Submit a Pull Request

Pull requests are the core way our project will receive your patch contributions. Navigate to your branch on your own fork within the version control system, and submit a pull request or submit the patch text to our project. 

Please make sure to provide a meaningful text description to your pull requests, whenever submitted. Our pull-request template will be auto-generated for you when you create your pull-request. See the template [here]([INSERT LINK TO YOUR PULL REQUEST TEMPLATE, ex: .github/PULL_REQUEST_TEMPLATE.md]). 

**Working on your first Pull Request?** See guide: [How to Contribute to an Open Source Project on GitHub](https://kcd.im/pull-request)

### Reviewing your Pull Request

Reviewing pull-requests, or any kinds of proposed patch changes, is an art. That being said, we follow the following best practices:
- **Intent** - is the purpose of your pull-request clearly stated?
- **Solution** - is your pull-request doing what you want it to?
- **Correctness** - is your pull-request doing what you want it to *correctly*?
- **Small Patches** - is your patch of a level of complexity and brevity that it can actually be reviewed by a human being? Or is does it involve too much content for one pull request?
- **Coding best practices** - are you following best practices in the coding / contribution language being used?
- **Readability** - is your patch readable, and ultimately maintainable, by others?
- **Reproducibility** - is your patch reproducible by others?
- **Tests** - do you have or have conducted meaningful tests?

## Ways to Contribute

### ⚠️ Issue Tickets

> *Do you like to talk about new features, changes, requests?*

Issue tickets are a very simple way to get involved in our project. It also helps new contributors get an understanding of the project more comprehensively. This is a great place to get started with the project if you're not sure where to start. 

See our list of issues at: [INSERT LINK TO YOUR ISSUE TRACKING SYSTEM]

#### Cleaning up Duplicate Issues

Often we receive duplicate issues that can confuse project members on *which* issue ticket to hold conversations upon.

Here's how you can help:
1. Scan the list of *open* issue tickets for duplicate titles, or internal wording 
2. If you find duplicates, copy / paste the below message on the conversation thread of the issue ticket *that has less participants* involved

```
This is a duplicate issue. Please migrate conversations over to [issue-XYZ](hyperlink to issue)
```

#### Good First Issues

Issue tickets can vary in complexity, and issues labeled with `good first issue` labels are often a great way to get started with the project as a newcomer. 

Take a look at our [issue tracking system]([INSERT LINK TO YOUR ISSUE TRACKING SYSTEM]), and filter by `good first issue` for issues that are low-complexity, and that will help you get familiar with our issue tracking and patch submission process.

#### Suggesting New Issue Labels

Labels within our [issue tracking system]([INSERT LINK TO YOUR ISSUE TRACKING SYSTEM]) are a great way to quickly sort through tickets. The project may not yet have labels to cover the full variety of issue tickets. Take a look through our list of issues, and if you notice a set of issue tickets that seem similar but are not categorized with an existing label, go ahead submit a request within one of the issues you've looked at with the following text:

```
I've noticed several other issues that are of the same category as this issue. Shall we make a new label for these types of issues?
```

#### Submitting Bug Issues

Resolving bugs is a priority for our project. We welcome bug reports. However, please make sure to do the following prior to submitting a bug report:
- **Check for duplicates** - there may be a bug report already describing your issue, so check the [issue tracking system]([INSERT LINK TO YOUR ISSUE TRACKING SYSTEM]) first.

Here's some guidance on submitting a bug issue:
1. Navigate to our [issue tracking system]([INSERT LINK TO YOUR ISSUE TRACKING SYSTEM]) and file a new issue
2. Select a bug template (if available) for your issue
   1. Fill out the template fields to the best of your ability, including output snippets or screenshots where applicable
3. Follow the general guidelines below for extra information about your bug
   1. Include a code snippet if you have it showcasing the bug
   2. Provide reproducible steps of how to recreate the bug
   3. If the bug triggers an exception or error message, include the *full message* or *stacktrace*
   4. Provide information about your operating system and the version of our project you're using

#### Submitting New Feature Issues

We welcome new feature requests to help grow our project. However, please make sure to do the following prior to submitting a new feature request:
- **Check for duplicates** - there may be a new feature issue already describing your issue, so check the [issue tracking system]([INSERT LINK TO YOUR ISSUE TRACKING SYSTEM]) first
- **Consider alternatives** - is your feature really needed? Or is there a feature within our project or with a third-party that may help you achieve what you want?

Here's some guidance on submitting a new feature issue:
1. Navigate to our [issue tracking system]([INSERT LINK TO YOUR ISSUE TRACKING SYSTEM]) and file a new issue
2. Select a new feature template (if available) for your issue
   1. Fill out the template fields to the best of your ability

#### Submitting Security Vulnerability Issues

Security vulnerabilities should **not** be filed to the regular issue tracking system.

Report your security vulnerabilities to (see contact links): [INSERT SECURITY CONTACT LINK HERE]

Please be sure to:
* Indicate the severity of the vulnerability
* Provide any workarounds, if you know them
* Provide return-contact information to follow-up with you if needed

#### Reviewing Pull Requests

Reviewing others' contributions is a great way to learn about best practices in both contributions as well as software. 

Take a look at our [pull requests tracking system]([INSERT LINK FOR PULL REQUESTS TRACKING SYSTEM]), and try the following options for providing a review:
1. Read the code / patch associated with the pull-request, and take note of any coding, bug, or documentation issues if found
2. Try to recreate the pull-request patch on your local machine, and report if it has issues with your system in particular
3. Scan over suggested feedback from other contributors, and provide feedback if necessary

### 💻  Code

⚠️ It's **highly** advised that you take a look at our [issue tracking system]([INSERT LINK TO YOUR ISSUE TRACKING SYSTEM]) before considering any code contributions. Here's some guidelines:
1. Check if any duplicate issues exist that cover your code contribution idea / task, and add comments to those tickets with your thoughts.
2. If no duplicates exist, create a new issue ticket and get a conversation started before making code changes using our [communication channels](#communication-channels).

Once you have a solid issue ticket in hand and are ready to work on code, you'll want to:
1. Ensure you have development [prerequisites](#prerequisites) cleared.
2. Have your [development environment](#developer-environment) set up properly.
3. Go through our [development process](#our-development-process), including proposing changes to our project.

Some guidelines for code-specific contributions:
- **Do your homework** - read-up on necessary documentation, like `README.md`s, developer documentation, and pre-existing code to see the intention and context necessary to make your contribution a success. It's important to _communicate_ what you're working on through our project [communication channels](#communication-channels) and get buy-in from frequent contributors - this will help the project be more receptive to your contributions! 
- **Ask questions** - its important to ask questions while you work on your contributions, to check-in with frequent contributors on the style and the set of expectations to make your code contribution work well with pre-existing project code. Use our [communication channels](#communication-channels)
- **Keep positive** - code contributions, by their nature, have direct impacts on the output and functionality of the project. Keep a positive spirit as your code is reviewed, and take it in stride if core contributors take time to review, give you suggestions for your code or respectfully decline your contribution. This is all part of the process for quality open source development. 
- **Comments** - include *useful* comments throughout your code that explain the intention of a code block, not a step-by-step analysis. See our [inline code documentation](#inline-code-documentation) section for specifics. 

[INSERT ADDITIONAL SECTIONS HERE FOR MORE SPECIFIC CLASSES OF CODE CONTRIBUTIONS DEPENDING ON YOUR MODULES, LANGUAGES, PLATFORMS IN USE BY YOUR PROJECT. THE MORE DETAILS YOU OFFER, THE MORE LIKELY SOMEONE IS TO UNDERSTAND HOW TO CONTRIBUTE]
<!-- EXAMPLE: APIs, PyTest, etc. -->

### 📖 Documentation 

Documentation is the core way our users and contributors learn about the project. We place a high value on the quality, thoroughness, and readability of our documentation. Writing or editing documentation is an excellent way to contribute to our project without performing active coding. 

⚠️ It's **highly** advised that you take a look at our [issue-tracking system]([INSERT LINK TO YOUR ISSUE TRACKING SYSTEM]) before considering any documentation contributions. Here's some guidelines:
1. Check if any duplicate issues exist that cover your documentation contribution idea / task, and add comments to those tickets with your thoughts.
2. If no duplicates exist, create a new issue ticket and get a conversation started before making documentation changes.

Some guidelines for documentation best practices (summarized from Google's [excellent documentation guide](https://google.github.io/styleguide/docguide/best_practices.html)):
- **Minimum viable docs** - don't do less documentation than your users / developers need, but also don't do more
- **Changed code = changed docs** - if your code has changed, remember to update your documentation
- **Delete old docs** - continually clean your documentation tree, and remove outdated docs regularly

#### Documentation Organization

The overall structure of our project documentation is as follows:
- Source-controlled documentation
  - [README.md](README.md) - top-level information about how to run, build, and contribute to the project
  - [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) - best practices and guidance on how to work well with other people in the project, and suggestions on dealing with interpersonal issues
  - [CONTRIBUTING.md](CONTRIBUTING.md) - guidance on contributing to the project
  - `*.[INSERT YOUR CODING LANGUAGE FILE EXTENSIONS HERE]` - inline documentation available inside code files
- [INSERT ADDITIONAL DOCUMENTATION CLASSES AND ORGANIZATION STRUCTURE HERE, SEE EXAMPLE IN COMMENTS BELOW]

<!-- EXAMPLE:
- Source-controlled documentation
  - [README.md](README.md) - top-level information about how to run, build, and contribute to the project
  - [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) - best practices and guidance on how to work well with other people in the project, and suggestions on dealing with interpersonal issues
  - [CONTRIBUTING.md](CONTRIBUTING.md) - guidance on contributing to the project
  - `*.py` - inline documentation available inside code files' function headers and code blocks
  - [docs/](docs/)` - top-level directory containing source-controlled documentation built into statically hosted files on our documentation website
- Hosted documentation
  - [Wiki Main-page]()
    - [Wiki Sub-page 1]()
    - [Wiki Sub-page 2]() 
- Discussion Boards
  - [Discussion Board Topic 1]()
  - [Discussion Board Topic 2]()
- YouTube.com video tutorials
  - [Channel page 1]()
  - [Channel page 2]()
- Application Programming Interface (API) documentation
  - [Sub-module 1]()
  - [Sub-module 2]()
- etc.
-->

For directions on contributing to our source-controlled documentation:
1. Ensure you have development [prerequisites](#prerequisites) cleared.
2. Have your [development environment](#developer-environment) set up properly.
3. Go through our [development process](#our-development-process), including proposing changes to our project.

<!-- OPTIONAL FOR HOSTED DOCUMENTATION >
For directions on contributing to our hosted documentation:
1. 
2. 
3. 

[INSERT HOSTED DOCUMENTATION PLATFORM SPECIFIC INSTRUCTIONS HERE FOR HOW TO CONTRIBUTE]
-->

#### Writing Style

To ensure documentation is readable and consistent by newcomers and experts alike, here are some suggestions on writing style for English:
- Use gender neutral pronouns (they/their/them) instead of he/she/his/her 
- Avoid qualifiers that minimize the difficulty of a task at hand, e.g. avoid words like “easily”, “simply”, “just”, “merely”, “straightforward”, etc. Readers' expertise may not match your own, and qualifying complexity may deter some readers if the task does not match their level of experience. That being said, if a particular task is difficult or complex, do mention that. 

#### Common Wording 

Below are some commonly used words you'll want to leverage in your documentation contributions:
- **GitHub** - one word, and capitalization of the 'G' and the 'H'
- [INSERT YOUR PROJECT SPECIFIC COMMON TERMS AND HOW TO USE THEM]

#### Inline Code Documentation

For language-specific guidance on code documentation, including style guides, see [Google's list of language style guides](https://google.github.io/styleguide/) for a variety of languages. 

Additionally, take a look at Google's recommendations on [inline code documentation](https://google.github.io/styleguide/docguide/best_practices.html#documentation-is-the-story-of-your-code) for best practices. 

#### Media

Media, such as such as images, videos, sound files, etc., are an excellent way to explain documentation to a wider audience more easily. Include media in your contributions as often as possible.

When including media into our version-control system, it is recommended to use formats such as:
- Diagrams: [Mermaid](https://mermaid-js.github.io/mermaid/#/) format
- Images: JPEG format
- Videos: H264 MPEG format
- Sounds: MP3 format
<!-- ADD TO OR MODIFY ABOVE DEFAULT SUGGESTIONS -->

### ❓ Questions

Answering questions is an excellent way to learn more about our project, as well as get better known in our project community. 

Here are just a few ways you can help answer questions for our project:
- Answer open questions in our [discussion forum]([INSERT LINK TO DISCUSSION FORUM])
- Answer open questions mentioned in our [issue tracking system]([INSERT LINK TO YOUR ISSUE TRACKING SYSTEM])
<!-- ADD TO OR MODIFY DEPENDING ON YOUR COMMUNICATION CHANNELS LISTED AT THE BEGINNING OF THIS DOCUMENT-->

When answering questions, keep the following in mind:
- Be polite and friendly. See our [Code of Conduct](CODE_OF_CONDUCT.md) recommendations as you interact with others in the team.
- Repeat the specific question you are answering, followed by your suggestion.
- If suggesting code, repeat the line of code that needs to be altered, followed by your alteration
- Include any post-steps or checks to verify your answer can be reproduced 

### 🎨 Design

Design files can help to guide new features and new areas of expansion for our project. We welcome these kinds of contributions.

Here are just a few ways you can help provide design recommendations for our project:
- Create visual mockups or diagrams to increase usability of our project applications. This can apply to user interfaces, documentation structuring, or even code architecture diagrams.
- Conduct user research to understand user needs better. Save your findings within spreadsheets that the project team / contributors can review.
- Create art, such as logos or icons, to support the user experience for the project

Each of the above can be contributed directly to repository code, and you should use our [development process](#our-development-process) to contribute your additions.

### 🎟️ Meetups

A great way to contribute towards our project goals is to socialize and encourage people to meet and learn more about each other. Consider ideas like:
- Propose workshops or meetups regarding some topic within our project
- Help point project contributors and community members to conferences and publications where they may socialize their unique innovations
- Schedule in-person or virtual happy-hours to help create a more social atmosphere within the project community

For the above ideas, use our [communication channels](#communication-channels) to propose get-togethers.
Resources
Community
More
Copyright © 2024 California Institute of Technology ("Caltech"). U.S. Government sponsorship acknowledged. Contents licensed under Apache License Version 2.0.
- + \ No newline at end of file diff --git a/docs/guides/governance/contributions/contributing-guide/index.html b/docs/guides/governance/contributions/contributing-guide/index.html index 4a8591c9e..ee1f08acf 100644 --- a/docs/guides/governance/contributions/contributing-guide/index.html +++ b/docs/guides/governance/contributions/contributing-guide/index.html @@ -5,14 +5,14 @@ Contributing Guide | SLIM - +

Contributing Guide

Fast track developing a contribution guide for your new contributors.

Introduction​

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.

Use Cases:

  • Guiding new contributors on making meaningful contributions.
  • Ensuring contributions align with project norms and requirements.
  • Facilitating a transparent and efficient contribution process.

Prerequisites​

  • Understanding of basic project management and version control systems.
  • Familiarity with GitHub and Markdown formatting.

Quick Start​

⬇️ Contributing Guide Template

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.
  1. Customize the Template: Modify the Contributing Guide Template 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.
  2. Integrate with Project:
    • Add a link to CONTRIBUTING.md in your project's README.md file under the Contributing section.
  3. 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:

Acknowledgements: This template is influenced by guidelines from the following:

Feedback and Contributions​

Feedback and contributions are encouraged to refine this guide. Visit our contribution guidelines for more information.

Resources
Community
More
Copyright © 2024 California Institute of Technology ("Caltech"). U.S. Government sponsorship acknowledged. Contents licensed under Apache License Version 2.0.
- + \ No newline at end of file diff --git a/docs/guides/governance/contributions/issue-templates/bug-reports/bug_report.yml/index.html b/docs/guides/governance/contributions/issue-templates/bug-reports/bug_report.yml/index.html index a499e54aa..0883c1a6f 100644 --- a/docs/guides/governance/contributions/issue-templates/bug-reports/bug_report.yml/index.html +++ b/docs/guides/governance/contributions/issue-templates/bug-reports/bug_report.yml/index.html @@ -5,13 +5,13 @@ bug_report.yml | SLIM - +

bug_report.yml

name: Bug Report Form
description: Report a bug to help us improve
title: "[Bug]: "
labels: "bug"
body:
  - type: markdown
    attributes:
      value: |
        > _Thanks for filing a bug ticket. We appreciate your time and effort. Please answer a few questions._
  - type: dropdown
    id: checked-for-duplicates
    attributes:
      label: Checked for duplicates
      description: Have you checked for duplicate issue tickets?
      multiple: false
      options:
        - "Yes - I've already checked"
        - "No - I haven't checked"
    validations:
      required: yes
  - type: textarea
    id: description
    attributes:
      label: Describe the bug
      description: A clear and concise description of what the bug is. Plain-text snippets preferred but screenshots welcome.
      placeholder: Tell us what you saw
      value: "When I did [...] action, I noticed [...]"
    validations:
      required: true
  - type: textarea
    id: expected-behavior
    attributes:
      label: What did you expect?
      description: A clear and concise description of what you expect to happen
      placeholder: Tell us what you expected
      value: "I expected [...]"
    validations:
      required: true
  - type: textarea
    id: reproduction
    attributes:
      label: Reproducible steps
      description: "How would we reproduce this bug? Please walk us through it step by step. Plain-text snippets preferred but screenshots welcome."
      value: |
        1.
        2.
        3.
        ...
      render: bash
  - type: textarea
    id: environment
    attributes:
      label: Environment
      description: "What is your environment? Include any computer hardware, operating system, framework, browser, time-of-day or other contextual information related to your issue"
      value: |
        - Version of this software [e.g. vX.Y.Z]
        - Operating System: [e.g. MacOSX with Docker Desktop vX.Y]
        ...
      render: bash
Resources
Community
More
Copyright © 2024 California Institute of Technology ("Caltech"). U.S. Government sponsorship acknowledged. Contents licensed under Apache License Version 2.0.
- + \ No newline at end of file diff --git a/docs/guides/governance/contributions/issue-templates/bug-reports/bug_report/index.html b/docs/guides/governance/contributions/issue-templates/bug-reports/bug_report/index.html index 6810912fe..b7467acf8 100644 --- a/docs/guides/governance/contributions/issue-templates/bug-reports/bug_report/index.html +++ b/docs/guides/governance/contributions/issue-templates/bug-reports/bug_report/index.html @@ -5,13 +5,13 @@ bug_report | SLIM - +

bug_report

---
name: Bug Report
about: Report a bug to help us improve
title: '[Bug]: '
labels: 'bug'
assignees: ''

---

**Checked for duplicates**

> Have you checked for duplicate issue tickets?

- Ex. Yes - I've already checked
- Ex. No - I haven't checked

**Describe the bug**

> A clear and concise description of what the bug is. Plain-text snippets preferred but screenshots welcome.

Ex. When I did [...] action, I noticed [...]

**What did you expect?**

> A clear and concise description of what you expect to happen

Ex. I expected [...]

**Reproducible steps**

> How would we reproduce this bug? Please walk us through it step by step. Plain-text snippets preferred but screenshots welcome.

1.
2.
3.

**What is your environment?**

> Include any computer hardware, operating system, framework, browser, time-of-day or other contextual information related to your issue

- Ex. Version of this software [e.g. vX.Y.Z]
- Ex. Operating System: [e.g. MacOSX with Docker Desktop vX.Y]
- ...
Resources
Community
More
Copyright © 2024 California Institute of Technology ("Caltech"). U.S. Government sponsorship acknowledged. Contents licensed under Apache License Version 2.0.
- + \ No newline at end of file diff --git a/docs/guides/governance/contributions/issue-templates/features/new_feature.yml/index.html b/docs/guides/governance/contributions/issue-templates/features/new_feature.yml/index.html index 23e9aa3be..10c478c9f 100644 --- a/docs/guides/governance/contributions/issue-templates/features/new_feature.yml/index.html +++ b/docs/guides/governance/contributions/issue-templates/features/new_feature.yml/index.html @@ -5,13 +5,13 @@ new_feature.yml | SLIM - +

new_feature.yml

name: New Feature Form
description: Suggest a new feature for us to implement
title: "[New Feature]: "
labels: "enhancement"
body:
  - type: markdown
    attributes:
      value: |
        > _Thanks for filing a new feature request. We appreciate your time and effort. Please answer a few questions._
  - type: dropdown
    id: checked-for-duplicates
    attributes:
      label: Checked for duplicates
      description: Have you checked for duplicate issue tickets?
      multiple: false
      options:
        - "Yes - I've already checked"
        - "No - I haven't checked"
    validations:
      required: yes
  - type: dropdown
    id: checked-alternatives
    attributes:
      label: Alternatives considered
      description: Have you considered alternative solutions to your feature request?
      options:
        - "Yes - and alternatives don't suffice"
        - "No - I haven't considered"
    validations:
      required: yes
  - type: textarea
    id: related-problems
    attributes:
      label: Related problems
      description: Is your feature request related to any problems? Please help us understand if so, including linking to any other issue tickets.
      placeholder: Tell us the problems
      value: "I'm frustrated when [...] happens as documented in issue-XYZ"
    validations:
      required: false
  - type: textarea
    id: description
    attributes:
      label: Describe the feature request
      description: A clear and concise description of your request. 
      placeholder: Tell us what you want
      value: "I need or want [...]"
    validations:
      required: true
Resources
Community
More
Copyright © 2024 California Institute of Technology ("Caltech"). U.S. Government sponsorship acknowledged. Contents licensed under Apache License Version 2.0.
- + \ No newline at end of file diff --git a/docs/guides/governance/contributions/issue-templates/features/new_feature/index.html b/docs/guides/governance/contributions/issue-templates/features/new_feature/index.html index c3a81765d..a302f4df9 100644 --- a/docs/guides/governance/contributions/issue-templates/features/new_feature/index.html +++ b/docs/guides/governance/contributions/issue-templates/features/new_feature/index.html @@ -5,13 +5,13 @@ new_feature | SLIM - +

new_feature

---
name: New Feature
about: Suggest a new feature for us to implement
title: '[New Feature]: '
labels: 'enhancement'
assignees: ''

---

**Checked for duplicates**

> Have you checked for duplicate issue tickets?

- Ex. Yes - I've already checked
- Ex. No - I haven't checked

**Alternatives considered**

> Have you considered alternative solutions to your feature request?

- Ex. Yes - and alternatives don't suffice
- Ex. No - I haven't considered

**Related problems**

> Is your feature request related to any problems? Please help us understand if so, including linking to any other issue tickets.

Ex. I'm frustrated when [...] happens as documented in issue-XYZ

**Describe the feature request**

> A clear and concise description of your request. 

Ex. I need or want [...]
Resources
Community
More
Copyright © 2024 California Institute of Technology ("Caltech"). U.S. Government sponsorship acknowledged. Contents licensed under Apache License Version 2.0.
- + \ No newline at end of file diff --git a/docs/guides/governance/contributions/issue-templates/index.html b/docs/guides/governance/contributions/issue-templates/index.html index 26a4fe8fa..0e670c84a 100644 --- a/docs/guides/governance/contributions/issue-templates/index.html +++ b/docs/guides/governance/contributions/issue-templates/index.html @@ -5,13 +5,13 @@ Issue Templates | SLIM - +

Issue Templates

Make issue tracking clear and consistent with structured issue templates for your contributors.

Introduction​

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.

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.

Prerequisites​

  • Access to a GitHub repository with administrative permissions.
  • Basic knowledge of Markdown for editing GitHub templates.

Quick Start​

Bug Reports:

New Features:

📔 GitHub Issue Template Documentation

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:

  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:

Acknowledgements:

  • GitHub for providing documentation for issue templates.

Feedback and Contributions​

Feedback and contributions are welcome to enhance these guidelines. See our contribution guidelines.

Resources
Community
More
Copyright © 2024 California Institute of Technology ("Caltech"). U.S. Government sponsorship acknowledged. Contents licensed under Apache License Version 2.0.
- + \ No newline at end of file diff --git a/docs/guides/governance/contributions/pull-requests/PULL_REQUEST_TEMPLATE/index.html b/docs/guides/governance/contributions/pull-requests/PULL_REQUEST_TEMPLATE/index.html index 6e90b4f9a..2875929fb 100644 --- a/docs/guides/governance/contributions/pull-requests/PULL_REQUEST_TEMPLATE/index.html +++ b/docs/guides/governance/contributions/pull-requests/PULL_REQUEST_TEMPLATE/index.html @@ -5,13 +5,13 @@ PULL_REQUEST_TEMPLATE | SLIM - +

PULL_REQUEST_TEMPLATE

## Purpose
- Clear, easy-to-understand sentences outlining the purpose of the PR
## Proposed Changes
- [ADD] ...
- [CHANGE] ...
- [REMOVE] ...
- [FIX] ...
## Issues
- Links to relevant issues
- Example: issue-XYZ
## Testing
- Provide some proof you've tested your changes 
- Example: test results available at ...
- Example: tested on operating system ...
Resources
Community
More
Copyright © 2024 California Institute of Technology ("Caltech"). U.S. Government sponsorship acknowledged. Contents licensed under Apache License Version 2.0.
- + \ No newline at end of file diff --git a/docs/guides/governance/contributions/pull-requests/index.html b/docs/guides/governance/contributions/pull-requests/index.html index d1d1b4251..4643742c8 100644 --- a/docs/guides/governance/contributions/pull-requests/index.html +++ b/docs/guides/governance/contributions/pull-requests/index.html @@ -5,13 +5,13 @@ Pull Requests | SLIM - +

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

Our recommended pull request template for projects.

📔 GitHub Pull Request Template Documentation

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 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 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:

Feedback and Contributions​

We welcome feedback and contributions to enhance this guide. For contributing, please see our contribution guidelines.

Resources
Community
More
Copyright © 2024 California Institute of Technology ("Caltech"). U.S. Government sponsorship acknowledged. Contents licensed under Apache License Version 2.0.
- + \ No newline at end of file diff --git a/docs/guides/governance/governance-model/GOVERNANCE-TEMPLATE/index.html b/docs/guides/governance/governance-model/GOVERNANCE-TEMPLATE/index.html index 6dfa70d87..be61b2eef 100644 --- a/docs/guides/governance/governance-model/GOVERNANCE-TEMPLATE/index.html +++ b/docs/guides/governance/governance-model/GOVERNANCE-TEMPLATE/index.html @@ -5,13 +5,13 @@ GOVERNANCE-TEMPLATE | SLIM - +

GOVERNANCE-TEMPLATE

# [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 governing committees (e.g. technical steering, project steering) are set up to ensure the project's direction is in-line with requirements / goals while supporting flexibility for future growth and membership. Technical decision making will primarily be made through a "[consensus-seeking](https://en.wikipedia.org/wiki/Consensus-seeking_decision-making)" approach within the respective governing committees. 

## Roles

| Role                                | Restricted To | Description                                                                                                                                                                           | Read/Clone                           | Propose Pull Request                 | Comment in Tickets / Discussions     | Triage                               | Review                               | Commit                               | Technical Decisions                  | Project 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.                                                                                         | ✅ | ✅ | ✅ | ❌    | ❌    | ❌    | ❌    | ❌    |
| Triager                             | Contributor   | Subset of contributors demonstrating a strong familiarity with the project.                                                                                                           | ✅ | ✅ | ✅ | ✅ | ❌    | ❌    | ❌    | ❌    |
| Collaborator                        | Contributor   | Subset of contributors granted write access to one or more of the project repositories upon selection by TSC                                                                          | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ❌    | ❌    |
| Technical Steering Committee Member | Collaborator  | A subset of collaborators having technical decision making authority and admin privileges                                                                                             | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ❌    |
| Project Steering Committee Member   | Stakeholders  | Sponsor organization representatives (i.e. those providing funding to the project) and key stakeholders with authority to guide project based on requirements, budget, schedule, etc. | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| Product Manager                     | Stakeholders  | Overall manager of project with final authority over all key decisions when consensus cannot be reached                                                                                    | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |

### 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])

### Technical Steering Committee Member

A subset of the collaborators forms the Technical Steering Committee (TSC). The TSC has authority over the following aspects of this project:

- Technical direction and guidance
- Committee governance and process 
- Contribution policy
- Conduct guidelines
- Maintaining the list of collaborators

#### TSC Committee Members
- [INSERT MEMBER NAME] ([username1]([INSERT LINK TO USERNAME]), [INSERT ORG ASSOCIATION]
- [INSERT MEMBER NAME] ([username1]([INSERT LINK TO USERNAME]), [INSERT ORG ASSOCIATION]


<details>

<summary>Emeriti</summary>

#### TSC Emeriti
- [INSERT MEMBER NAME] ([username1]([INSERT LINK TO USERNAME]), [INSERT ORG ASSOCIATION]

</details>
 
#### Scope

The TSC is primarily responsible for the following project repositories:

- [INSERT LINK TO PROJECT REPOSITORIES]

However, the TSC also has the responsibility to interface with and monitor third-party dependencies of the project for key changes impacting [INSERT PROJECT NAME]. These third-party dependencies include:

- [INSERT LINK TO DEPENDENT PROJECT REPOSITORIES]


#### Decision Making Process

Any community member can create an issue or comment asking the TSC to review something. Prior to implementing a substantial contribution, the design of that contribution should be reviewed by at least one member of the TSC. If consensus-seeking fails during the review of a pull request or in design discussions, the issue will be addressed by the TSC to make a determination on direction. TSC members will meet regularly and will keep track of decisions made when consensus was not met. 

The TSC can nominate new members at any time. Candidates for membership tend to be collaborators who have shown great dedication to the project and/or experts in a particular domain or project component. TSC members are expected to be active contributors or members who have made significant contributions within the past 12 months. 

### Project Management Committee (PMC) Member

The Project Management Committee (PMC) is made up of sponsor organization representatives (i.e. those providing funding to the project) and key stakeholders who rely or plan to rely on the project to meet a critical need. The PMC has the following responsibilities:

- Maintaining the overall project roadmap
- Determining project requirements and commitments to sponsors and stakeholders
- Assessing available resources and allocating them across the project
- Monitoring and reporting on progress against the roadmap 
- On-boarding new sponsors and stakeholders
- Overall project governance (including this policy)
- Addressing any legal considerations

#### PMC Committee Members
- [INSERT MEMBER NAME] ([username1]([INSERT LINK TO USERNAME]), [INSERT ORG ASSOCIATION]
- [INSERT MEMBER NAME] ([username1]([INSERT LINK TO USERNAME]), [INSERT ORG ASSOCIATION]

<details>

<summary>Emeriti</summary>

#### PMC Emeriti
- [INSERT MEMBER NAME] ([username1]([INSERT LINK TO USERNAME]), [INSERT ORG ASSOCIATION]

</details>   

#### Scope

The PMC has management authority over the same project repositories over which the TSC has technical authority over.   

#### Decision Making Process

The PMC will consist of a product manager and additional representative from sponsors and key stakeholders. The PMC or sponsoring organizations can nominate new members at any time. Care should be taken not to include too many members from a single stakeholder project or organization.

Regular stakeholder meetings are held to discuss current project status and propose changes to the project roadmap. If stakeholder representatives and sponsors concur with these proposals during the meeting, they will be immediately adopted. A member of the PMC will ensure the changes have been captured and recorded. Regular stakeholder meetings will be open to the entire community, but only members of the PMC have decision making authority. 

Additional meetings may be held if consensus is not met or to discuss significant changes to the roadmap due to changes in stakeholder priorities or available resources. Any decision made outside of stakeholder meetings must still be approved by all sponsors and stakeholders. If full consensus cannot be made, the product manager has the final authority to determine project direction. Any non-concurrences from stakeholders or sponsors will be noted. 

### Product Manager

Overall manager of the project with final authority over all key decisions when consensus cannot be reached within the TSC or PSC. The product manager is often chosen at the onset of project initiation and can be reassigned by the PMC (with institutional approval, if applicable).

# Acknowledgements

Much of this governance model was adapted from the other notable open source projects including [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/), and [OpenMCT](https://github.com/nasa/openmct/blob/master/CONTRIBUTING.md). We would like to thank those projects for setting the foundation upon which this model was built.
Resources
Community
More
Copyright © 2024 California Institute of Technology ("Caltech"). U.S. Government sponsorship acknowledged. Contents licensed under Apache License Version 2.0.
- + \ No newline at end of file diff --git a/docs/guides/governance/governance-model/governance-template-small-team/index.html b/docs/guides/governance/governance-model/governance-template-small-team/index.html index b0e7a5583..098936b9b 100644 --- a/docs/guides/governance/governance-model/governance-template-small-team/index.html +++ b/docs/guides/governance/governance-model/governance-template-small-team/index.html @@ -5,13 +5,13 @@ governance-template-small-team | SLIM - +

governance-template-small-team

# [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)

<details>
<summary>Emeriti</summary>
#### Committee Emeriti
- [INSERT MEMBER NAME] ([username1]([INSERT LINK TO USERNAME]), [INSERT ORG ASSOCIATION]
(Additional member listings)
</details>

#### 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)
Resources
Community
More
Copyright © 2024 California Institute of Technology ("Caltech"). U.S. Government sponsorship acknowledged. Contents licensed under Apache License Version 2.0.
- + \ No newline at end of file diff --git a/docs/guides/governance/governance-model/index.html b/docs/guides/governance/governance-model/index.html index f306c5165..2c5195d0c 100644 --- a/docs/guides/governance/governance-model/index.html +++ b/docs/guides/governance/governance-model/index.html @@ -5,13 +5,13 @@ Governance Model | SLIM - +

Governance Model

Establish a project guide for effective open source governance.

Introduction​

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.

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

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.
    • 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:

Acknowledgements:

This template was developed by evaluating best GOVERNANCE.md practices in the following organizations:

Feedback and Contributions​

We invite feedback and contributions to refine this guide. Visit our contribution guidelines.

Resources
Community
More
Copyright © 2024 California Institute of Technology ("Caltech"). U.S. Government sponsorship acknowledged. Contents licensed under Apache License Version 2.0.
- + \ No newline at end of file diff --git a/docs/guides/search/index.html b/docs/guides/search/index.html index 77d8ebe09..d6718e5b5 100644 --- a/docs/guides/search/index.html +++ b/docs/guides/search/index.html @@ -5,13 +5,13 @@ Guides | SLIM - +

Guides

Explore our guides via the categories below or the left-hand navigation. You may also search our guides.


Resources
Community
More
Copyright © 2024 California Institute of Technology ("Caltech"). U.S. Government sponsorship acknowledged. Contents licensed under Apache License Version 2.0.
- + \ No newline at end of file diff --git a/docs/guides/software-lifecycle/application-starter-kits/python-starter-kit/index.html b/docs/guides/software-lifecycle/application-starter-kits/python-starter-kit/index.html index c0cbe2770..1730f16e1 100644 --- a/docs/guides/software-lifecycle/application-starter-kits/python-starter-kit/index.html +++ b/docs/guides/software-lifecycle/application-starter-kits/python-starter-kit/index.html @@ -5,7 +5,7 @@ Python Starter Kit | SLIM - + @@ -15,7 +15,7 @@ Documentation requiring updates are marked with the keyword INSERT.

  • Apply Project Settings:

    • Update pyproject.toml to update build system dependencies
    • Update setup.cfg to specify build system configurations
      • Edit the metadata keywords to set appropriate keyword values 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, 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 (or refactoring on an existing repo).
        4. Update author, author_email, description and keywords to reflect your project details

  • 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
    • Clean and build and clean again after module builds successfully

      Information
      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.

  • Build on GitHub: A release kicks off a build and release process in GitHub Actions.

    • Additional Files​

    This starter kit produces several deliverables deployed for distribution:

    Frequently Asked Questions (FAQ)​

    • Q: What tooling is necessary to use the starter kit?

    • A: Python 3 version 3.9 or greater must be installed with a working package manager (pip). 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:

    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.

    Resources
    Community
    More
    Copyright © 2024 California Institute of Technology ("Caltech"). U.S. Government sponsorship acknowledged. Contents licensed under Apache License Version 2.0.
    - + \ No newline at end of file diff --git a/docs/guides/software-lifecycle/continuous-integration/continuous-integration-frameworks/index.html b/docs/guides/software-lifecycle/continuous-integration/continuous-integration-frameworks/index.html index 023f36a8e..e4d7bbd07 100644 --- a/docs/guides/software-lifecycle/continuous-integration/continuous-integration-frameworks/index.html +++ b/docs/guides/software-lifecycle/continuous-integration/continuous-integration-frameworks/index.html @@ -5,13 +5,13 @@ CI Tools and Frameworks | SLIM - +

    CI Tools and Frameworks

    Resources
    Community
    More
    Copyright © 2024 California Institute of Technology ("Caltech"). U.S. Government sponsorship acknowledged. Contents licensed under Apache License Version 2.0.
    - + \ No newline at end of file diff --git a/docs/guides/software-lifecycle/continuous-integration/index.html b/docs/guides/software-lifecycle/continuous-integration/index.html index 7b5c9b8ac..a1e10bfa6 100644 --- a/docs/guides/software-lifecycle/continuous-integration/index.html +++ b/docs/guides/software-lifecycle/continuous-integration/index.html @@ -5,13 +5,13 @@ Continuous Integration | SLIM - +

    Continuous Integration

    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

    Click the link above to explore various tools and systems for setting up and optimizing your CI pipeline.

    📔 CI Reference Architectures

    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 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 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:

    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 for more information.

    Resources
    Community
    More
    Copyright © 2024 California Institute of Technology ("Caltech"). U.S. Government sponsorship acknowledged. Contents licensed under Apache License Version 2.0.
    - + \ No newline at end of file diff --git a/docs/guides/software-lifecycle/continuous-integration/reference-architecture/index.html b/docs/guides/software-lifecycle/continuous-integration/reference-architecture/index.html index 678988128..aa187997b 100644 --- a/docs/guides/software-lifecycle/continuous-integration/reference-architecture/index.html +++ b/docs/guides/software-lifecycle/continuous-integration/reference-architecture/index.html @@ -5,7 +5,7 @@ CI Reference Architectures | SLIM - + @@ -95,7 +95,7 @@ mechanism to produce reliable software that is transparent and self-validating. This lends itself to tested, reproducible software deliveries with the crisp reliability and speed of automated systems.

    Resources
    Community
    More
    Copyright © 2024 California Institute of Technology ("Caltech"). U.S. Government sponsorship acknowledged. Contents licensed under Apache License Version 2.0.
    - + \ No newline at end of file diff --git a/docs/guides/software-lifecycle/continuous-testing/index.html b/docs/guides/software-lifecycle/continuous-testing/index.html index f8d88e62b..7a10ee346 100644 --- a/docs/guides/software-lifecycle/continuous-testing/index.html +++ b/docs/guides/software-lifecycle/continuous-testing/index.html @@ -5,13 +5,13 @@ Continuous Testing | SLIM - +
    Resources
    Community
    More
    Copyright © 2024 California Institute of Technology ("Caltech"). U.S. Government sponsorship acknowledged. Contents licensed under Apache License Version 2.0.
    - + \ No newline at end of file diff --git a/docs/guides/software-lifecycle/continuous-testing/testing-frameworks/index.html b/docs/guides/software-lifecycle/continuous-testing/testing-frameworks/index.html index 676fd614e..6995a2704 100644 --- a/docs/guides/software-lifecycle/continuous-testing/testing-frameworks/index.html +++ b/docs/guides/software-lifecycle/continuous-testing/testing-frameworks/index.html @@ -5,13 +5,13 @@ Testing Frameworks | SLIM - +

    Testing Frameworks

    Resources
    Community
    More
    Copyright © 2024 California Institute of Technology ("Caltech"). U.S. Government sponsorship acknowledged. Contents licensed under Apache License Version 2.0.
    - + \ No newline at end of file diff --git a/docs/guides/software-lifecycle/metrics/index.html b/docs/guides/software-lifecycle/metrics/index.html index 0ebe20976..d0433a29e 100644 --- a/docs/guides/software-lifecycle/metrics/index.html +++ b/docs/guides/software-lifecycle/metrics/index.html @@ -5,14 +5,14 @@ Metrics | SLIM - +

    Metrics

    A Guide for Configuring and Deploying Software Lifecycle Metrics Tracking.

    slim-dashboard Example Metrics Dashboard using Apache DevLake

    Introduction​

    Metrics collection is important for project management and software quality assurance. We recommend Apache DevLake for easy tracking and analysis. This guide simplifies its installation and configuration, especially for developers new to metrics collection.

    Use Cases:

    • Collecting and analyzing DORA metrics along with many others for your project.
    • Creating a visual dashboard to view metrics from multiple sources (e.g., GitHub, JIRA) in one place.
    • Streamlining the setup and configuration of Apache DevLake through a single-command setup step.
    • Gain insight into organizational and project performance for software development and the overall software lifecycle.

    Why We Chose Apache DevLake:

    Our decision to select Apache DevLake was informed by thorough trade study documentation, available here.

    Prerequisites​

    • Familiarity with Docker as well as a running instance of it
    • A familiarity with validated software metrics is not required for this tool but it is recommended

    Quick Start​

    To quickly deploy DevLake on one of your servers or locally for testing, we've developed a convenient 1-step command. Please ensure Docker is running on your system before executing this command.

    The purpose of this script is to automate the installation process DevLake recommends here. The script does the following:

    • Checks for necessary software: ensures you have Docker and docker-compose installed to run DevLake.
    • Downloads required files: automatically retrieves setup files if they're not already present on your system.
    • Prepares setup files: adjusts file permissions and sets up the necessary environment variables for DevLake.
    • Secures the setup: generates a unique encryption key for data security.
    • Starts DevLake: uses Docker to initialize the DevLake application in the background and guides you to visit a web address to start using DevLake for data analysis and viewing dashboards.

    Run This Command in Your Terminal and Then Move on to the Next Step of the Configuration Guide:

    cd /path/to/your/chosen/deployment/directory
    /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/NASA-AMMOS/slim/main/docs/guides/software-lifecycle/metrics/metrics-starter-kit/install_devlake.sh)"

    To Stop Services:

    1. Navigate to the directory containing your docker-compose.yml file (where you ran the above command).

    2. Run the following command to gracefully stop all containers defined in the docker-compose.yml file:

      docker-compose down

    To Restart Services:

    1. Navigate to the directory containing your docker-compose.yml file.

    2. Run the following command to start containers for services defined in the docker-compose.yml file:

      docker-compose up -d

      The -d flag runs containers in detached mode, allowing them to run in the background.

    Step-by-Step Configuration Guide​

    1. Run the Quick Start steps above.
    2. Once you have a working DevLake instance, we recommend going through DevLake's official start guide step-by-step, beginning with the data sources section.
    3. If you're interested in sharing your dashboards with your community but are unable to host a server, you can export your dashboards by following the instructions provided here.

    There are two additional topics we'd like to emphasize. Our recommendations for data sources and metrics to collect.

    We recommend, at a minimum, connecting the following data sources (see the DevLake docs on configuring data sources for further assistance):

    See this list of metrics on the DevLake documentation guide for why certain metrics are important and how to collect them. As a minium, we recommend the following metrics should be collected for your projects:

    • Change Failure Rate: "The percentage of changes that were made to a code that then resulted in incidents, rollbacks, or any type of production failure."
    • Lead Time for Changes: "The median amount of time for a code change to be deployed into production."

    Frequently Asked Questions (FAQ)​

    • Q: How do I customize the DevLake Quick Start script for more functionality?

    • A: If you have already provided DevLake with a data source, you can further configure your dashboard by following this guide. Use simple queries to gather the information you need.

    • Q: How do export the Grafana dashboard to a PDF?

    • A: You can use this tool.

    Credits​

    Authorship:

    Feedback and Contributions​

    We value your feedback and welcome contributions to improve this guide. Please see our contribution guidelines.

    Acknowledgements:

    • The NISAR and SWOT missions for their experience deploying and using DevLake.
    Resources
    Community
    More
    Copyright © 2024 California Institute of Technology ("Caltech"). U.S. Government sponsorship acknowledged. Contents licensed under Apache License Version 2.0.
    - + \ No newline at end of file diff --git a/docs/guides/software-lifecycle/security/github-security/index.html b/docs/guides/software-lifecycle/security/github-security/index.html index 5d53813b9..9c5cde543 100644 --- a/docs/guides/software-lifecycle/security/github-security/index.html +++ b/docs/guides/software-lifecycle/security/github-security/index.html @@ -5,13 +5,13 @@ GitHub Security Best Practices | SLIM - +

    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 for details. Organization administrative-level access is required.

    We recommend enabling the below features for all your repositories:

    img

    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:
            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".

    1. 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.

    2. 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:

    Acknowledgements:

    • GitHub for providing the security features and related documentation. See GitHub’s Security Features to access an overview of the suite of security features GitHub provides for repositories.
    • OWASP DevSecOps Guideline 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.

    Resources
    Community
    More
    Copyright © 2024 California Institute of Technology ("Caltech"). U.S. Government sponsorship acknowledged. Contents licensed under Apache License Version 2.0.
    - + \ No newline at end of file diff --git a/docs/guides/software-lifecycle/security/secrets-detection/index.html b/docs/guides/software-lifecycle/security/secrets-detection/index.html index 5c7c23eb8..67526637f 100644 --- a/docs/guides/software-lifecycle/security/secrets-detection/index.html +++ b/docs/guides/software-lifecycle/security/secrets-detection/index.html @@ -3,23 +3,15 @@ -Secrets Detection | SLIM +Secrets Detection | SLIM - +
    -

    Secrets Detection

    We recommend 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.

    detect-secrets-wordcloud

    Our application of detect-secrets embraces a tri-layered approach, bolstered by customized plugins (full list of plugins available here), 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.

    Note: Below three layers, are running on experimental version slim-detect-secrets which supports additional secret detection plugins.

    They are:

    • AWS sensitive information
    • Public IP Address
    • Absolute Path
    • Email Address

    Link to their implementation and test suites

    It is being tested by both NASA-AMMOS/slim team and 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.

    Starter Kit:

    1. Install experimental version of slim-detect-secrets
    pip install git+https://github.com/NASA-AMMOS/slim-detect-secrets.git@exp
    1. Scan all local files from current directory and output the result as a baseline file
    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.

    1. Check result in the baseline file
    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,

    "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.

    1. Analyze results by audit tool
    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,

    It also provides other ways to present the result. For more information, please refer to Auditing Secrets in Baseline

    Note if you have marked any detected secrets as true positives, its best to first remove all references to those secrets in your code and then rerun a full scan to generate a fresh audit report that you can compare against to ensure you only have false-positives (white-listed secrets) in your .secrets.baseline - this is especially important for Layer 2.

    Layer 2: Git Commit Scan (Client-side)​

    The second layer is a pre-commit hook implemented in the local environment. This hook utilizes a .pre-commit-config.yaml file to config the pre-commit hook. The hook is triggered when the developer attempts to commit changes. The hook will scan the changes and compare them to the baseline file generated in the first layer. If any new secrets are detected, the hook will prevent the commit and report the detected secrets to the developer.

    Starter Kit:

    1. Install pre-commit
    pip install pre-commit

    This tool is used to install pre-commit hook in your local git repository.

    1. Create .pre-commit-config.yaml file in root directory of your project with the following contents
    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.*'

    This file is used to config the pre-commit hook. In this example, we use the experimental version of slim-detect-secrets tool. The --baseline argument is used to specify the baseline file generated in the first layer. The --exclude-files argument is used to exclude the .git directory and .secrets baseline files from scanning to reduce false positives. Make modifications when necessary.

    1. Install pre-commit hook
    pre-commit install

    This command reads the .pre-commit-config.yaml file and installs the pre-commit hook in your local git repository. -After this, you can see a .git/hooks/pre-commit file is created in your local git repository.

    1. Add the baseline file .secrets.baseline in your local Git repository under the following conditions only:
      1. You wish to share white-listed secrets with other team members
      2. You've removed any references in your code to sensitive secrets detected that are not white-listed, i.e. find and modify code referenced in you .secrets.baseline with flag is_secret: true
      3. You've re-run a fresh detect-secrets scan followed by a detect-secrets audit and your .secrets.baseline ONLY now contains white-listed entries, i.e. is_secret: false

    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!

    1. 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,

    Screen Shot 2023-04-20 at 7 32 10 AM

    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, 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. 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.

    Starter Kit:

    1. Create a workflow file detect-secrets.yaml in .github/workflows directory from your repository root.
    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

    • Print a message in the "Details" with instructions on how to resolve the issue

    • Send an email notification to the user

    1. Protect your branch

    After this, if status check fails, GitHub will prevent the merge or push to the protected branch.

    Attention for using Detect Secrets​

    1.It does not show all the same type of secrets in a same file to minimize noise

    This means sometimes it will only show one secret in a file even if there are multiple same type of secrets in the same file. -Audit tool will not show all the secrets due to this reason.

    -> Thus, when you see a secret is detected, best practice is to manually check that file.

    2.Even though detect-secrets has strong secret-detect ability compared to other tools, it is still possible that detect-secrets will not show you a file that contains secrets due to a new type of secret not capable by current plugins.

    -> Thus, the best practice is always to be careful as a developer and manually check the files that you think might contain secrets.

    Note: detect-secrets is a backup approach to minimize the chance of pushing secrets to the cloud.

    1. At least use layer 3 (Server-side push to GitHub.com) to protect the main branch from being pushed or merged if any secrets are detected.
    2. If any secrets are detected during layer 3, you can:
    3. Recommend to set up layer 2 (Git commit scan, client-side) for every developer
      • It can minimize the chance of pushing secrets to the cloud
      • Local files are easier to clean than GitHub commit history
    4. Layer 1 (Full scan and audit, client-side) can be involved during each stage
      • It helps you generate, update or analyze baseline file for layer 2 and 3

    More Configurations​

    Check out

    1. detect-secrets
    2. pre-commit
    Resources
    Community
    More
    Copyright © 2024 California Institute of Technology ("Caltech"). U.S. Government sponsorship acknowledged. Contents licensed under Apache License Version 2.0.
    - +

    Secrets Detection

    Guide to identify and automatically prevent leaking of sensitive information into your codebase.

    Introduction​

    Background: Sensitive information like API keys, passwords or tokens may be inadvertently committed to your repository. Such slip-ups can pose significant security risks. We recommend not only recurring scans for sensitive information, but proactively preventing sensitive information from getting infused. To support these goals, we recommend a tool called detect-secrets that mitigates these risks. It scans for common sensitive information categories like passwords and other high-entropy values that contain sensitive data. It also provides a plugin system to support additional customization. It's fast for use in continuous integration pipelines and quickly executes on local-developer machines. It uses a "baseline file" approach, leveraging .secrets.baseline, that streamlines management of legitimate secrets and reduces false positives. This helps both new and established projects detect and prevent secrets from entering the code base.

    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 3 with the pip tool installed.
    • (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 by the detect-secrets team for merge into the tool's main codebase. Until then we recommend using our SLIM fork as described below. 

      pip install git+https://github.com/NASA-AMMOS/slim-detect-secrets.git@exp

    2. Execute a baseline scan:

      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:

      detect-secrets audit .secrets.baseline

    Additional steps like whitelisting accepted values and false positives, establishing pre-commit hooks and/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 comprehensive security. Please see below sections for further details.

    Table of Contents​

    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.
        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.
        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.
        cat .secrets.baseline

    4. Analysis

      • Analyze results using the audit tool.
        detect-secrets audit .secrets.baseline

    View more on 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, 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

    2. Configuration

      • Create a .pre-commit-config.yaml configuration file with the below contents.

          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.

        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​

    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 tool and GitHub Action. The scan is triggered during a push or pull request and any detected new secrets are reported while blocking merges or pushes to protected branches.

    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. For example (from the Slim Python Starter Kit):
    name: "Secret Detection"
    on:
      push:
        branches: [main, develop]
      pull_request:
        # The branches below must be a subset of the branches above
        branches: [develop]

    jobs:
      secret-detection:
        name: Secret-Detection
        runs-on: ubuntu-latest
        permissions:
          actions: write
          contents: read
          security-events: write
        steps:
        - name: Checkout repository
          uses: actions/checkout@v4
          with:
            fetch-depth: 0
        - name: Upgrade tooling
          run: |
            python3 -m pip install --upgrade pip
            pip install --upgrade git+https://github.com/NASA-AMMOS/slim-detect-secrets.git@exp
            pip install --upgrade jq
        - name: Create baseline config
          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
          run: |
            # scripts scan repository for new secrets
            # backup list of known secrets
            cp -pr .secrets.baseline .secrets.new
            # find secrets in the repository
            detect-secrets scan --disable-plugin AbsolutePathDetectorExperimental --baseline .secrets.new \
                --exclude-files '\.secrets..*' \
                --exclude-files '\.git.*' \
                --exclude-files '\.mypy_cache' \
                --exclude-files '\.pytest_cache' \
                --exclude-files '\.tox' \
                --exclude-files '\.venv' \
                --exclude-files 'venv' \
                --exclude-files 'dist' \
                --exclude-files 'build' \
                --exclude-files '.*\.egg-info'
            # break build when new secrets discovered
            # function compares baseline/new secrets w/o listing results -- success(0) when new secret found
            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) | grep -q '>' ; }
            # test baseline versus new secret files
            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 "🟢 Secrets tests PASSED! 🟢" >&1
                echo "No new secrets were detected in comparison to any baseline configurations."  >&1
                exit 0
            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 specific lines of code that may contain sensitive information are not disclosed publicly. In GitHub Action logs only a yes/no indication of sensitive information appears. However, the surface area exists for potential attackers to readily identify sensitive information. Monitor your pull requests actively to respond and always ensure your team actively uses Layer 1 and Layer 2 to mitigate 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.
      • 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: How are commits containing secrets removed permanently from Git history?

      A: The process of scrubbing errant commits and their content involves a destructive rewrite of repository commit history. Backups are essential and changes must be handled with precision and caution. One solution is to start a new repository from scratch with only the latest cleaned code, thereby negating the need to change existing repository content. Solutions involving more entropy include Git filter commands or well-known cleaning applications, such as BFG Repo-Cleaner. Because of the risks involved in mutating repository history and content, such changes always must be handled with backups, expertise and extreme care.

    • Q: Where can I find more configurations and options for detect-secrets?

      A: Refer to the official documentation for detect-secrets and pre-commit.

    Credits​

    Authorship:

    Acknowledgements:

    Feedback and Contributions​

    We value your feedback and contributions. Enhance and expand this guide by referring to our contribution guidelines.

    Resources
    Community
    More
    Copyright © 2024 California Institute of Technology ("Caltech"). U.S. Government sponsorship acknowledged. Contents licensed under Apache License Version 2.0.
    + \ No newline at end of file diff --git a/index.html b/index.html index b23734b38..bb2c1227f 100644 --- a/index.html +++ b/index.html @@ -5,13 +5,13 @@ Home | SLIM - +

    A community-resource for exchanging and implementing best practices in software lifecycle improvements.

    See our Best Practice Guides
    Submit a Best Practice Guide

    Our Scope

    We focus on best practices related to software project governance, documentation, and development life-cycles.

    Community Based

    We solicit improvement ideas and solutions from our community deliver best practices back to our members. See our community planning board.

    Open Source

    We develop best practices through standards-as-code. We iteratively improve our recommendations through the open source tickets and pull requests.

    Resources
    Community
    More
    Copyright © 2024 California Institute of Technology ("Caltech"). U.S. Government sponsorship acknowledged. Contents licensed under Apache License Version 2.0.
    - + \ No newline at end of file diff --git a/markdown-page/index.html b/markdown-page/index.html index f3dfc79af..828d2c348 100644 --- a/markdown-page/index.html +++ b/markdown-page/index.html @@ -5,13 +5,13 @@ Markdown page example | SLIM - +

    Markdown page example

    You don't need React to write simple standalone pages.

    Resources
    Community
    More
    Copyright © 2024 California Institute of Technology ("Caltech"). U.S. Government sponsorship acknowledged. Contents licensed under Apache License Version 2.0.
    - + \ No newline at end of file