Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions _articles/en-US/best-practices.md
Original file line number Diff line number Diff line change
Expand Up @@ -67,8 +67,8 @@ Here are a few rules that are worth writing down:

* How a contribution is reviewed and accepted (_Do they need tests? An issue template?_)
* The types of contributions you'll accept (_Do you only want help with a certain part of your code?_)
* When it's appropriate to follow up (_ex. "You can expect a response from a maintainer within 7 days. If you haven't heard anything by then, feel free to ping the thread."_)
* How much time you spend on the project (_ex. "We only spend about 5 hours per week on this project"_)
* When it's appropriate to follow up (_for example, "You can expect a response from a maintainer within 7 days. If you haven't heard anything by then, feel free to ping the thread."_)
* How much time you spend on the project (_for example, "We only spend about 5 hours per week on this project"_)

[Jekyll](https://github.com/jekyll/jekyll/tree/master/docs), [CocoaPods](https://github.com/CocoaPods/CocoaPods/wiki/Communication-&-Design-Rules), and [Homebrew](https://github.com/Homebrew/brew/blob/bbed7246bc5c5b7acb8c1d427d10b43e090dfd39/docs/Maintainers-Avoiding-Burnout.md) are several examples of projects with ground rules for maintainers and contributors.

Expand Down
10 changes: 5 additions & 5 deletions _articles/en-US/how-to-contribute.md
Original file line number Diff line number Diff line change
Expand Up @@ -193,7 +193,7 @@ Finally, open source projects use the following tools to organize discussion. Re

* **Issue tracker:** Where people discuss issues related to the project.
* **Pull requests:** Where people discuss and review changes that are in progress.
* **Discussion forums or mailing lists:** Some projects may use these channels for conversational topics (ex. _"How do I..."_ or _"What do you think about..."_ instead of bug reports or feature requests). Others use the issue tracker for all conversations.
* **Discussion forums or mailing lists:** Some projects may use these channels for conversational topics (for example, _"How do I..."_ or _"What do you think about..."_ instead of bug reports or feature requests). Others use the issue tracker for all conversations.
* **Synchronous chat channel:** Some projects use chat channels (such as Slack or IRC) for casual conversation, collaboration, and quick exchanges.

## Finding a project to contribute to
Expand Down Expand Up @@ -353,7 +353,7 @@ A project that is friendly and welcoming signals that they will be receptive to
<div class="clearfix mb-2">
<input type="checkbox" id="cbox15" class="d-block float-left mt-1 mr-2" value="checkbox">
<label for="cbox15" class="overflow-hidden d-block text-normal">
Are people friendly in the issues, discussion forum, and chat (ex. IRC or Slack)?
Are people friendly in the issues, discussion forum, and chat (for example, IRC or Slack)?
</label>
</div>

Expand Down Expand Up @@ -462,7 +462,7 @@ If you want to make a substantial contribution, open an issue to ask before work
You should usually open an issue in the following situations:

* Report an error you can't solve yourself
* Discuss a high-level topic or idea (ex. community, vision, policies)
* Discuss a high-level topic or idea (for example, community, vision or policies)
* Propose a new feature or other project idea

Tips for communicating on issues:
Expand All @@ -475,7 +475,7 @@ Tips for communicating on issues:

You should usually open a pull request in the following situations:

* Submit trivial fixes (ex. a typo, broken link, or obvious error)
* Submit trivial fixes (for example, a typo, a broken link or an obvious error)
* Start work on a contribution that was already asked for, or that you've already discussed, in an issue

A pull request doesn't have to represent finished work. It's usually better to open a pull request early on, so others can watch or give feedback on your progress. Just mark it as a "WIP" (Work in Progress) in the subject line. You can always add more commits later.
Expand All @@ -484,7 +484,7 @@ If the project is on GitHub, here's how to submit a pull request:

* **[Fork the repository](https://guides.github.com/activities/forking/)** and clone it locally. Connect your local to the original "upstream" repository by adding it as a remote. Pull in changes from "upstream" often so that you stay up to date so that when you submit your pull request, merge conflicts will be less likely. (See more detailed instructions [here](https://help.github.com/articles/syncing-a-fork/).)
* **[Create a branch](https://guides.github.com/introduction/flow/)** for your edits.
* **Reference any relevant issues** or supporting documentation in your PR (ex. "Closes #37.")
* **Reference any relevant issues** or supporting documentation in your PR (for example, "Closes #37.")
* **Include screenshots of the before and after** if your changes include differences in HTML/CSS. Drag and drop the images into the body of your pull request.
* **Test your changes!** Run your changes against any existing tests if they exist and create new ones when needed. Whether tests exist or not, make sure your changes don't break the existing project.
* **Contribute in the style of the project** to the best of your abilities. This may mean using indents, semi-colons or comments differently than you would in your own repository, but makes it easier for the maintainer to merge, others to understand and maintain in the future.
Expand Down
2 changes: 1 addition & 1 deletion _articles/en-US/leadership-and-governance.md
Original file line number Diff line number Diff line change
Expand Up @@ -66,7 +66,7 @@ For a smaller project, designating leaders can be as simple as adding their name

For a bigger project, if you have a website, create a team page or list your project leaders there. For example, [Postgres](https://github.com/postgres/postgres/) has a [comprehensive team page](https://www.postgresql.org/community/contributors/) with short profiles for each contributor.

If your project has a very active contributor community, you might form a "core team" of maintainers, or even subcommittees of people who take ownership of different issue areas (ex. security, issue triaging, or community conduct). Let people self-organize and volunteer for the roles they're most excited about, rather than assigning them.
If your project has a very active contributor community, you might form a "core team" of maintainers, or even subcommittees of people who take ownership of different issue areas (for example, security, issue triaging, or community conduct). Let people self-organize and volunteer for the roles they're most excited about, rather than assigning them.

<aside markdown="1" class="pquote">
\[We\] supplement the core team with several "subteams". Each subteam is focused on a specific area, e.g., language design or libraries. (...) To ensure global coordination and a strong, coherent vision for the project as a whole, each subteam is led by a member of the core team.
Expand Down
4 changes: 2 additions & 2 deletions _articles/en-US/starting-a-project.md
Original file line number Diff line number Diff line change
Expand Up @@ -230,7 +230,7 @@ Pick a name that is easy to remember and, ideally, gives some idea of what the p
* [Sentry](https://github.com/getsentry/sentry) monitors apps for crash reporting
* [Thin](https://github.com/macournoyer/thin) is a fast and simple Ruby web server

If you're building upon an existing project, using their name as a prefix can help clarify what your project does (ex. [node-fetch](https://github.com/bitinn/node-fetch) brings `window.fetch` to Node.js).
If you're building upon an existing project, using their name as a prefix can help clarify what your project does (for example, [node-fetch](https://github.com/bitinn/node-fetch) brings `window.fetch` to Node.js).

Consider clarity above all. Puns are fun, but remember that some jokes might not translate to other cultures or people with different experiences from you. Some of your potential users might be company employees: you don't want to make them uncomfortable when they have to explain your project at work!

Expand Down Expand Up @@ -319,7 +319,7 @@ Ready to open source your project? Here's a checklist to help. Check all the box
<div class="clearfix mb-4">
<input type="checkbox" id="cbox7" class="d-block float-left mt-1 mr-2" value="checkbox">
<label for="cbox7" class="overflow-hidden d-block text-normal">
There are no sensitive materials in the revision history, issues, or pull requests (ex. passwords or other non-public information)
There are no sensitive materials in the revision history, issues, or pull requests (for example, passwords or other non-public information)
</label>
</div>

Expand Down
4 changes: 2 additions & 2 deletions docs/content-model.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,11 +12,11 @@ Everything written in the guides should fall into one of the following categorie

## Concept Guides

Concept guides dive deep into a specific topic (ex. "Building a community", "Measuring success"). They may contain visuals and anecdotes to illustrate their point. While meant to be read from beginning to end, they have a table of contents to help the reader quickly skim the content and find a relevant subsection.
Concept guides dive deep into a specific topic (for example, "Building a community" or "Measuring success"). They may contain visuals and anecdotes to illustrate their point. While meant to be read from beginning to end, they have a table of contents to help the reader quickly skim the content and find a relevant subsection.

## FAQ

An FAQ tackles a complex topic where a reader is likely coming in with specific questions (ex. "The legal side of open source", "Leadership & governance"). Whereas concept guides aim to teach the entire concept, an FAQ respects a reader's desire to jump around, get the information they need, and leave. The table of contents is especially important in an FAQ, because the page isn't meant to be read from beginning to end. FAQs might also be longer than a concept guide, because of the jump-around navigation.
An FAQ tackles a complex topic where a reader is likely coming in with specific questions (for example, "The legal side of open source" or "Leadership & governance"). Whereas concept guides aim to teach the entire concept, an FAQ respects a reader's desire to jump around, get the information they need, and leave. The table of contents is especially important in an FAQ, because the page isn't meant to be read from beginning to end. FAQs might also be longer than a concept guide, because of the jump-around navigation.

## Design Elements

Expand Down