📖 Improve text on Packaging #1035
Merged
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
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 ossf#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 <dwheeler@dwheeler.com>
|
license boilerplate check failed, I think that's a borken test not an actual problem. |
|
@naveensrinivasan : Can you check on the "license boilerplate check"? It fails bizarrely with |
I re-ran the check, it should hopefully fix it. |
laurentsimon
approved these changes
Sep 16, 2021
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 <dwheeler@dwheeler.com>
|
@david-a-wheeler Is it good to be merged? |
|
@naveensrinivasan : Yes, it's ready for merging! Go for it! |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Make various improvements to the text on packaging.
packages, which is absurd; end-users install software packages all
the time.
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.
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 case 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-docsas that would add otherirrelevant changes. Instead, after this PR is accepted there should be a
make generate-docs& a pull of that.Signed-off-by: David A. Wheeler dwheeler@dwheeler.com