scorecard/CONTRIBUTING.md

Contributing to OpenSSF Scorecard

Thank you for contributing your time and expertise to the OpenSSF Scorecard project. This document describes the contribution guidelines for the project.

Note: Before you start contributing, you must read and abide by our Code of Conduct.

• Contributing code
  • Getting started
  • Environment Setup
• Contributing steps
• Error handling
• How to build scorecard locally
• PR Process
• What to do before submitting a pull request
• Permission for GitHub personal access tokens
• Where the CI Tests are configured
• dailyscore-cronjob
  • Deploying the cron job
• How do I add additional GitHub repositories to be scanned by scorecard dailyscore?
• Adding New Checks
• Updating Docs
• Choosing checks to run

Contributing code

Getting started

1. Create a GitHub account
2. Create a personal access token
3. Set up your development environment

Environment Setup

You must install these tools:

1. git: For source control

2. go: You need go version v1.19 or higher.

3. docker: v18.9 or higher.

Contributing steps

1. Submit an issue describing your proposed change to the repo in question.
2. The repo owners will respond to your issue promptly.
3. Fork the desired repo, develop and test your code changes.
4. Submit a pull request.

Error handling

See errors.

How to build scorecard locally

Note that, by building the scorecard from the source code we are allowed to test the changes made locally.

1. Run the following command to clone your fork of the project locally

git clone git@github.com:<user>/scorecard.git $GOPATH/src/github.com/<user>/scorecard.git

1. Enter the project folder by running the command cd ./scorecard
2. Ensure you activate module support before continue ($ export GO111MODULE=on)
3. Install the build tools for the project by running the command make install
4. Run the command make build to build the source code

How to run scorecard locally

In the project folder, run the following command:

// Get scores for a repository
$ go run main.go --repo=github.com/ossf-tests/scorecard-check-branch-protection-e2e

You can input the repository you want to analyze using the --repo=<your_repo> flag. To view more Scorecard commands run:

// View scorecard help
$ go run main.go --help

Choosing checks to run

You can use the --checks option to select which checks to run. This is useful if, for example, you only want to run the check you're currently developing.

// Get score for Pinned-Dependencies check
$ go run main.go --repo=github.com/ossf-tests/scorecard-check-branch-protection-e2e --checks=Pinned-Dependencies

// Get score for Pinned-Dependencies and Binary-Artifacts check
$ go run main.go --repo=github.com/ossf-tests/scorecard-check-branch-protection-e2e --checks=Pinned-Dependencies,Binary-Artifacts

PR Process

Every PR should be annotated with an icon indicating whether it's a:

• Breaking change: ⚠️ (:warning:)
• Non-breaking feature: ✨ (:sparkles:)
• Patch fix: 🐛 (:bug:)
• Docs: 📖 (:book:)
• Infra/Tests/Other: 🌱 (:seedling:)
• No release note: 👻 (:ghost:)

Use 👻 (no release note) only for the PRs that change or revert unreleased changes, which don't deserve a release note. Please don't abuse it.

You are free to use the :xyz: aliases or to use the equivalent emoji directly.

Individual commits should not be tagged separately, but will generally be assumed to match the PR. For instance, if you have a bugfix in with a breaking change, it's generally encouraged to submit the bugfix separately, but if you must put them in one PR, you should mark the whole PR as breaking.

What to do before submitting a pull request

Following the targets that can be used to test your changes locally.

Command	Description	Is called in the CI?
make all	Runs go test,golangci lint checks, fmt, go mod tidy	yes
make e2e-pat	Runs e2e tests	yes

Make sure to signoff your commits before submitting a pull request.

https://docs.pi-hole.net/guides/github/how-to-signoff/

Permission for GitHub personal access tokens

The personal access token need the following scopes:

• repo:status - Access commit status
• repo_deployment - Access deployment status
• public_repo - Access public repositories

Where the CI Tests are configured

1. See the action files to check its tests, and the scripts used on it.

How do I add additional GitHub repositories to be scanned by scorecard weekly?

Scorecard maintains the list of repositories in a file https://github.com/ossf/scorecard/blob/main/cron/internal/data/projects.csv

Submit a PR for this file and scorecard would start scanning in subsequent runs.

Adding New Checks

See checks/write.md. When you add new checks, you need to also update the docs.

Updating Docs

A summary for each check needs to be included in the README.md. In most cases, to update the documentation simply edit the corresponding .md file, with the notable exception of the auto-generated file checks.md.

Details about each check need to be provided in docs/checks/internal/checks.yaml. If you want to update its documentation, update that checks.yaml file.

Whenever you modify the checks.yaml file, run the following to generate docs/checks.md:

make generate-docs

DO NOT edit docs/checks.md directly, as that is an auto-generated file. Edit docs/checks/internal/checks.yaml instead.