mirror of
https://github.com/ossf/scorecard.git
synced 2024-09-19 21:18:09 +03:00
4c6d0e53a3
* undo pat scope doc change Signed-off-by: Spencer Schrock <sschrock@google.com> * add Go resources some contributors may be unfamiliar with the language Signed-off-by: Spencer Schrock <sschrock@google.com> --------- Signed-off-by: Spencer Schrock <sschrock@google.com>
241 lines
9.3 KiB
Markdown
241 lines
9.3 KiB
Markdown
# 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.
|
|
|
|
> [!IMPORTANT]
|
|
> Before you start contributing, you must read and abide by our
|
|
**[Code of Conduct](./CODE_OF_CONDUCT.md)**.
|
|
>
|
|
> Additionally the Linux Foundation (LF) requires all contributions include per-commit sign-offs.
|
|
> Ensure you use the `-s` or `--signoff` flag for every commit.
|
|
>
|
|
> For more details, see the [LF DCO wiki](https://wiki.linuxfoundation.org/dco)
|
|
> or [this Pi-hole signoff guide](https://docs.pi-hole.net/guides/github/how-to-signoff/).
|
|
|
|
<!-- vim-markdown-toc GFM -->
|
|
|
|
* [Contributing code](#contributing-code)
|
|
* [Getting started](#getting-started)
|
|
* [Environment Setup](#environment-setup)
|
|
* [New to Go?](#new-to-go)
|
|
* [Contributing steps](#contributing-steps)
|
|
* [How to build scorecard locally](#how-to-build-scorecard-locally)
|
|
* [PR Process](#pr-process)
|
|
* [What to do before submitting a pull request](#what-to-do-before-submitting-a-pull-request)
|
|
* [Changing Score Results](#changing-score-results)
|
|
* [Linting](#linting)
|
|
* [Permission for GitHub personal access tokens](#permission-for-github-personal-access-tokens)
|
|
* [Adding New Probes](#adding-new-probes)
|
|
* [Where the CI Tests are configured](#where-the-ci-tests-are-configured)
|
|
* [dailyscore-cronjob](#dailyscore-cronjob)
|
|
* [Deploying the cron job](#deploying-the-cron-job)
|
|
* [How do I add additional GitHub repositories to be scanned by scorecard dailyscore?](#how-do-i-add-additional-github-repositories-to-be-scanned-by-scorecard-dailyscore)
|
|
* [Adding New Checks](#adding-new-checks)
|
|
* [Updating Docs](#updating-docs)
|
|
* [Choosing checks to run](#choosing-checks-to-run)
|
|
|
|
<!-- vim-markdown-toc -->
|
|
|
|
## Contributing code
|
|
|
|
### Getting started
|
|
|
|
1. Create [a GitHub account](https://github.com/join)
|
|
1. Create a
|
|
[personal access token](https://docs.github.com/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens)
|
|
1. Set up your [development environment](#environment-setup)
|
|
|
|
### Environment Setup
|
|
|
|
You must install these tools:
|
|
|
|
1. [`git`](https://help.github.com/articles/set-up-git/): For source control
|
|
|
|
1. [`go`](https://golang.org/doc/install): You need go version
|
|
[v1.21.8](https://golang.org/dl/) or higher.
|
|
|
|
1. [`protoc`](https://grpc.io/docs/protoc-installation/): `v3` or higher
|
|
|
|
1. [`make`](https://www.gnu.org/software/make/): You can build and run Scorecard without it, but some tasks are easier if you have it.
|
|
|
|
You may need these tools for some tasks:
|
|
|
|
1. [`docker`](https://docs.docker.com/engine/install/): `v18.9` or higher.
|
|
|
|
### New to Go?
|
|
|
|
If you're unfamiliar with the language, there are plenty of articles, resources, and books.
|
|
We recommend starting with several resources from the official Go website:
|
|
|
|
* [How to Write Go Code](https://go.dev/doc/code)
|
|
* [A Tour of Go](https://go.dev/tour/)
|
|
* [Effective Go](https://go.dev/doc/effective_go)
|
|
|
|
## Contributing steps
|
|
|
|
1. Identify an existing issue you would like to work on, or submit an issue describing your proposed change to the repo in question.
|
|
1. The repo owners will respond to your issue promptly.
|
|
1. Fork the desired repo, develop and test your code changes.
|
|
1. Submit a pull request.
|
|
|
|
## How to build Scorecard locally
|
|
|
|
Note that, by building Scorecard from the source code we are allowed to test
|
|
the changes made locally.
|
|
|
|
1. Clone your fork of the project locally. ([Detailed instructions](https://docs.github.com/repositories/creating-and-managing-repositories/cloning-a-repository#cloning-a-repository))
|
|
1. Enter the project folder by running the command `cd ./scorecard`
|
|
1. Install the build tools for the project by running the command `make install`
|
|
1. Run the command `make build` to build the source code
|
|
|
|
## How to run scorecard locally
|
|
|
|
In the project folder, run the following command:
|
|
|
|
```shell
|
|
# Get scores for a repository
|
|
go run main.go --repo=github.com/ossf-tests/scorecard-check-branch-protection-e2e
|
|
```
|
|
|
|
Many developers prefer working with the JSON output format, although you may need to pretty print it.
|
|
Piping the output to [jq](https://jqlang.github.io/jq/) is one way of doing this.
|
|
```shell
|
|
# Get scores for a repository
|
|
go run main.go --repo=github.com/ossf-tests/scorecard-check-branch-protection-e2e --format json | jq
|
|
```
|
|
|
|
To view all Scorecard commands and flags run:
|
|
|
|
```shell
|
|
# View scorecard help
|
|
go run main.go --help
|
|
```
|
|
|
|
You should familiarize yourself with:
|
|
* `--repo` and `--local` to specify a repository
|
|
* `--checks` and `--probes` to specify which analyses run
|
|
* `--format` to change the result output format
|
|
* `--show-details` is pretty self explanatory
|
|
|
|
### 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.
|
|
|
|
```shell
|
|
# 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: (`:warning:`)
|
|
- Non-breaking feature: :sparkles: (`:sparkles:`)
|
|
- Patch fix: :bug: (`:bug:`)
|
|
- Documentation changes (user or developer): :book: (`:book:`)
|
|
- Infra/Tests/Other: :seedling: (`:seedling:`)
|
|
- No release note: :ghost: (`:ghost:`)
|
|
|
|
Use :ghost: (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.
|
|
|
|
Prefer using the `:xyz:` aliases over the equivalent emoji directly when possible.
|
|
|
|
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.
|
|
|
|
> [!NOTE]
|
|
> Once a maintainer reviews your code, please address feedback without rebasing when possible.
|
|
> This includes [synchronizing your PR](https://docs.github.com/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/keeping-your-pull-request-in-sync-with-the-base-branch)
|
|
> with `main`. The GitHub review experience is much nicer with traditional merge commits.
|
|
|
|
## 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 |
|
|
|
|
When developing locally, the following targets are useful to run frequently.
|
|
While they are included in `make all`, running them individually is faster.
|
|
|
|
| Command | Description | Called in the CI? |
|
|
|----------|-------------|-------------------|
|
|
| `make unit-test` | Runs unit tests only | yes |
|
|
| `make check-linter` | Checks linter issues only | yes |
|
|
|
|
## Changing Score Results
|
|
|
|
As a general rule of thumb, pull requests that change Scorecard score results will need a good reason to do so to get merged.
|
|
It is a good idea to discuss such changes in a GitHub issue before implementing them.
|
|
|
|
## Linting
|
|
|
|
Most linter issues can be fixed with `golangci-lint` with the following command:
|
|
|
|
```
|
|
make fix-linter
|
|
```
|
|
|
|
## Permission for GitHub personal access tokens
|
|
|
|
For public repos, classic personal access tokens need the following scopes:
|
|
|
|
- `public_repo` - Read/write access to public repositories. Needed for branch protection
|
|
|
|
## Where the CI Tests are configured
|
|
|
|
1. See the [action files](.github/workflows) 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 GitHub repositories in a file
|
|
https://github.com/ossf/scorecard/blob/main/cron/internal/data/projects.csv
|
|
|
|
GitLab repositories are listed in:
|
|
https://github.com/ossf/scorecard/blob/main/cron/internal/data/gitlab-projects.csv
|
|
|
|
Append your desired repositories to the end of these files, then run `make add-projects`.
|
|
Commit the changes, and submit a PR and scorecard would start scanning in subsequent runs.
|
|
|
|
## Adding New Checks
|
|
|
|
See [checks/write.md](checks/write.md).
|
|
When you add new checks, you need to also update the docs.
|
|
|
|
## Adding New Probes
|
|
|
|
See [probes/README.md](probes/README.md) for information about the probes.
|
|
|
|
## 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](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`:
|
|
|
|
```shell
|
|
make generate-docs
|
|
```
|
|
|
|
**DO NOT** edit `docs/checks.md` directly, as that is an
|
|
auto-generated file. Edit `docs/checks/internal/checks.yaml` instead.
|