|
| 1 | +# Contributing |
| 2 | + |
| 3 | +The Ember Guides are maintained and updated by an all-volunteer group of Ember community members. We'd love to have you join our efforts! Here are a few ways you can help: |
| 4 | + |
| 5 | +* _Fixing problems_: If you find a problem on a particular page in the Guides, the most helpful thing you can do is open a pull request. If you're not sure how to fix it, open an issue. |
| 6 | +* _Contributing requested content_: We try to make it easy for people to contribute to the Guides by tagging issues with [help wanted](https://github.com/ember-learn/guides-source/issues?q=is%3Aopen+is%3Aissue+label%3A%22help+wanted%22) when appropriate. The best way to get started contributing content is to pick up one of these issues. |
| 7 | +Add a comment to let the maintainers know that you're interested, and post any questions you may have. |
| 8 | +* _Contributing unsolicited content_: If you'd like to contribute content that you think is missing, please start by checking the issues page. There may already be a plan to add this content! If not, open an issue yourself so that you can get feedback before you start writing. Our core contributors may ask you to start off by writing a blog post on your topic instead of or before opening a pull request on the Guides. This helps us keep the Guides consistent and streamlined. |
| 9 | +* _Writing infrastructure code_: You can also help out with the Guides by improving the code for the app that is used to build the content. Issues related to writing infrastructure code and layout should be made on the [guides-app](https://github.com/ember-learn/guides-app) repository. |
| 10 | + |
| 11 | +Please note that no attempt is made to update content for older versions of the Guides. Except for broken links, they are considered static and immutable, as it is too difficult to maintain content for every version ever released. Issues will only be fixed for future releases. |
| 12 | + |
| 13 | +## Making Your First Pull Request |
| 14 | + |
| 15 | +First-time contributors are encouraged to choose issues that are labeled |
| 16 | +"help wanted" or "good for new contributors." If you have questions, want a |
| 17 | +suggestion of what to work on, or would like a buddy to pair with, you can |
| 18 | +join the #-team-learning channel in the |
| 19 | +[Ember Community Slack](https://ember-community-slackin.herokuapp.com/). |
| 20 | + |
| 21 | +Fork this repository (click "fork" on the repository's home page in GitHub) |
| 22 | + |
| 23 | +Clone the forked repository with `git clone <your fork's url>` and create a |
| 24 | +branch with `git checkout -b some-branch-name`. |
| 25 | + |
| 26 | +As you make commits, reference the issue number in your commit message, such as |
| 27 | +`git commit -m "add glasses to nearsighted hamster (#6217)"` |
| 28 | + |
| 29 | +Once you're at the point that you'd like feedback, submit a Pull Request (new |
| 30 | +Pull Request button). Choose `master` for the base and your branch name for `compare`, |
| 31 | +then submit it! |
| 32 | + |
| 33 | +Your PR will be reviewed by another contributor, and then either merged or have |
| 34 | +changes requested. |
| 35 | + |
| 36 | +## Keeping your fork updated |
| 37 | + |
| 38 | +As you tackle new Issues, you'll want to be sure that you always start by working |
| 39 | +on the most recent code. To sync up your fork's `master` with a parent repository's |
| 40 | +master, set an upstream and pull from it. For this to work, you should make sure |
| 41 | +you're always committing to a branch, not master. |
| 42 | + |
| 43 | +``` |
| 44 | +git remote add upstream https://github.com/ember-learn/guides-source.git |
| 45 | +git checkout master |
| 46 | +git pull upstream master |
| 47 | +``` |
| 48 | + |
| 49 | +## Style Guide |
| 50 | + |
| 51 | +Before you open a PR with anything but a minor fix, please familiarize yourself with this style guide so that we can ensure a high quality, consistent style of writing throughout the documentation. |
| 52 | + |
| 53 | +- The **Guides** refers to the entire Ember Guides project. Here, _Guides_ is capitalized. |
| 54 | +- A **guide** is one page of the Guides, for example "Defining Your Routes". Here, _guide_ is lowercase. |
| 55 | +- A **section** is one of the top-level grouping of several guides, for example "Routing". |
| 56 | + |
| 57 | +Write in complete sentences. Use a friendly tone of voice. Use American English. Use gender-neutral pronouns - for example, "Is the user logged in? Are _they_ an admin user?" Use title case for all titles and headers. If English is not your native language and you aren't sure about any of these, don't hesitate to ask for help in your pull request! |
| 58 | + |
| 59 | +Be as brief as possible, but don't sacrifice clarity for brevity. If a guide is more than a couple screens of scrolling, consider breaking it into multiple pages. |
| 60 | + |
| 61 | +The target audience of the Guides are developers whose skills range from beginner developer with perhaps some jQuery experience, to experienced Ember developer learning about a new feature. Be sure to write content that covers both of their needs: keep explanations thorough enough for the beginner, while including more advanced topics for the experienced developer. |
| 62 | + |
| 63 | +The Guides are primarily meant to cover the "Ember happy path", and are not intended to be comprehensive. Leave edge cases and rarely-used features to the API documentation. Start each guide and each section with the simplest, most commonly-used features, and progress to the more advanced and less commonly-used features. |
| 64 | + |
| 65 | +Each guide should thoroughly explain the feature it documents, and include links to the API documentation. Links to authoritative sources of information on background concepts are also encouraged: for example, the _Handlebars Basics_ guide appropriately links to http://handlebarsjs.com/. Do not link to other outside content like blog posts or meetup slides, as reviewing and updating this content is better suited for content aggregators. |
| 66 | + |
| 67 | +Liberally use examples in your writing. For example, the sentence "Templates can contain expressions in double curly braces" should be expanded to something like "Templates can contain expressions in double curly braces, such as \`<h1>Welcome {{user.name}}</h1>\`" A short example is often more clear than a long explanation. In fact, it is often helpful to give two examples to make things even clearer. |
| 68 | + |
| 69 | +When writing prose: |
| 70 | + |
| 71 | +* Use a single space after periods. |
| 72 | +* Manually break lines: |
| 73 | + * at the beginning of every new sentence; |
| 74 | + * after the last comma in sentences over 120 characters; or |
| 75 | + * after logical statements in sentences over 120 characters with no commas. |
| 76 | + |
| 77 | +In code samples: |
| 78 | + |
| 79 | +* Follow the [Ember Style Guide](https://github.com/emberjs/ember.js/blob/master/STYLEGUIDE.md). |
| 80 | +* Use double-quotes in templates, i.e., `<div class="awesome">{{foo-bar title="Tomster"}}</div>`. |
| 81 | +* Omit the boilerplate that Ember CLI generates, especially the `import Ember from 'ember'` at the top of every file. |
| 82 | +* In fenced code blocks, include the filename or language after the triple-backticks, like <code>```routes/kittens.js</code> or <code>```hbs</code>. |
| 83 | +* Write paths relative to the project root. |
| 84 | + |
| 85 | +When linking to API pages: |
| 86 | + |
| 87 | +* use code backticks as part of the link text, i.e., \[<code>`store.push()`</code>] |
| 88 | +(api link) |
| 89 | +* include parenthesis when linking to an API method, i.e., <code>`store.push()`</code> |
| 90 | + |
| 91 | +Write once, edit twice (at least!) before opening a PR. When you edit your own writing, ask yourself: |
| 92 | + |
| 93 | +* Am I using proper grammar and spelling? |
| 94 | +* Can I clarify or simplify any of my explanations or examples? |
| 95 | +* Have I included clear examples of everything I am documenting? |
| 96 | +* Did I include links where appropriate? |
| 97 | + |
| 98 | +You'll be amazed at how much better your writing gets as you edit and re-edit! |
0 commit comments