README: Replace local contrib docs with a CONTRIBUTING.md link #9
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
wking
force-pushed
the
drop-readme-contrib-docs
branch
from
b023a0b to
724ab29
Compare
stevvooe
reviewed
Apr 11, 2018
| @@ -24,116 +24,7 @@ Following sections give context for aspects of this specification: | |||
|
|
|||
| ## Contributing | |||
|
|
|||
There was a problem hiding this comment.
This should at least provide a link to the issue tracker and mailing list so users don't need to wade through several docs before finding basic information. The longer form stuff is definitely part of contributing.
There was a problem hiding this comment.
This should at least provide a link to the issue tracker and mailing list…
Done with 724ab29 → 2bbc5c1, using text copy/pasted from CONTRIBUTING.md. If you have specific wording in mind, give me something to copy/paste ;).
If you're concerned about skimmers reading some of the contribution information (e.g. the issues link in the README with 2bbc5c1) and submitting security issues over those public channels, you may want to add a reference to the security section as well. For a paranoid approach to this “skimmed and missed the security section” issue, see opencontainers/project-template#57.
There was a problem hiding this comment.
submitting security issues over those public channels, you may want to add a reference to the security section as well.
Please do add this.
wking
force-pushed
the
drop-readme-contrib-docs
branch
from
724ab29 to
2632b29
Compare
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
force-pushed
the
drop-readme-contrib-docs
branch
from
2632b29 to
2bbc5c1
Compare
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>
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>
wking
force-pushed
the
drop-readme-contrib-docs
branch
from
2bbc5c1 to
fa939cc
Compare
|
LGTM |
1 similar comment
|
LGTM |
sudo-bmitch
added a commit
to sudo-bmitch/distribution-spec
that referenced
this pull request
Aug 10, 2022
Add filtering to references API
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.
CONTRIBUTING.md(which we got from project-template in be21fe9, #3) covers this same space. Dropping the contrib docs from the README (and instead linking toCONTRIBUTING.md):CONTRIBUTING.mdand not linking from the README), andCC @vbatts, since the README contrib docs came in with his #6.