diff --git a/.gitignore b/.gitignore index 961496ae5..52446e01a 100644 --- a/.gitignore +++ b/.gitignore @@ -5,3 +5,4 @@ **/node_modules **/package-lock.json /build/** +.DS_Store \ No newline at end of file diff --git a/docs/contribute/submit-best-practice.md b/docs/contribute/submit-best-practice.md index 94fcd1c1e..07f7d6426 100644 --- a/docs/contribute/submit-best-practice.md +++ b/docs/contribute/submit-best-practice.md @@ -159,3 +159,43 @@ To document metadata about your best practice and have your best practice show u ``` 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 initiated a draft pull request or issue, 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. + +To request feedback, you can use the following platforms: + +- **Slack**: Post a message in the relevant SLIM Slack channels (e.g. #slim, #mightydevs). 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. + + ```plaintext + Hello @channel, + + I am seeking feedback on my recent contribution to the SLIM project, titled [INSERT YOUR CONTRIBUTION TITLE]. The contribution is aimed at [INSERT BRIEF DESCRIPTION OF THE PURPOSE]. + + Your insights and suggestions would be super valuable to ensure the contribution effectively addresses our project goals. You can find the details here: [Link to Pull Request/Issue]. + + Thank you in advance for your support and feedback! + + Best, + [Your Name] + ``` + +- **E-mail**: Send an email to the SLIM community mailing list, using a similar template as above. + +- **GitHub Comment**: Within your issue ticket or pull request, include a comment tagging the "@slim-community" team to directly notify them. + +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. diff --git a/docs/guides/software-lifecycle/metrics/README.md b/docs/guides/software-lifecycle/metrics/README.md new file mode 100644 index 000000000..743f11ef3 --- /dev/null +++ b/docs/guides/software-lifecycle/metrics/README.md @@ -0,0 +1,123 @@ +# Metrics + +
A Guide for Configuring and Deploying Software Lifecycle Metrics Tracking.
+ +![slim-dashboard](../../../../static/img/slim-dashboard-devlake.png) +*Example Metrics Dashboard using Apache DevLake* + +## Introduction + +Metrics collection is important for project management and software quality assurance. We recommend [Apache DevLake](https://devlake.apache.org/) 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](https://devlake.apache.org/docs/DORA/) 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](https://github.com/NASA-AMMOS/slim/issues/117#issuecomment-1802302091). + +--- + +## Prerequisites + +- Familiarity with [Docker](https://docs.docker.com/engine/install/) 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](https://devlake.apache.org/docs/GettingStarted/DockerComposeSetup). 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](#step-by-step-configuration-guide):** + +```bash +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: + + ```bash + 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: + + ```bash + 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](#quick-start)** steps above. +2. Once you have a working DevLake instance, we recommend going through DevLake's [official start guide](https://devlake.apache.org/docs/Overview/Introduction/#2-configuring-data-source) 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](https://grafana.com/docs/grafana/latest/dashboards/create-reports/). + +There are two additional topics we'd like to emphasize. Our recommendations for data sources and metrics to collect. + +### Recommended Data Sources + +We recommend, at a minimum, connecting the following data sources (see the DevLake docs on [configuring data sources](https://devlake.apache.org/docs/Overview/Introduction#2-configuring-data-source) for further assistance): + +- [GitHub](https://devlake.apache.org/docs/v0.20/Configuration/GitHub) + +### Recommended Metrics to Collect + +See [this list](https://devlake.apache.org/docs/Metrics) 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](https://devlake.apache.org/docs/Metrics/CFR): *"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](https://devlake.apache.org/docs/Metrics/LeadTimeForChanges): *"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](https://devlake.apache.org/docs/Configuration/Dashboards/GrafanaUserGuide). Use simple queries to gather the information you need. + +- **Q:** How do export the Grafana dashboard to a PDF? +- **A:** You can use [this](https://github.com/IzakMarais/reporter) tool. + +--- + +## Credits + +**Authorship**: + +- Dillon Dalton [ddalton-jpl](https://github.com/ddalton-jpl) +- Rishi Verma [riverma](https://github.com/riverma) + +--- + +## Feedback and Contributions + +We value your feedback and welcome contributions to improve this guide. Please see our [contribution guidelines](https://link-to-contribution-guidelines). + +--- + +**Acknowledgements**: + +- The [NISAR](https://nisar.jpl.nasa.gov/) and [SWOT](https://swot.jpl.nasa.gov/) missions for their experience deploying and using DevLake. diff --git a/docs/guides/software-lifecycle/metrics/metrics-starter-kit/install_devlake.sh b/docs/guides/software-lifecycle/metrics/metrics-starter-kit/install_devlake.sh new file mode 100755 index 000000000..dfc26a86f --- /dev/null +++ b/docs/guides/software-lifecycle/metrics/metrics-starter-kit/install_devlake.sh @@ -0,0 +1,61 @@ +#!/bin/bash + +############################################################################### +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# http://www.apache.org/licenses/LICENSE-2.0 +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +############################################################################### + +echo "=== Apache DevLake Installation ===" + +echo "Step 1: Prerequisites" +echo "Make sure you have Docker v19.03.10+ and docker-compose v2.2.3+ installed." +echo "If you have Docker Desktop installed, docker-compose is already included." + +CURR_DEV_LAKE_VERSION="v0.20.0-beta4" +DOCKER_COMPOSE_URL="https://github.com/apache/incubator-devlake/releases/download/${CURR_DEV_LAKE_VERSION}/docker-compose.yml" +ENV_EXAMPLE_URL="https://github.com/apache/incubator-devlake/releases/download/${CURR_DEV_LAKE_VERSION}/env.example" + +# Check if docker-compose.yml and env.example already exist +if [ ! -e docker-compose.yml ] && [ ! -e env.example ]; then + echo "Step 2. Downloading docker-compose.yml and env.example" + wget $DOCKER_COMPOSE_URL + wget $ENV_EXAMPLE_URL + + chmod 660 docker-compose.yml + chmod 660 env.example + + echo "Step 3. Renaming env.example to .env..." + mv env.example .env +else + echo "Existing docker-compose.yml and env.example found. Skipping download." +fi + +echo "Step 4. Generating encryption key..." +encryption_key=$(openssl rand -base64 2000 | tr -dc 'A-Z' | fold -w 128 | head -n 1) + +# Check if .env file exists +if [ -e .env ]; then + existing_content=$(cat .env) + printf "%s\nENCRYPTION_SECRET=\"%s\"\n" "$existing_content" "$encryption_key" >.env +else + printf "ENCRYPTION_SECRET=\"%s\"\n" "$encryption_key" >.env + chmod 660 .env +fi + +# Step 5: Run Docker Compose to launch DevLake +echo "Step 5: Launching DevLake with Docker Compose" +docker-compose down +docker-compose up -d + +# Step 6: Collect data and view dashboards +echo "Step 6: Collect data and view dashboards" + +echo "Visit http://localhost:4000 in your browser to configure DevLake and collect data." +echo "=== Installation Completed ===" diff --git a/static/data/slim-registry.json b/static/data/slim-registry.json index da5b0187a..6ec02dc1d 100644 --- a/static/data/slim-registry.json +++ b/static/data/slim-registry.json @@ -1,169 +1,180 @@ [ - { - "title": "GOVERNANCE.md", - "uri": "/slim/docs/guides/governance/governance-model", - "category": "governance", - "description": "A governance model template seeking to generalize how most government-sponsored open source projects can expect to operate in the open source arena.", - "tags": [ - "governance", - "templates", - "repository-setup", - "github" - ] - }, - { - "title": "Secrets Detection", - "uri": "/slim/docs/guides/software-lifecycle/security/secrets-detection", - "category": "software lifecycle", - "description": "Detect-secrets is a security tool that scans code repositories to identify and prevent the accidental inclusion of sensitive information, such as API keys or passwords, by utilizing various detection techniques.", - "tags": [ - "software-lifecycle", - "security", - "testing", - "tools" - ] - }, - { - "title": "README.md", - "uri": "/slim/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", - "templates", - "github" - ] - }, - { - "title": "Issue Ticket Templates", - "uri": "/slim/docs/guides/governance/contributions/issue-templates/", - "category": "documentation", - "description": "Issue tickets templates helping development teams keep the language of bug, feature, and other types of issues readable and consistent.", - "tags": [ - "documentation", - "templates", - "repository-setup", - "github" - ] - }, - { - "title": "Change Log", - "uri": "/slim/docs/guides/documentation/change-log/", - "category": "documentation", - "description": "A guide on creating and maintaining a human-readable change log for software development projects, emphasizing the importance of a `CHANGELOG.md` file.", - "tags": [ - "documentation", - "versioning", - "templates", - "repository-setup", - "github" - ] - }, - { - "title": "Documentation Hosts", - "uri": "/slim/docs/guides/documentation/documentation-hosts/trade-study-hostingdocs-user", - "category": "documentation", - "description": "A guide on possible use cases and recommended tools for hosting various types of documentation with a call for contributions.", - "tags": [ - "documentation", - "trade-studies", - "tools" - ] - }, - { - "title": "Pull Requests", - "uri": "/slim/docs/guides/governance/contributions/change-request-templates", - "category": "governance", - "description": "A guide outlining how to implement a pre-filled pull request template to provide guidance to potential contributors on GitHub.", - "tags": [ - "github", - "templates", - "governance", - "repository-setup" - ] - }, - { - "title": "Code of Conduct", - "uri": "/slim/docs/guides/governance/contributions/code-of-conduct", - "category": "governance", - "description": "A guide on how to create and implement a code of conduct for project teams, with a specific recommendation to use the Contributor Covenant.", - "tags": [ - "governance", - "repository-setup", - "github", - "templates" - ] - }, - { - "title": "Contributing Guide", - "uri": "/slim/docs/guides/governance/contributions/contributing-guide", - "category": "governance", - "description": "A detailed guide about creating a contributing guide for your project, featuring a customizable template and instructions on how to use it.", - "tags": [ - "templates", - "governance", - "repository-setup", - "github", - "templates" - ] - }, - { - "title": "Python Starter Kit", - "uri": "/slim/docs/guides/software-lifecycle/application-starter-kits/python-starter-kit", - "category": "software-lifecycle", - "description": "A guide to a complete, deployment-ready Python 3 application that's bundled into a reusable template repository for quick implementation, with integrated build, release, and publish on GitHub.", - "tags": [ - "python", - "templates", - "repository-setup", - "continuous-integration", - "github" - ] - }, - { - "title": "Continuous Integration Frameworks", - "uri": "/slim/docs/guides/software-lifecycle/continuous-integration/continuous-integration-frameworks", - "category": "software lifecycle", - "description": "An overview of different continuous integration frameworks and their use cases.", - "tags": [ - "tools", - "continuous-integration", - "trade-studies" - ] - }, - { - "title": "Reference Architectures", - "uri": "/slim/docs/guides/software-lifecycle/continuous-integration/reference-architecture", - "category": "software lifecycle", - "description": "A high-level reference guide for the implementation of continuous integration best practices, detailing structure, component interrelationships, and processes.", - "tags": [ - "continuous-integration", - "testing", - "versioning", - "devops" - ] - }, - { - "title": "Continuous Testing", - "uri": "/slim/docs/guides/software-lifecycle/continuous-testing/", - "category": "software lifecycle", - "description": "An extensive list of resources and tools for continuous testing including module testing, service endpoint testing, performance testing, and mobile testing among others.", - "tags": [ - "testing", - "tools" - ] - }, - { - "title": "GitHub Security Best Practices", - "uri": "/slim/docs/guides/software-lifecycle/security/github-security", - "category": "software lifecycle", - "description": "Recommendations for enabling GitHub security features for repositories, including using GitHub native tools like CodeQL, code scanning and more.", - "tags": [ - "software-lifecycle", - "security", - "testing", - "tools" - ] - } -] + { + "title": "GOVERNANCE.md", + "uri": "/slim/docs/guides/governance/governance-model", + "category": "governance", + "description": "A governance model template seeking to generalize how most government-sponsored open source projects can expect to operate in the open source arena.", + "tags": [ + "governance", + "templates", + "repository-setup", + "github" + ] + }, + { + "title": "Secrets Detection", + "uri": "/slim/docs/guides/software-lifecycle/security/secrets-detection", + "category": "software lifecycle", + "description": "Detect-secrets is a security tool that scans code repositories to identify and prevent the accidental inclusion of sensitive information, such as API keys or passwords, by utilizing various detection techniques.", + "tags": [ + "software-lifecycle", + "security", + "testing", + "tools" + ] + }, + { + "title": "README.md", + "uri": "/slim/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", + "templates", + "github" + ] + }, + { + "title": "Issue Ticket Templates", + "uri": "/slim/docs/guides/governance/contributions/issue-templates/", + "category": "documentation", + "description": "Issue tickets templates helping development teams keep the language of bug, feature, and other types of issues readable and consistent.", + "tags": [ + "documentation", + "templates", + "repository-setup", + "github" + ] + }, + { + "title": "Change Log", + "uri": "/slim/docs/guides/documentation/change-log/", + "category": "documentation", + "description": "A guide on creating and maintaining a human-readable change log for software development projects, emphasizing the importance of a `CHANGELOG.md` file.", + "tags": [ + "documentation", + "versioning", + "templates", + "repository-setup", + "github" + ] + }, + { + "title": "Documentation Hosts", + "uri": "/slim/docs/guides/documentation/documentation-hosts/trade-study-hostingdocs-user", + "category": "documentation", + "description": "A guide on possible use cases and recommended tools for hosting various types of documentation with a call for contributions.", + "tags": [ + "documentation", + "trade-studies", + "tools" + ] + }, + { + "title": "Pull Requests", + "uri": "/slim/docs/guides/governance/contributions/change-request-templates", + "category": "governance", + "description": "A guide outlining how to implement a pre-filled pull request template to provide guidance to potential contributors on GitHub.", + "tags": [ + "github", + "templates", + "governance", + "repository-setup" + ] + }, + { + "title": "Code of Conduct", + "uri": "/slim/docs/guides/governance/contributions/code-of-conduct", + "category": "governance", + "description": "A guide on how to create and implement a code of conduct for project teams, with a specific recommendation to use the Contributor Covenant.", + "tags": [ + "governance", + "repository-setup", + "github", + "templates" + ] + }, + { + "title": "Contributing Guide", + "uri": "/slim/docs/guides/governance/contributions/contributing-guide", + "category": "governance", + "description": "A detailed guide about creating a contributing guide for your project, featuring a customizable template and instructions on how to use it.", + "tags": [ + "templates", + "governance", + "repository-setup", + "github", + "templates" + ] + }, + { + "title": "Python Starter Kit", + "uri": "/slim/docs/guides/software-lifecycle/application-starter-kits/python-starter-kit", + "category": "software-lifecycle", + "description": "A guide to a complete, deployment-ready Python 3 application that's bundled into a reusable template repository for quick implementation, with integrated build, release, and publish on GitHub.", + "tags": [ + "python", + "templates", + "repository-setup", + "continuous-integration", + "github" + ] + }, + { + "title": "Continuous Integration Frameworks", + "uri": "/slim/docs/guides/software-lifecycle/continuous-integration/continuous-integration-frameworks", + "category": "software lifecycle", + "description": "An overview of different continuous integration frameworks and their use cases.", + "tags": [ + "tools", + "continuous-integration", + "trade-studies" + ] + }, + { + "title": "Reference Architectures", + "uri": "/slim/docs/guides/software-lifecycle/continuous-integration/reference-architecture", + "category": "software lifecycle", + "description": "A high-level reference guide for the implementation of continuous integration best practices, detailing structure, component interrelationships, and processes.", + "tags": [ + "continuous-integration", + "testing", + "versioning", + "devops" + ] + }, + { + "title": "Continuous Testing", + "uri": "/slim/docs/guides/software-lifecycle/continuous-testing/", + "category": "software lifecycle", + "description": "An extensive list of resources and tools for continuous testing including module testing, service endpoint testing, performance testing, and mobile testing among others.", + "tags": [ + "testing", + "tools" + ] + }, + { + "title": "GitHub Security Best Practices", + "uri": "/slim/docs/guides/software-lifecycle/security/github-security", + "category": "software lifecycle", + "description": "Recommendations for enabling GitHub security features for repositories, including using GitHub native tools like CodeQL, code scanning and more.", + "tags": [ + "software-lifecycle", + "security", + "testing", + "tools" + ] + }, + { + "title": "Metrics Tracking", + "uri": "/slim/docs/guides/software-lifecycle/metrics", + "category": "metrics tracking", + "description": "Recommendations for metrics collection and an installation tool for Apache DevLake.", + "tags": [ + "software-lifecycle", + "metrics", + "tools" + ] + } +] \ No newline at end of file diff --git a/static/img/slim-dashboard-devlake.png b/static/img/slim-dashboard-devlake.png new file mode 100644 index 000000000..8ae8a662a Binary files /dev/null and b/static/img/slim-dashboard-devlake.png differ