From 99c0e360a5a4431afe145cdce3142f5f9840c1ff Mon Sep 17 00:00:00 2001 From: Spencer Schrock Date: Wed, 3 Apr 2024 15:54:30 -0700 Subject: [PATCH 01/10] feature dco requirement more prominently Signed-off-by: Spencer Schrock --- CONTRIBUTING.md | 13 ++++++++----- 1 file changed, 8 insertions(+), 5 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 7953aa09fe3..2f6cb6549c2 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -3,8 +3,15 @@ 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 +> [!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/). @@ -141,10 +148,6 @@ Following the targets that can be used to test your changes locally. | 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/ - When developing locally, the following commands are useful to run regularly to check unit tests and linting. | Command | Description | Is called in the CI? | From b123cbd78d8afe24e8d658e7af231af3fc5d64aa Mon Sep 17 00:00:00 2001 From: Spencer Schrock Date: Wed, 3 Apr 2024 15:58:45 -0700 Subject: [PATCH 02/10] recommend merge commits to sync PR Signed-off-by: Spencer Schrock --- CONTRIBUTING.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 2f6cb6549c2..9c89fbcd129 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -136,8 +136,10 @@ 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. -When a maintainer reviews your code, it is generally preferred to solve each individual -review with small fixes without rebasing, so the maintainer can assess each fix separately. +> [!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 From 0ad51cd6e6e3bc3a7b2b65513e15f3699956d8aa Mon Sep 17 00:00:00 2001 From: Spencer Schrock Date: Wed, 3 Apr 2024 16:06:56 -0700 Subject: [PATCH 03/10] fix make target table Signed-off-by: Spencer Schrock --- CONTRIBUTING.md | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 9c89fbcd129..3b82a75040b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -147,14 +147,16 @@ 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 all` | Runs go test,golangci lint checks, fmt, go mod tidy| yes | +| `make e2e-pat` | Runs e2e tests | yes | -When developing locally, the following commands are useful to run regularly to check unit tests and linting. +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 | Is called in the CI? | -| make unit-test | Runs unit tests only. `make all` will also run this. | yes | -| make check-linter | Checks linter issues only. `make all` will also run this. | yes | +| 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 From 12867ac65ba7266b7e4e5ca13da6014ac450eb12 Mon Sep 17 00:00:00 2001 From: Spencer Schrock Date: Wed, 3 Apr 2024 16:28:24 -0700 Subject: [PATCH 04/10] remove references to old Go environment variables GO111MODULE is no longer used as of Go 1.17. GOPATH is still used for other purposes, but not in 'development mode'. https://go.dev/wiki/GOPATH Signed-off-by: Spencer Schrock --- CONTRIBUTING.md | 13 +++---------- 1 file changed, 3 insertions(+), 10 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 3b82a75040b..32a75d2c88a 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -68,20 +68,13 @@ You must install these tools: See [errors](errors/errors.md). -## How to build scorecard locally +## How to build Scorecard locally -Note that, by building the scorecard from the source code we are allowed to test +Note that, by building 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 - -```shell -git clone git@github.com:/scorecard.git $GOPATH/src/github.com//scorecard.git -``` - +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. Ensure you activate module support before continue (`$ export - GO111MODULE=on`) 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 From be7a6875f168b648a6b119907ac659605fb2362a Mon Sep 17 00:00:00 2001 From: Spencer Schrock Date: Wed, 3 Apr 2024 16:32:51 -0700 Subject: [PATCH 05/10] misc minor clarifications Signed-off-by: Spencer Schrock --- CONTRIBUTING.md | 14 +++++++++----- 1 file changed, 9 insertions(+), 5 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 32a75d2c88a..f12b1c486fc 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -43,7 +43,7 @@ project. This document describes the contribution guidelines for the project. 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) + [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 @@ -53,13 +53,17 @@ 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](https://golang.org/dl/) or higher. + [v1.21.8](https://golang.org/dl/) or higher. + +1. [`protoc`](https://grpc.io/docs/protoc-installation/): `v3` or higher + +You may need these tools for some tasks: 1. [`docker`](https://docs.docker.com/engine/install/): `v18.9` or higher. ## Contributing steps -1. Submit an issue describing your proposed change to the repo in question. +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. @@ -115,14 +119,14 @@ 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:`) -- Docs: :book: (`:book:`) +- 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. -You are free to use the `:xyz:` aliases or to use the equivalent emoji directly. +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 From 5a2dc9e287f4ee5793a8b5fd3d3ced4ec9171927 Mon Sep 17 00:00:00 2001 From: Spencer Schrock Date: Wed, 3 Apr 2024 16:45:07 -0700 Subject: [PATCH 06/10] remove reference to errors from CONTRIBUTORS.md I don't think this is one of the top things we should be displaying to someone Signed-off-by: Spencer Schrock --- CONTRIBUTING.md | 5 ----- errors/errors.md | 2 +- 2 files changed, 1 insertion(+), 6 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index f12b1c486fc..cfd62a6b652 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -19,7 +19,6 @@ project. This document describes the contribution guidelines for the project. * [Getting started](#getting-started) * [Environment Setup](#environment-setup) * [Contributing steps](#contributing-steps) -* [Error handling](#error-handling) * [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) @@ -68,10 +67,6 @@ You may need these tools for some tasks: 1. Fork the desired repo, develop and test your code changes. 1. Submit a pull request. -## Error handling - -See [errors](errors/errors.md). - ## How to build Scorecard locally Note that, by building Scorecard from the source code we are allowed to test diff --git a/errors/errors.md b/errors/errors.md index d5d43ee0b25..1e03dcb664f 100644 --- a/errors/errors.md +++ b/errors/errors.md @@ -1,7 +1,7 @@ # How to handle errors ```golang -import sce "github.com/ossf/scorecard/v2/errors" +import sce "github.com/ossf/scorecard/v4/errors" // Public errors are defined in errors/public.go and are exposed to callers. // Internal errors are defined in checks/errors.go. Their names start with errInternalXXX From b792ee1219bf772d71ec2b00913325699f063453 Mon Sep 17 00:00:00 2001 From: Spencer Schrock Date: Thu, 4 Apr 2024 09:37:23 -0700 Subject: [PATCH 07/10] mention make in environment Signed-off-by: Spencer Schrock --- CONTRIBUTING.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index cfd62a6b652..a27a572a1ac 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -56,6 +56,8 @@ You must install these tools: 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. From e888c13849e06d1a965d17c77b55a81d7e45e9f3 Mon Sep 17 00:00:00 2001 From: Spencer Schrock Date: Thu, 4 Apr 2024 09:50:51 -0700 Subject: [PATCH 08/10] no scopes needed for PATs Signed-off-by: Spencer Schrock --- CONTRIBUTING.md | 6 +----- 1 file changed, 1 insertion(+), 5 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index a27a572a1ac..0cbfbf524fa 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -167,11 +167,7 @@ make fix-linter ## 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 +For public repos, classic personal access tokens do not need any scopes. ## Where the CI Tests are configured From deacac2b8a11c6b8fd7d8e7d660e8124705de438 Mon Sep 17 00:00:00 2001 From: Spencer Schrock Date: Thu, 4 Apr 2024 10:01:02 -0700 Subject: [PATCH 09/10] highlight other scorecard options Signed-off-by: Spencer Schrock --- CONTRIBUTING.md | 15 ++++++++++++++- 1 file changed, 14 insertions(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 0cbfbf524fa..701c831e19d 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -88,13 +88,26 @@ In the project folder, run the following command: $ 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=` flag. To view more Scorecard commands run: +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. From 0dca25e876fa60dbadc9597a5a96b905f64de417 Mon Sep 17 00:00:00 2001 From: Spencer Schrock Date: Thu, 4 Apr 2024 10:14:06 -0700 Subject: [PATCH 10/10] allow shell codeblocks to be pasted into a shell the comment style was wrong and the $ was interpretted as a command. Signed-off-by: Spencer Schrock --- CONTRIBUTING.md | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 701c831e19d..56fe09892d1 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -84,22 +84,22 @@ the changes made 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 +# 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 +# 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 +# View scorecard help +go run main.go --help ``` You should familiarize yourself with: @@ -115,11 +115,11 @@ 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 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 +# 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 @@ -220,9 +220,9 @@ 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.