2022-12-01 12:36:12 +03:00
# Contributing to OpenSSF Scorecard
2020-10-09 17:47:59 +03:00
2022-12-01 12:36:12 +03:00
Thank you for contributing your time and expertise to the OpenSSF Scorecard
2021-05-07 15:08:33 +03:00
project. This document describes the contribution guidelines for the project.
2020-10-09 17:47:59 +03:00
2024-04-04 22:52:11 +03:00
> [!IMPORTANT]
> Before you start contributing, you must read and abide by our
2021-05-07 15:08:33 +03:00
**[Code of Conduct](./CODE_OF_CONDUCT.md)**.
2024-04-04 22:52:11 +03:00
>
> 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/).
2021-03-15 19:16:33 +03:00
<!-- vim - markdown - toc GFM -->
2021-05-14 23:50:26 +03:00
* [Contributing code ](#contributing-code )
* [Getting started ](#getting-started )
* [Environment Setup ](#environment-setup )
2024-04-08 18:37:04 +03:00
* [New to Go? ](#new-to-go )
2021-05-14 23:50:26 +03:00
* [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 )
2024-01-23 22:32:59 +03:00
* [Changing Score Results ](#changing-score-results )
* [Linting ](#linting )
2021-05-14 23:50:26 +03:00
* [Permission for GitHub personal access tokens ](#permission-for-github-personal-access-tokens )
2024-01-23 22:32:59 +03:00
* [Adding New Probes ](#adding-new-probes )
2021-05-14 23:50:26 +03:00
* [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 )
2021-09-13 23:40:56 +03:00
* [Updating Docs ](#updating-docs )
* [Choosing checks to run ](#choosing-checks-to-run )
2021-03-15 19:16:33 +03:00
<!-- vim - markdown - toc -->
2020-10-09 17:47:59 +03:00
## Contributing code
### Getting started
2021-05-07 15:08:33 +03:00
1. Create [a GitHub account ](https://github.com/join )
1. Create a
2024-04-04 22:52:11 +03:00
[personal access token ](https://docs.github.com/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens )
2021-05-07 15:08:33 +03:00
1. Set up your [development environment ](#environment-setup )
2020-10-09 17:47:59 +03:00
2020-10-26 23:22:13 +03:00
### Environment Setup
2020-10-09 17:47:59 +03:00
You must install these tools:
2021-05-07 15:08:33 +03:00
1. [`git` ](https://help.github.com/articles/set-up-git/ ): For source control
2020-10-09 17:47:59 +03:00
2021-05-07 15:08:33 +03:00
1. [`go` ](https://golang.org/doc/install ): You need go version
2024-09-03 06:22:00 +03:00
[v1.22.0 ](https://golang.org/dl/ ) or higher.
2024-04-04 22:52:11 +03:00
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:
2020-10-09 17:47:59 +03:00
2021-05-07 15:08:33 +03:00
1. [`docker` ](https://docs.docker.com/engine/install/ ): `v18.9` or higher.
2020-10-09 17:47:59 +03:00
2024-04-08 18:37:04 +03:00
### 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 )
2021-01-04 20:09:21 +03:00
## Contributing steps
2020-10-09 17:47:59 +03:00
2024-04-04 22:52:11 +03:00
1. Identify an existing issue you would like to work on, or submit an issue describing your proposed change to the repo in question.
2021-05-07 15:08:33 +03:00
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.
2020-10-09 17:47:59 +03:00
2024-04-04 22:52:11 +03:00
## How to build Scorecard locally
2020-10-09 17:47:59 +03:00
2024-04-04 22:52:11 +03:00
Note that, by building Scorecard from the source code we are allowed to test
2021-05-07 15:08:33 +03:00
the changes made locally.
2020-10-09 17:47:59 +03:00
2024-04-04 22:52:11 +03:00
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))
2023-02-01 07:06:46 +03:00
1. Enter the project folder by running the command `cd ./scorecard`
2022-02-03 02:00:35 +03:00
1. Install the build tools for the project by running the command `make install`
2021-05-07 15:08:33 +03:00
1. Run the command `make build` to build the source code
2021-01-04 20:09:21 +03:00
2023-02-01 07:06:46 +03:00
## How to run scorecard locally
In the project folder, run the following command:
```shell
2024-04-04 22:52:11 +03:00
# Get scores for a repository
go run main.go --repo=github.com/ossf-tests/scorecard-check-branch-protection-e2e
2023-02-01 07:06:46 +03:00
```
2024-04-04 22:52:11 +03:00
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:
2023-02-01 07:06:46 +03:00
```shell
2024-04-04 22:52:11 +03:00
# View scorecard help
go run main.go --help
2023-02-01 07:06:46 +03:00
```
2024-04-04 22:52:11 +03:00
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
2023-02-01 07:06:46 +03:00
### 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
2024-04-04 22:52:11 +03:00
# Get score for Pinned-Dependencies check
go run main.go --repo=github.com/ossf-tests/scorecard-check-branch-protection-e2e --checks=Pinned-Dependencies
2023-02-01 07:06:46 +03:00
2024-04-04 22:52:11 +03:00
# 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
2023-02-01 07:06:46 +03:00
```
2021-03-21 18:02:19 +03:00
## PR Process
Every PR should be annotated with an icon indicating whether it's a:
2021-05-07 15:08:33 +03:00
- Breaking change: :warning: (`:warning:`)
- Non-breaking feature: :sparkles: (`:sparkles:`)
- Patch fix: :bug: (`:bug:`)
2024-04-04 22:52:11 +03:00
- Documentation changes (user or developer): :book: (`:book:`)
2021-05-07 15:08:33 +03:00
- Infra/Tests/Other: :seedling: (`:seedling:`)
- No release note: :ghost: (`:ghost:`)
2021-03-21 18:02:19 +03:00
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.
2024-04-04 22:52:11 +03:00
Prefer using the `:xyz:` aliases over the equivalent emoji directly when possible.
2021-03-21 18:02:19 +03:00
Individual commits should not be tagged separately, but will generally be
2021-05-07 15:08:33 +03:00
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.
2021-03-21 18:02:19 +03:00
2024-04-04 22:52:11 +03:00
> [!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.
2024-01-23 22:32:59 +03:00
2021-01-04 20:09:21 +03:00
## What to do before submitting a pull request
Following the targets that can be used to test your changes locally.
2021-05-07 15:08:33 +03:00
| Command | Description | Is called in the CI? |
| -------- | -------------------------------------------------- | -------------------- |
2024-04-04 22:52:11 +03:00
| `make all` | Runs go test,golangci lint checks, fmt, go mod tidy| yes |
| `make e2e-pat` | Runs e2e tests | yes |
2022-10-21 01:28:55 +03:00
2024-04-04 22:52:11 +03:00
When developing locally, the following targets are useful to run frequently.
While they are included in `make all` , running them individually is faster.
2022-10-21 01:28:55 +03:00
2024-04-04 22:52:11 +03:00
| Command | Description | Called in the CI? |
|----------|-------------|-------------------|
| `make unit-test` | Runs unit tests only | yes |
| `make check-linter` | Checks linter issues only | yes |
2024-01-23 22:32:59 +03:00
## 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
```
2021-01-08 22:09:06 +03:00
## Permission for GitHub personal access tokens
2024-04-08 18:37:04 +03:00
For public repos, classic personal access tokens need the following scopes:
- `public_repo` - Read/write access to public repositories. Needed for branch protection
2021-01-08 22:09:06 +03:00
2021-01-04 20:09:21 +03:00
## Where the CI Tests are configured
2021-05-07 15:08:33 +03:00
1. See the [action files ](.github/workflows ) to check its tests, and the
scripts used on it.
2021-01-04 20:09:21 +03:00
2022-06-07 21:12:28 +03:00
## How do I add additional GitHub repositories to be scanned by scorecard weekly?
2021-03-15 19:16:33 +03:00
2024-01-20 01:11:19 +03:00
Scorecard maintains the list of GitHub repositories in a file
2022-06-07 21:12:28 +03:00
https://github.com/ossf/scorecard/blob/main/cron/internal/data/projects.csv
2021-03-15 19:16:33 +03:00
2024-01-20 01:11:19 +03:00
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.
2021-03-15 19:16:33 +03:00
2020-10-09 17:47:59 +03:00
## Adding New Checks
2021-07-20 21:36:35 +03:00
See [checks/write.md ](checks/write.md ).
2021-09-13 23:40:56 +03:00
When you add new checks, you need to also update the docs.
2020-10-09 17:47:59 +03:00
2024-01-23 22:32:59 +03:00
## Adding New Probes
See [probes/README.md ](probes/README.md ) for information about the probes.
2021-09-13 23:40:56 +03:00
## Updating Docs
2021-05-14 23:50:26 +03:00
2021-09-13 23:40:56 +03:00
A summary for each check needs to be included in the `README.md` .
In most cases, to update the documentation simply edit the corresponding
2022-06-07 21:12:28 +03:00
`.md` file, with the notable exception of the auto-generated file `checks.md` .
2021-05-14 23:50:26 +03:00
2024-09-20 20:44:35 +03:00
> [!IMPORTANT]
> **DO NOT** edit `docs/checks.md` directly, as that is an
> auto-generated file. Edit `docs/checks/internal/checks.yaml` instead.
2022-06-07 21:12:28 +03:00
Details about each check need to be provided in
[docs/checks/internal/checks.yaml ](docs/checks/internal/checks.yaml ).
2024-09-20 20:44:35 +03:00
If you want to update its documentation:
1. Make your edits in `docs/checks/internal/checks.yaml` .
2. Regenerate `docs/checks.md` by running `make generate-docs`
3. Commit both `docs/checks/internal/checks.yaml` and `docs/checks.md`