diff --git a/docs/guides/checklist.md b/docs/guides/checklist.md new file mode 100644 index 000000000..6f5015dde --- /dev/null +++ b/docs/guides/checklist.md @@ -0,0 +1,95 @@ +--- +sidebar_position: 2 +--- + +# ✅ Getting Started + +We have numerous guides and recommendations on this website. You are free to explore and take what you find most helpful. However, if you're looking for more guidance on how to bring together SLIM's recommendations for your project in an aggregated form, you've come to the right place. + +## Checklist + +Here we present a checklist you can run through for your project, as well as links to automation / guides to make your project ready with the best of SLIM. + +Review your project's repositories, and ensure all have the following (in prioritized order): + +| Checklist Item | Why? | Done? | +| -------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- | ----- | +| LICENSE | Spell out legal terms for software usage & modification | ✅ or ❌ | +| [README](documentation/readme/) | Provide project overview, setup, & usage instructions | ✅ or ❌ | +| [Contributing Guide](governance/contributions/contributing-guide) | Outline how to contribute & the process for submissions | ✅ or ❌ | +| [Code of Conduct](governance/contributions/code-of-conduct) | Establish community behavior standards | ✅ or ❌ | +| [Issue Templates](governance/contributions/issue-templates/) | Streamline issue reporting for consistency & clarity | ✅ or ❌ | +| [Pull Request Templates](governance/contributions/pull-requests/) | Ensure PRs are comprehensive & adhere to project standards | ✅ or ❌ | +| [Documentation](documentation/documentation-hosts/) | Offer detailed info on features, APIs, & customizations not covered in README | ✅ or ❌ | +| [Change Log](documentation/change-log/) | Keep track of all notable changes in each version in a human-readable format | ✅ or ❌ | +| [Security & Dependency Scanning](software-lifecycle/security/github-security) | Identify vulnerabilities & outdated dependencies for security | ✅ or ❌ | +| [Sensitive Information Scanning](software-lifecycle/security/secrets-detection/) | Detect accidental commits of sensitive info | ✅ or ❌ | +| [Governance Model](governance/governance-model/) | Define decision-making structure & project leadership for transparency & organization | ✅ or ❌ | + + +## Repository Starter Kit + +If you're starting a new project / repository, you can automatically get many of the above setup quickly using our: + +**🌐 [Repository Starter Kit](https://github.com/nasa-ammos/slim-starterkit)** + +### Using GitHub's "Use this template" Button + +1. **Navigate to the Starter Kit**: Go to the [SLIM Repository Starter Kit](https://github.com/nasa-ammos/slim-starterkit) on GitHub. +2. **Create Your Repository**: Click the "Use this template" button at the top right of the GitHub repository page. + ![GitHub Use Template Button](/img/gh-use-template.png) + Example screenshot of button to click. +3. **Set Up Your New Repository**: Fill in the Repository name and description for your new project. Decide whether your repository will be public or private. Click "Create repository from template". +4. **Customize Your Repository**: After creation, go through your new repository and look for files containing the `[INSERT ...]` text. These are placeholders for you to replace with information specific to your project. This includes project name, description, contributing guidelines, etc. +5. **Push Changes**: Once you've made your customizations, commit and push the changes to your repository to ensure all your project information is up to date. + +### Manually Cloning and Using the Repository + +If you prefer to set up your project manually or need more control over the initial setup, follow these steps: + +1. **Clone the Starter Kit**: + - Open your terminal or command prompt. + - Navigate to the directory where you want your project to be. + - Clone the repository using: + ```bash + git clone https://github.com/nasa-ammos/slim-starterkit.git YOUR_PROJECT_NAME + ``` + - Replace `YOUR_PROJECT_NAME` with the desired name of your project folder. + +2. **Navigate to Your Project Directory**: + ```bash + cd YOUR_PROJECT_NAME + ``` + +3. **Remove the Git History** and start fresh: + ```bash + rm -rf .git + git init + ``` + +4. **Customize Your Project**: Go through the cloned files and modify any `[INSERT ...]` placeholders with information relevant to your project. This step is crucial for tailoring the starter kit to your specific project needs. + +5. **Initial Commit**: + - Add all the files to your new git repository: + ```bash + git add . + ``` + - Commit the changes: + ```bash + git commit -m "Initial commit with SLIM Repository Starter Kit" + ``` + +6. **Create a New Repository on GitHub** (or your preferred Git hosting service) without initializing it with a README, .gitignore, or license since your project already contains these files. + +7. **Link Your Local Repository to GitHub**: + - Follow the instructions provided by GitHub to push an existing repository from the command line, which will include: + ```bash + git remote add origin + git branch -M main + git push -u origin main + ``` + +8. **Push Your Changes**: Ensure all your customizations and initial setup are pushed to your remote repository. + +By following these steps, you'll have a new project set up with best practices in repository setup, including a LICENSE, README, contributing guide, and more. Remember to keep your project information up to date and regularly review the repository for any updates to the starter kit that might be beneficial to your project. + diff --git a/docs/guides/documentation/_category_.json b/docs/guides/documentation/_category_.json index 36f5bf161..d9d45203d 100644 --- a/docs/guides/documentation/_category_.json +++ b/docs/guides/documentation/_category_.json @@ -1,8 +1,8 @@ { - "label": "Documentation", - "position": 3, + "label": "💬 Information Sharing", + "position": 5, "link": { "type": "generated-index", - "description": "Check out our below list of guides and sub-sections related to documentation best practices." + "description": "Check out our below list of guides and sub-sections related to information sharing best practices." } } diff --git a/docs/guides/governance/_category_.json b/docs/guides/governance/_category_.json index ca74086d7..5f78a4912 100644 --- a/docs/guides/governance/_category_.json +++ b/docs/guides/governance/_category_.json @@ -1,6 +1,6 @@ { - "label": "Governance", - "position": 2, + "label": "🏛 Governance", + "position": 4, "link": { "type": "generated-index", "description": "Check out our below list of guides and sub-sections related to governance best practices." diff --git a/docs/guides/governance/contributions/contributing-guide/README.md b/docs/guides/governance/contributions/contributing-guide/README.md index a86e456ca..4db3cfb47 100644 --- a/docs/guides/governance/contributions/contributing-guide/README.md +++ b/docs/guides/governance/contributions/contributing-guide/README.md @@ -22,7 +22,7 @@ ## Quick Start -**[⬇️ Contributing Guide Template](CONTRIBUTING)** +**[⬇️ Contributing Guide Template](CONTRIBUTING.md)** Download our customizable template to create a contributing guide for your project. @@ -42,7 +42,7 @@ Download our customizable template to create a contributing guide for your proje - etc. -2. **Customize the Template**: Modify the [Contributing Guide Template](CONTRIBUTING) to fit your project's specifics. +2. **Customize the Template**: Modify the [Contributing Guide Template](CONTRIBUTING.md) to fit your project's specifics. - Copy the template and create a `CONTRIBUTING.md` file at the root level of your repository. - Replace `[INSERT ...]` placeholders with your project's details. These markers are used throughout to designate customization options. 3. **Integrate with Project**: diff --git a/docs/guides/governance/contributions/pull-requests/README.md b/docs/guides/governance/contributions/pull-requests/README.md index baafc1424..7b8267e77 100644 --- a/docs/guides/governance/contributions/pull-requests/README.md +++ b/docs/guides/governance/contributions/pull-requests/README.md @@ -21,7 +21,7 @@ ## Quick Start -**[⬇️ Pull Request Template](PULL_REQUEST_TEMPLATE)** +**[⬇️ Pull Request Template](PULL_REQUEST_TEMPLATE.md)** Our recommended pull request template for projects. @@ -33,7 +33,7 @@ Recommendations from GitHub.com on how-to facilitate the use of pull request tem ## Step-by-Step Guide -1. **Team Discussion**: Discuss the benefits of a pull request template with your team. Gain consensus on adopting this approach for consistency in contributions. Below is an explanation of our recommended [Pull Request Template](PULL_REQUEST_TEMPLATE) file's fields. Adjust as necessary. +1. **Team Discussion**: Discuss the benefits of a pull request template with your team. Gain consensus on adopting this approach for consistency in contributions. Below is an explanation of our recommended [Pull Request Template](PULL_REQUEST_TEMPLATE.md) file's fields. Adjust as necessary. - ***Purpose***: To clearly state the intention behind the pull request. This helps reviewers understand the context and significance of your changes. - ***Proposed Changes***: - `[ADD]` for new features or content the contributor introduced. @@ -47,7 +47,7 @@ Recommendations from GitHub.com on how-to facilitate the use of pull request tem - In your GitHub repository, create a `.github/` folder to hold community health files. 3. **Add Pull Request Template**: - - Copy the [Pull Request Template](PULL_REQUEST_TEMPLATE) into `.github/PULL_REQUEST_TEMPLATE`. + - Copy the [Pull Request Template](PULL_REQUEST_TEMPLATE.md) into `.github/PULL_REQUEST_TEMPLATE`. - Commit and push this file to the `main` branch of your repository. 4. **Usage**: diff --git a/docs/guides/search.md b/docs/guides/search.md index db93ae7b8..a667401da 100644 --- a/docs/guides/search.md +++ b/docs/guides/search.md @@ -8,15 +8,15 @@ import { Card, Button } from 'react-bootstrap'; import 'bootstrap/dist/css/bootstrap.min.css'; import { Link } from 'react-router-dom'; -# Guides +# 🔍 Explore Our Guides Explore our guides via the categories below or the left-hand navigation. You may also search our guides. -
+
- Software Lifecycle + Software Lifecycle Software Lifecycle Covers the entire process of software development, continuous pipelines, application kits, testing, and security. @@ -28,7 +28,7 @@ Explore our guides via the categories below or the left-hand navigation. You may - Governance + Governance Governance Dedicated to establishing robust governance frameworks, with standards for contributions and governance models. @@ -40,8 +40,8 @@ Explore our guides via the categories below or the left-hand navigation. You may - Documentation - Documentation + Documentation + Information Sharing Focuses on creating effective project documentation, including Change Logs, Documentation Hosts, and README templates. @@ -50,6 +50,20 @@ Explore our guides via the categories below or the left-hand navigation. You may
+
+ + + + Getting Started + + Not sure where to begin? Start here with our checklist. + + + + +
+ +

## Search diff --git a/docs/guides/software-lifecycle/_category_.json b/docs/guides/software-lifecycle/_category_.json index e7eef0295..a2ebe5162 100644 --- a/docs/guides/software-lifecycle/_category_.json +++ b/docs/guides/software-lifecycle/_category_.json @@ -1,6 +1,6 @@ { - "label": "Software Lifecycle", - "position": 1, + "label": "🔄 Software Lifecycle", + "position": 3, "link": { "type": "generated-index", "description": "Check out our below list of guides and sub-sections related to software lifecycle best practices." diff --git a/static/data/slim-registry.json b/static/data/slim-registry.json index 6ec02dc1d..3c1e109ea 100644 --- a/static/data/slim-registry.json +++ b/static/data/slim-registry.json @@ -73,7 +73,7 @@ }, { "title": "Pull Requests", - "uri": "/slim/docs/guides/governance/contributions/change-request-templates", + "uri": "/slim/docs/guides/governance/contributions/pull-requests", "category": "governance", "description": "A guide outlining how to implement a pre-filled pull request template to provide guidance to potential contributors on GitHub.", "tags": [ diff --git a/static/img/gh-use-template.png b/static/img/gh-use-template.png new file mode 100644 index 000000000..b0d16e1fb Binary files /dev/null and b/static/img/gh-use-template.png differ