📖 Improve text on Packaging (#1035)

* 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 <[email protected]>

* 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 <[email protected]>

Author: david-a-wheeler

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.