2021-01-04 20:09:21 +03:00
# Contributing to Security Scorecards
2020-10-09 17:47:59 +03:00
2021-05-07 15:08:33 +03:00
Thank you for contributing your time and expertise to the Security Scorecards
project. This document describes the contribution guidelines for the project.
2020-10-09 17:47:59 +03:00
2021-05-07 15:08:33 +03:00
**Note:** Before you start contributing, you must read and abide by our
**[Code of Conduct](./CODE_OF_CONDUCT.md)**.
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 )
* [Contributing steps ](#contributing-steps )
2021-07-20 21:36:35 +03:00
* [Error handling ](#error-handling )
2021-05-14 23:50:26 +03:00
* [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 )
* [Permission for GitHub personal access tokens ](#permission-for-github-personal-access-tokens )
* [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
[personal access token ](https://docs.github.com/en/free-pro-team@latest/developers/apps/about-apps#personal-access-tokens )
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
2021-09-02 01:13:04 +03:00
[v1.17 ](https://golang.org/dl/ ) or higher.
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
2021-01-04 20:09:21 +03:00
## Contributing steps
2020-10-09 17:47:59 +03:00
2021-05-07 15:08:33 +03:00
1. 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.
2020-10-09 17:47:59 +03:00
2021-07-20 21:36:35 +03:00
## Error handling
2021-10-19 22:14:11 +03:00
See [errors ](errors/errors.md ).
2021-07-20 21:36:35 +03:00
2021-01-04 20:09:21 +03:00
## How to build scorecard locally
2020-10-09 17:47:59 +03:00
2021-05-07 15:08:33 +03:00
Note that, by building the scorecard from the source code we are allowed to test
the changes made locally.
2020-10-09 17:47:59 +03:00
2021-05-07 15:08:33 +03:00
1. Run the following command to clone your fork of the project locally
2020-10-09 17:47:59 +03:00
```shell
2021-01-04 20:09:21 +03:00
git clone git@github.com:< user > /scorecard.git $GOPATH/src/github.com/< user > /scorecard.git
2020-10-09 17:47:59 +03:00
```
2021-05-07 15:08:33 +03:00
1. Ensure you activate module support before continue (`$ export
GO111MODULE=on`)
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
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:`)
- Docs: :book: (`:book:`)
- 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.
2022-02-02 14:14:11 +03:00
You are free to use the `:xyz:` aliases or to use the equivalent emoji directly.
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
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? |
| -------- | -------------------------------------------------- | -------------------- |
| make all | Runs go test,golangci lint checks, fmt, go mod tidy| yes |
| make e2e | Runs e2e tests | yes |
2021-01-04 20:09:21 +03:00
2021-01-08 22:09:06 +03:00
## Permission for GitHub personal access tokens
The personal access token need the following scopes:
2021-05-07 15:08:33 +03:00
- `repo:status` - Access commit status
- `repo_deployment` - Access deployment status
- `public_repo` - Access public repositories
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
2021-05-07 15:08:33 +03:00
Scorecard maintains the list of 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
Submit a PR for this file and scorecard would start scanning in subsequent runs.
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
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
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 ).
If you want to update its documentation, update that `checks.yaml` file.
2021-05-14 23:50:26 +03:00
2021-09-13 23:40:56 +03:00
Whenever you modify the `checks.yaml` file, run the following to
2022-06-07 21:12:28 +03:00
generate `docs/checks.md` :
2021-09-13 23:40:56 +03:00
~~~~
make generate-docs
~~~~
**DO NOT** edit `docs/checks.md` directly, as that is an
auto-generated file. Edit `docs/checks/internal/checks.yaml` instead.
## 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.