Tool to generate a Markdown report of SLIM best practices compliance.
This repository serves to create a leaderboard report (markdown table) that ranks and showcases how well a given set of GitHub repositories follow SLIM best practices.
- Script to query a set of GitHub repositories and create a markdown table showcasing compliance to SLIM best practices, sorted by most to least compliant, printed to standard out and to an external file.
- Best practices scanned for include:
- Repository best practices (i.e. README, templates, licensing, etc.)
- Specification of repositories and API tokens 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.
- API jittering to prevent too many fast requests to GitHub at once.
- Logging to share the status of repository compliance as the script runs.
- Features
- Contents
- Quick Start
- Changelog
- Frequently Asked Questions (FAQ)
- Contributing
- License
- Support
Use this quick start guide to generate a fresh leaderboard table.
You must have a configuration file to use this script. The purpose of the configuration file is:
- List the repositories to scan
- List the organizations to scan for repositories
- Point to the output file that will list the results
- Cite the GitHub personal access token used for authorization
This configuration file will be pointed to at runtime as an agrgument (see run instructions below).
Below is a sample of a configuration file named slim-config.json
:
{
"gh_personal_access_token": "[INSERT_GITHUB_TOKEN_HERE]",
"targets": [
{
"type": "organization",
"name": "https://github.com/nasa-ammos"
},
{
"type": "repository",
"name": "https://github.com/nasa/FEI"
},
{
"type": "repository",
"name": "https://github.com/rzellem/EXOTIC"
}
],
"output": "slim-oss-leaderboard.md"
}
Requirements:
- Python 3
requests
module
Setup:
- Generate a GitHub personal access token and replace the string
TOKEN_GOES_HERE
with the value of your token. NOTE: make sure the "repo" group permission is enabled for your token within GitHub.com's personal access token setup.
To generate a fresh leaderboard markdown table (printed to stdout
), run the following command:
python leaderboard.py [CONFIG_FILE]
Example:
python leaderboard.py slim-config.json
You'll see an output similar to the contents of the below sample:
Project | Repository | Issue Templates | PR Templates | Code of Conduct | Contributing Guide | LICENSE | README | Change Log | Link to Docs in README |
---|---|---|---|---|---|---|---|---|---|
nasa-ammos | slim-starterkit | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
nasa-ammos | slim-starterkit-python | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
nasa-ammos | parent-ammos | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
nasa-ammos | slim | ❌ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ |
nasa-ammos | MMGIS | ❌ | ✅ | ✅ | ✅ | ✅ | ❌ | ✅ | ✅ |
|
How to interpret the leaderboard contents:
- A ✅ indicates successful compliance, where as a ❌ indicates not fully compliant
- Most checks verify whether files within your repository that should exist, do in fact exist. Some checks are more specialized, such as:
- "README" - checks if your README conforms to the SLIM standard README
- "Dev/User Documentation" check for links to be present in your README that point to specific Dev or User docs - this is part of the SLIM standard README
See our root CHANGELOG.md for a history of our changes.
None. Please post a PR for this section to ask your question and the development team will add an answer.
Interested in contributing to our project? Please see our: CONTRIBUTING.md
See our: LICENSE
Key points of contact are: @riverma