CONTRIBUTING: Lead off with the security section #57
Conversation
This file contains 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
This reduces the chances that a skimmer reads "Issues are used for bugs..." and files an issue without scrolling down to see the security section. I've also added links back to the security section from the all other paragraphs that suggest using other channels (issues, pull requests, IRC, ...), so that no matter which anchor a skimmer starts at, they cannot miss the fact that we have a special disclosure procedure for security issues. If we are confident that readers interested in submitting a security issue will not start at a mid-document anchor without reading the beginning of this file, we could drop some or all of these back-refs. Also adjust the lines I touch to use one line per sentence, since that's the standard in other OCI Projects (like the runtime spec [1]). [1]: https://github.com/opencontainers/runtime-spec/blob/v1.0.1/style.md#one-sentence-per-line Signed-off-by: W. Trevor King <wking@tremily.us>
wking
added a commit
to wking/distribution-spec
that referenced
this pull request
Apr 11, 2018
CONTRIBUTING.md (which we got from project-template in be21fe9, *: Pull in project-template 61d73a3, 2018-04-04, opencontainers#3) covers this same space. Dropping the contrib docs from the README (and instead linking to CONTRIBUTING.md) keeps us DRY (vs. having the content in each location), gets us the GitHub contributing UI improvements [1] (vs. having the content only in the README), keeps the information discoverable (vs. having the content only in CONTRIBUTING and not linking from the README), and gives us more space in the README to talk about the project itself (contributing docs are only useful for a subset of README readers). I've copy/pasted the CONTRIBUTING.md content for issues and the mailing list into the README at Stephen's request [2]. Personally I don't have a problem with requiring readers to click through to CONTRIBUTING to get this information, but I'm not a maintainer. I am slightly concerned that the copy/pasted discussion channel information is even further from the security-disclosure section (for a paranoid approach, see [3]), but I'll leave addressing that or not up to the maintainers as well. [1]: https://help.github.com/articles/setting-guidelines-for-repository-contributors/ [2]: opencontainers#9 (comment) [3]: opencontainers/project-template#57 Signed-off-by: W. Trevor King <wking@tremily.us>
wking
added a commit
to wking/distribution-spec
that referenced
this pull request
Apr 11, 2018
CONTRIBUTING.md (which we got from project-template in be21fe9, *: Pull in project-template 61d73a3, 2018-04-04, opencontainers#3) covers this same space. Dropping the contrib docs from the README (and instead linking to CONTRIBUTING.md) keeps us DRY (vs. having the content in each location), gets us the GitHub contributing UI improvements [1] (vs. having the content only in the README), keeps the information discoverable (vs. having the content only in CONTRIBUTING and not linking from the README), and gives us more space in the README to talk about the project itself (contributing docs are only useful for a subset of README readers). I've copy/pasted the CONTRIBUTING.md content for issues and the mailing list into the README at Stephen's request [2], turning "Issues" into a link in the process. I've left it as a non-link in CONTRIBUTING.md to stay closer to the upstream project-template, but wouldn't have a problem making it a link there to if the maintainers preferred that. Personally I don't have a problem with requiring readers to click through to CONTRIBUTING to get this information, but I'm not a maintainer. I am slightly concerned that the copy/pasted discussion channel information is even further from the security-disclosure section (for a paranoid approach, see [3]), but I'll leave addressing that or not up to the maintainers as well. [1]: https://help.github.com/articles/setting-guidelines-for-repository-contributors/ [2]: opencontainers#9 (comment) [3]: opencontainers/project-template#57 Signed-off-by: W. Trevor King <wking@tremily.us>
wking
added a commit
to wking/distribution-spec
that referenced
this pull request
Apr 11, 2018
CONTRIBUTING.md (which we got from project-template in be21fe9, *: Pull in project-template 61d73a3, 2018-04-04, opencontainers#3) covers this same space. Dropping the contrib docs from the README (and instead linking to CONTRIBUTING.md) keeps us DRY (vs. having the content in each location), gets us the GitHub contributing UI improvements [1] (vs. having the content only in the README), keeps the information discoverable (vs. having the content only in CONTRIBUTING and not linking from the README), and gives us more space in the README to talk about the project itself (contributing docs are only useful for a subset of README readers). I've copy/pasted the CONTRIBUTING.md content for issues and the mailing list into the README at Stephen's request [2], turning "Issues" into a link in the process and making some other minor copy-edits. I've left it as a non-link in CONTRIBUTING.md to stay closer to the upstream project-template, but wouldn't have a problem making it a link there to if the maintainers preferred that. I've also added a security reference based on my in-flight [3], also at Stephen's request [4]. Personally I don't have a problem with requiring readers to click through to CONTRIBUTING to get this information (as long as the security information stays close to the information for other channels [3]), but I'm not a maintainer. [1]: https://help.github.com/articles/setting-guidelines-for-repository-contributors/ [2]: opencontainers#9 (comment) [3]: opencontainers/project-template#57 [4]: opencontainers#9 (comment) Signed-off-by: W. Trevor King <wking@tremily.us>
cyphar
reviewed
Apr 12, 2018
| @@ -20,25 +26,24 @@ Minutes from past meetings are archived [here][minutes]. | |||
| ## Mailing list | |||
|
|
|||
| You can subscribe and browse the mailing list on [Google Groups][mailing-list]. | |||
| Responsible disclosure for security issues is discussed [above](#security-issues). | |||
There was a problem hiding this comment.
I don't think you need to repeat this sentence in every section. Just expand the opening line to say "do not create an issue, file a pull request, send a public message on the mailing list or IRC, or discuss it in the monthly meeting".
There was a problem hiding this comment.
I don't think you need to repeat this sentence in every section.
Right, that's:
If we are confident that readers interested in submitting a security issue will not start at a mid-document anchor without reading the beginning of this file, we could drop some or all of these back-refs.
from my initial post. Are you confident that folks with a security issue will notice the opening section of this file, even if they find it via a .../CONTRIBUTING.md#mailing-list link (for example)? You could also make this argument more narrowly, and say something like:
We don't need a back-ref from the mailing list section. Both it and the following IRC section are short, so even a hasty mailing-list-section skimmer is likely to notice the IRC-section back-ref.
But I'm fine droping whichever back-refs folks want me to drop. Do you want me to drop all of them? Or just from a few sections? Or maybe we can get a security ref that sticks to the top of the browser window (something like this if GitHub won't strip that out).
There was a problem hiding this comment.
Or maybe we can get a security ref that sticks to the top of the browser window (something like this if GitHub won't strip that out).
This is a no-go, because GitHub strips style attributes.
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.
This reduces the chances that a skimmer reads “Issues are used for bugs…” and files an issue without scrolling down to see the security section.
I've also added links back to the security section from the all other paragraphs that suggest using other channels (issues, pull requests, IRC, …), so that no matter which anchor a skimmer starts at, they cannot miss the fact that we have a special disclosure procedure for security issues. If we are confident that readers interested in submitting a security issue will not start at a mid-document anchor without reading the beginning of this file, we could drop some or all of these back-refs.
Also adjust the lines I touch to use one line per sentence, since that's the standard in other OCI Projects (like the runtime spec).