Skip to content

Commit

Permalink
refactor CONTRIBUTING.md into multiple files to help readability (cnc…
Browse files Browse the repository at this point in the history 
…f#722)

* create a directory to make it so we can refactor into a few files to help readability

Co-authored-by: Brandon Lum <[email protected]>
  • Loading branch information
@ultrasaurus @lumjjb
ultrasaurus and lumjjb authored Jul 15, 2021
1 parent 48bfbe7 commit a54fffe
Show file tree
Hide file tree
Showing 3 changed files with 83 additions and 69 deletions.
37 changes: 37 additions & 0 deletions CONTRIBUTING/README.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,37 @@
# Contributing

We aspire to create a welcoming environment for collaboration on this project
and ask that all contributors do the same. For more details, see our [code of
conduct](/CODE-OF-CONDUCT.md).

This document covers contributions to this git repository. Please review
[governance](/governance) for our mission, charter, and other operations.

## Open source

While this repository does not contain open source code, we manage content
contributions following open source practice, as detailed below.

All contributions to this project will be released under open source license as
described in [LICENSE.md](/LICENSE.md). By submitting a pull request (PR),
you are agreeing to release the PR contents under this license.

## Communication

Anyone interested in contributing should join the mailing list and other
[communication channels](/README.md#Communications)

We strongly encourage and support all our members to participate in anyway
they can. Not everyone can participate in the regularly scheduled live meetings,
so we strive to make our processes friendly for people to be active contributors
through asynchronous communication and contributions to our documentation
in this repository.

## Github pull requests and issues

If you are new to the group, [reviewing pull requests](pull-request-review.md)
and commenting on issues is a great way to get involved!

When creating or reviewing pull requests, please refer to the
[writing style guide](writing-style.md) to help maintain consistency across
all of our documents.
73 changes: 4 additions & 69 deletions CONTRIBUTING.md → CONTRIBUTING/pull-request-review.md
View file
Original file line number Diff line number Diff line change
@@ -1,31 +1,4 @@
# Contributing

We aspire to create a welcoming environment for collaboration on this project
and ask that all contributors do the same. For more details, see our [code of
conduct](CODE-OF-CONDUCT.md).

This document covers contributions to this git repository. Please review
[governance](governance) for our mission, charter, and other operations.

## Open source

While this repository does not contain open source code, we manage content
contributions following open source practice, as detailed below.

All contributions to this project will be released under open source license as
described in [LICENSE.md](LICENSE.md). By submitting a pull request (PR),
you are agreeing to release the PR contents under this license.

## Communication

Anyone interested in contributing should join the mailing list and other
[communication channels](README.md#Communications)

## Reviewing Pull Requests

If you are new to the group, reviewing pull requests and commenting on issues is
a great way to get involved! We strongly encourage and support all our members
to participate in anyway they can.
# Pull Request (PR) reviews

Except for urgent or very small grammar or spelling fixes, such as simple
changes discussed below, we leave pull requests open for at least 24 hours, so
Expand Down Expand Up @@ -85,7 +58,7 @@ A person with access, including the PR author, may then perform the merge.
A person with access, other than the PR author, can both review **and** merge a
PR if found favorable after review.

[Code owners](CODEOWNERS) need to be at least one concurring reviewer or the
[Code owners](/CODEOWNERS) need to be at least one concurring reviewer or the
merging party.

#### Significant changes
Expand All @@ -105,49 +78,11 @@ and provide concurrence prior to merging.
Two persons with access, other than the PR author, must review the PR and
provide concurrence, the last of which should perform the merge.

[Code owners](CODEOWNERS) need to be at least one concurring reviewer or the
[Code owners](/CODEOWNERS) need to be at least one concurring reviewer or the
merging party.

### Merging pull requests

PRs may be merged after at least one review as occurred, dependent on the type
of changes reflected in the PR. The merging party needs to verify a review has
occurred, the PR is in alignment with this guide, and is in scope of the TAG.

### Writing style

Consistency creates clarity in communication.

<!-- cSpell:ignore usecase --->
* Common terms
* When referring to users and use cases, ensure consistency with
[use cases](usecase-personas/)
* See [CNCF Style Guide][cncf-style] for common terms. Note that the following
terms are not hyphenated and all lower case, except for capitalizing the
first letter when at the beginning of a sentence:
* open source
* cloud native
* Additional formatting
* Headlines, page titles, subheads and similar content should follow sentence
case, and should not include a trailing colon.
* Paragraphs do not start with leading indent.
* Wrap lines at 80 characters, except where it would break a link. No need to
reformat the whole paragraph to make it perfect -- fewer diffs are easier
for reviewers.
* File & directory naming conventions
* Every directory should have a README.md with useful introductory text.
* All other file and directory names should be all lower case with dashes to
separate words.

If you find yourself correcting for consistency, please propose additional style
guidelines via pull request to this document. Feel free to add references to
good sources for content guidelines below.

Sources:

<!-- cSpell:ignore Opps --->
* [OpenOpps Contribution Guide][openopps-style]
* [18F Content Guide](https://content-guide.18f.gov/)

[cncf-style]: https://github.com/cncf/foundation/blob/master/style-guide.md
[openopps-style]: https://github.com/openopps/openopps-platform/blob/master/CONTRIBUTING.md
occurred, the PR is in alignment with this guide, and is in scope of the TAG.
42 changes: 42 additions & 0 deletions CONTRIBUTING/writing-style.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,42 @@
# Writing style

Consistency creates clarity in communication.

If you find yourself correcting for consistency, please propose additional style
guidelines via pull request to this document. Feel free to add references to
good sources for content guidelines at the bottom of this guide.

<!-- cSpell:ignore usecase --->
## Common terms

* When referring to users and use cases, ensure consistency with
[use cases](/usecase-personas/)
* See [CNCF Style Guide][cncf-style] for common terms. Note that the following
terms are not hyphenated and all lower case, except for capitalizing the
first letter when at the beginning of a sentence:
* open source
* cloud native

## Additional formatting

* Headlines, page titles, subheads and similar content should follow sentence
case, and should not include a trailing colon.
* Paragraphs do not start with leading indent.
* Wrap lines at 80 characters, except where it would break a link. No need to
reformat the whole paragraph to make it perfect -- fewer diffs are easier
for reviewers.

## File & directory naming conventions

* Every directory should have a README.md with useful introductory text.
* All other file and directory names should be all lower case with dashes to
separate words.

## Sources

<!-- cSpell:ignore Opps --->
* [OpenOpps Contribution Guide][openopps-style]
* [18F Content Guide](https://content-guide.18f.gov/)

[cncf-style]: https://github.com/cncf/foundation/blob/master/style-guide.md
[openopps-style]: https://github.com/openopps/openopps-platform/blob/master/CONTRIBUTING.md

0 comments on commit a54fffe

Please sign in to comment.