From bc5d7a8d4b6e8ae268ff94e75dda3082566d30e8 Mon Sep 17 00:00:00 2001 From: "David A. Wheeler" Date: Fri, 17 Sep 2021 09:35:53 -0400 Subject: [PATCH] =?UTF-8?q?=F0=9F=93=96=20Improve=20text=20on=20Packaging?= =?UTF-8?q?=20(#1035)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * Improve text on Packaging Make various improvements to the text on packaging. * The original text assumes that only software developers install software packages, which is absurd; end-users install software packages all the time. * The original text seemed to assume that there are only language-level packages, but system-level packages & containers are a thing :-). At least acknowledge them. Also, this doesn't make sense in some cases (e.g., software specific to one website that's updated through commits, or IoT software where there are no "packages" - you upload the entire image); that should be admitted. * Fix main text to stop using "you/your" to mean "project developer". There are at least two *different* readers: (1) developers of the project being measured and (2) potential users of the project being measured. Many users of scorecard will be #2, they'll reading scorecard results to decide if they want to use the software being measured. So don't say "you" and assume that "you" means project developers. I left "you" meaning "project developers" inside remediation, under the assumption that this was remdediation text for project developers. To be fair, *users* of software can also sometimes take remediation steps; that might be worth adding as its own section if we text to add there (e.g., `user_remediation`). I have intentionally not run `make generate-docs` as that would add other irrelevant changes. Instead, after this PR is accepted there should be a `make generate-docs` & a pull of *that*. Signed-off-by: David A. Wheeler * Add note about filing an issue Add note about filing an issue if scorecard fails to detect the packaging mechanism, per review by @naveensrinivasan (thanks!). Signed-off-by: David A. Wheeler --- docs/checks/internal/checks.yaml | 30 +++++++++++++++++++++++++++--- 1 file changed, 27 insertions(+), 3 deletions(-) diff --git a/docs/checks/internal/checks.yaml b/docs/checks/internal/checks.yaml index 3563c12d5b5..1c1db9f2114 100644 --- a/docs/checks/internal/checks.yaml +++ b/docs/checks/internal/checks.yaml @@ -363,16 +363,40 @@ checks: Packaging: risk: Medium tags: supply-chain, security, releases - short: Determines if the project is published as a package that other developers can install/download. + short: Determines if the project is published as a package that others can easily download, install, easily update, and uninstall. description: - This check tries to determine if the project is published as a package that other developers can install/download. + This check tries to determine if the project is published as a package that others can easily download, install, easily update, and uninstall. + + It's important that the project provide an easy way to + download, install, update, and uninstall the software. + It's particularly important to make it easy for users to + receive security patches as updates. + + This is often done by creating a "package" that is + easy to install and uninstall by a package manager. + Many program language ecosystems have a generally-used packaging format + supported by a language-level package manager + tool and public package repository. + Many operating system platforms also have at least one package format, + tool, and public repository (in some cases the source repository + generates system-independent source packages, which are then + used by others to generate system executable packages). + Container images are yet another way to package software. + In some situations packaging is not sensible, but it's wise to package + software in so many circumstances that it's worth checking for it. - Packaging your project is essential for users to receive updates and security patches automatically. A low score is considered `Medium` risk. The check currently looks for [GitHub packaging workflows]( https://docs.github.com/en/packages/learn-github-packages/publishing-a-package) and language-specific GitHub Actions that upload the package to a corresponding hub, e.g., [Npm](https://www.npmjs.com/). There is a plan to add better support to query package manager hubs directly in the future, e.g., for [Npm](https://www.npmjs.com/), [PyPi](https://pypi.org/). + A project may meet this criterion yet have a failing scorecard report; + some widely-used tools are relatively easy to detect, but it's + challenging for an automated tool (like scorecard) to detect + them all. + If scorecard fails to detect the way you publish a package and + you think scorecard should support your use case, please + [open an issue in the scorecard project](https://github.com/ossf/scorecard/issues/new/choose). remediation: - Publish your project as a [downloadable package](https://docs.github.com/en/packages/learn-github-packages/publishing-a-package). - Use a GitHub action to release your package to language-specific hubs.