From 84a2c1b977a9799198d1c681ea96f51ca5eda944 Mon Sep 17 00:00:00 2001 From: Pedro Nacht Date: Mon, 18 Jul 2022 19:13:42 -0300 Subject: [PATCH 1/3] Minor typos and copy-editing to checks/write.md --- checks/write.md | 52 ++++++++++++++++++++++++------------------------- 1 file changed, 25 insertions(+), 27 deletions(-) diff --git a/checks/write.md b/checks/write.md index 383f8830087..f1bac5bfd54 100644 --- a/checks/write.md +++ b/checks/write.md @@ -1,14 +1,14 @@ # Requirements for a check -If you'd like to add a check, make sure it is something that meets the following -criteria and then create a new GitHub Issue to discuss with the team: +If you'd like to add a check, make sure it meets the following criteria and then +create a new GitHub Issue to discuss with the team: - The scorecard must only be composed of automate-able, objective data. For example, a project having 10 contributors doesn’t necessarily mean it’s more - secure than a project with say 50 contributors. But, having two maintainers + secure than a project with 50 contributors. But, having two maintainers might be preferable to only having one - the larger bus factor and ability to provide code reviews is objectively better. -- The scorecard criteria can be as specific as possible and not limited +- The scorecard criteria can be as specific as possible and are not limited to general recommendations. For example, for Go, we can recommend/require specific linters and analyzers to be run on the codebase. - The scorecard can be populated for any open source project without any work @@ -19,18 +19,18 @@ criteria and then create a new GitHub Issue to discuss with the team: of a given scorecard finding for that repository. - Any criteria in the scorecard must be actionable. It should be possible, with help, for any project to "check all the boxes". -- Any solution to compile a scorecard should be usable by the greater open - source community to monitor upstream security. +- Any solution to compile a scorecard should be usable by the greater + open-source community to monitor upstream security. # How to write a check -The steps to writting a check are as follow: +The steps to writing a check are as follows: -1. Create a file under `checks/` folder, say `checks/mycheck.go` +1. Create a file under the `checks/` folder, say `checks/mycheck.go` 2. Give the check a name and register the check: - ``` - // Note: export the name: start its name with an upper-case letter. + ```go + // Note: export the name by starting it with an upper-case letter. const CheckMyCheckName string = "My-Check" func init() { @@ -38,46 +38,44 @@ The steps to writting a check are as follow: } ``` -3. Log information that is benfical to the user using `checker.DetailLogger`: +3. Log useful information with `checker.DetailLogger`: * Use `checker.DetailLogger.Warn()` to provide detail on low-score - results. This is showed when the user supplies the `show-results` - option. + results. This is shown when the user supplies the `show-results` option. * Use `checker.DetailLogger.Info()` to provide detail on high-score - results. This is showed when the user supplies the `show-results` - option. + results. This is shown when the user supplies the `show-results` option. * Use `checker.DetailLogger.Debug()` to provide detail in verbose mode: - this is showed only when the user supplies the `--verbosity Debug` + this is shown only when the user supplies the `--verbosity Debug` option. * If your message relates to a file, try to provide information such as the `Path`, line number `Offset` and `Snippet`. -4. If the checks fails in a way that is irrecoverable, return a result with - `checker.CreateRuntimeErrorResult()` function: For example, if an error is - returned from an API you call, use the function. +4. If the check fails in a way that is irrecoverable, return a result with the + `checker.CreateRuntimeErrorResult()` function. For example, if an error is + returned from an API you call, use this function. -5. Create the result of the check as follow: +5. Create the result of the check as follows: - * Always provide a high-level sentence explaining the result/score of the - check. + * Always provide a high-level sentence explaining the check's + result/score. * If the check runs properly but is unable to determine a score, use - `checker.CreateInconclusiveResult()` function. + `checker.CreateInconclusiveResult()`. * For proportional results, use `checker.CreateProportionalScoreResult()`. - * For maximum score, use `checker.CreateMaxScoreResult()`; for min score - use `checker.CreateMinScoreResult()`. + * For maximum and minimum scores, use `checker.CreateMaxScoreResult()` and + `checker.CreateMinScoreResult()`, respectively. * If you need more flexibility and need to set a specific score, use `checker.CreateResultWithScore()` with one of the constants declared, such as `checker.HalfResultScore`. 6. Dealing with errors: see [errors/errors.md](/errors/errors.md). -7. Create unit tests for both low, high and inconclusive score. Put them in a +7. Create unit tests for both low, high and inconclusive scores. Put them in a file `checks/mycheck_test.go`. 8. Create e2e tests in `e2e/mycheck_test.go`. Use a dedicated repo that will not change over time, so that it's reliable for the tests. -9. Update the `checks/checks.yaml` with the description of your check. +9. Update the `checks/checks.yaml` with a description of your check. 10. Generate `docs/check.md` using `make generate-docs`. This will validate and generate `docs/check.md`. From f680e77d66f3c8568839768a48c159216caffdf0 Mon Sep 17 00:00:00 2001 From: Pedro Nacht Date: Tue, 19 Jul 2022 12:50:40 -0300 Subject: [PATCH 2/3] Undo hyphen, remove "both" --- checks/write.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/checks/write.md b/checks/write.md index f1bac5bfd54..ecc6edb561a 100644 --- a/checks/write.md +++ b/checks/write.md @@ -19,8 +19,8 @@ create a new GitHub Issue to discuss with the team: of a given scorecard finding for that repository. - Any criteria in the scorecard must be actionable. It should be possible, with help, for any project to "check all the boxes". -- Any solution to compile a scorecard should be usable by the greater - open-source community to monitor upstream security. +- Any solution to compile a scorecard should be usable by the greater open + source community to monitor upstream security. # How to write a check @@ -69,7 +69,7 @@ The steps to writing a check are as follows: 6. Dealing with errors: see [errors/errors.md](/errors/errors.md). -7. Create unit tests for both low, high and inconclusive scores. Put them in a +7. Create unit tests for low, high and inconclusive scores. Put them in a file `checks/mycheck_test.go`. 8. Create e2e tests in `e2e/mycheck_test.go`. Use a dedicated repo that will From b47aaf69ac4f728f34247683e2b795703332d17a Mon Sep 17 00:00:00 2001 From: Pedro Nacht Date: Tue, 19 Jul 2022 12:52:17 -0300 Subject: [PATCH 3/3] Reflow item 7 --- checks/write.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/checks/write.md b/checks/write.md index ecc6edb561a..fc0bc9e6c95 100644 --- a/checks/write.md +++ b/checks/write.md @@ -69,8 +69,8 @@ The steps to writing a check are as follows: 6. Dealing with errors: see [errors/errors.md](/errors/errors.md). -7. Create unit tests for low, high and inconclusive scores. Put them in a - file `checks/mycheck_test.go`. +7. Create unit tests for low, high and inconclusive scores. Put them in a file + `checks/mycheck_test.go`. 8. Create e2e tests in `e2e/mycheck_test.go`. Use a dedicated repo that will not change over time, so that it's reliable for the tests.