/slim-leaderboard

Generates a report of SLIM best practices compliance.

Primary LanguagePythonApache License 2.0Apache-2.0

SLIM Best Practices Leaderboard

Tool to generate a scan report of SLIM best practices compliance.

Contributor Covenant SLIM

This repository serves to create a leaderboard report that ranks and showcases how well a given set of GitHub repositories follow SLIM best practices.

Features

  • Script to query a set of GitHub repositories and create a report showcasing compliance to SLIM best practices, sorted by most to least compliant, printed to standard out.
  • Best practices scanned for include all checklist items specified in the SLIM Getting Started Checklist
  • Specification of repositories via a config file - where repositories can be listed individually or automatically scanned from a parent organization.
  • Works with GitHub.com or GitHub Enterprise repositories.
  • GraphQL and parallelized queries to GitHub for optimization
  • Logging to share the status of repository compliance as the script runs.
  • Output format modes including: tree, table, and markdown
  • Verbose mode for additional statistical details and explanations

Contents

Quick Start

Use this quick start guide to generate a fresh leaderboard report.

Setup Instructions

This script requires a configuration file to operate. This file specifies the repositories and organizations to scan.

Below is an example of a configuration file named slim-config.json:

{
  "targets": [
      {
        "type": "repository",
        "name": "https://github.com/nasa-ammos/slim"
      }
  ]
}

Additional examples can be found in the examples/ sub-folder within this repository.

Run Instructions

Requirements:

  • Python 3
  • requests, requests-cache, tqdm, and rich modules
    • Install via: pip install requests requests-cache tqdm rich

Setup:

  • Obtain a GitHub personal access token (classic). Ensure that all permissions under the "repo" group are enabled for this token, including security_events.
  • Set the environment variable GITHUB_TOKEN with your token.

Execution:

*NOTE: the below example outputs will change as the tool evolves and adds more checks. For demonstration purposes only. *

To generate a fresh leaderboard report, use the following command format:

python leaderboard.py [CONFIG_FILE] --output_format [FORMAT] --unsorted --verbose --emoji

Arguments:

  • config_path: Path to the JSON configuration file.
  • (Optional) --output_format: Choose from 'TREE', 'TABLE', 'MARKDOWN', or 'PLAIN'. Default is 'TREE'.
  • (Optional) --unsorted: If included, the results will not be sorted.
  • (Optional) --verbose: If included, outputs verbose information, including detailed statistics and explanations for each check performed.
  • (Optional) --emoji: If included, outputs emojis for statuses rathe than pure text (e.g. ✅ ❌ ⚠️ etc.)

Examples: Generate a report using default settings:

python leaderboard.py slim-config.json

tree

Generate a report in table format:

python leaderboard.py slim-config.json --output_format TABLE

table

Verbose output in tree format:

python leaderboard.py slim-config.json --output_format TREE --verbose

tree-verbose

Markdown format without sorting and with emojis:

python leaderboard.py slim-config.json --output_format MARKDOWN --unsorted --emoji
Scanning Repositories: 100%|█████████████████████████████████████████████████████████████████████████████████████████████████████████████████████| 2/2 [00:02<00:00,  1.15s/repo]

# SLIM Best Practices Repository Scan Report
| Owner | Repository | License | Readme | Contributing Guide | Code of Conduct | Issue Templates | PR Templates | Changelog | Additional Documentation | Secrets Detection | Governance Model | GitHub: Vulnerability Alerts | GitHub: Code Scanning Alerts | GitHub: Secret Scanning Alerts |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| nasa-ammos | slim | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ | ✅ | ✅ | ✅ | ❌ |
| NASA-AMMOS | slim-starterkit-python | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ | ✅ | ❌ |

Changelog

See our root CHANGELOG.md for a history of our changes.

Frequently Asked Questions (FAQ)

None. Please post a PR for this section to ask your question and the development team will add an answer.

Contributing

Interested in contributing to our project? Please see our: CONTRIBUTING.md

License

See our: LICENSE

Support

Key points of contact are: @riverma