1 | # Getting Involved
|
2 |
|
3 | There are many ways to contribute to the project, you can fix issues,
|
4 | improve documentation or work on any of the features on the
|
5 | [wish list](https://github.com/ember-cli/ember-cli/wiki/Wish-List).
|
6 |
|
7 | # Questions
|
8 |
|
9 | This is the issue tracker for `ember-cli`. The community uses this site
|
10 | to collect and track bugs and discussions of new features. If you are
|
11 | having difficulties using `ember-cli` or have a question about usage
|
12 | please ask a question on Stack Overflow: https://stackoverflow.com/questions/ask?tags=ember-cli
|
13 |
|
14 | # Issues
|
15 |
|
16 | Think you've found a bug or have a new feature to suggest? Let us know!
|
17 |
|
18 | ## Slow builds?
|
19 |
|
20 | Please be sure to review [The Perf Guide](https://github.com/ember-cli/ember-cli/blob/master/PERF_GUIDE.md) (and implement its recommendations) before posting an issue.
|
21 |
|
22 | ## Reporting a Bug
|
23 |
|
24 | 1. Update to the most recent master release if possible. We may have already
|
25 | fixed your bug.
|
26 |
|
27 | 2. Search for similar issues. It's possible somebody has encountered this bug
|
28 | already.
|
29 |
|
30 | 3. Provide a demo that specifically shows the problem. This demo should be fully
|
31 | operational with the exception of the bug you want to demonstrate. The more
|
32 | pared down, the better. Issues with demos are prioritized.
|
33 |
|
34 | 4. Your issue will be verified. The provided demo will be tested for
|
35 | correctness. The ember-cli team will work with you until your issue can be
|
36 | verified.
|
37 |
|
38 | 5. Keep up to date with feedback from the ember-cli team on your ticket. Your
|
39 | ticket may be closed if it becomes stale.
|
40 |
|
41 | 6. If possible, submit a Pull Request with a failing test. Better yet, take
|
42 | a stab at fixing the bug yourself if you can!
|
43 |
|
44 | The more information you provide, the easier it is for us to validate that
|
45 | there is a bug and the faster we'll be able to take action.
|
46 |
|
47 | Be sure to include (At the very least):
|
48 |
|
49 | * OS
|
50 | * npm version
|
51 | * ember version
|
52 | * clear steps to reproduction
|
53 |
|
54 | And ideally
|
55 |
|
56 | * an isolated demonstration of this issue as a github repo
|
57 |
|
58 | ## Requesting a Feature
|
59 |
|
60 | Feature requests are handled via https://github.com/ember-cli/rfcs
|
61 |
|
62 | * issues are eargley stage requests/proposals
|
63 | * rfcs as pull requests are for fleshing out details
|
64 |
|
65 | 1. Search Issues for similar feature requests. It's possible somebody has
|
66 | already asked for this feature or provided a pull request that we're still
|
67 | discussing.
|
68 |
|
69 | 2. Provide a clear and detailed explanation of the feature you want and why it's
|
70 | important to add. Keep in mind that we want features that will be useful to
|
71 | the majority of our users and not just a small subset. If you're just
|
72 | targeting a minority of users, consider writing an addon library for
|
73 | `ember-cli`.
|
74 |
|
75 | 3. If the feature is complex, consider writing some initial documentation for
|
76 | it. If we do end up accepting the feature it will need to be documented and
|
77 | this will also help us to understand it better ourselves.
|
78 |
|
79 | 4. Attempt a Pull Request. If you are willing to help the project out, you can
|
80 | submit a Pull Request. We always have more work to do than time to do it. If
|
81 | you can write some code then that will speed the process along.
|
82 |
|
83 | # Pull Requests
|
84 |
|
85 | We love pull requests. Here's a quick guide:
|
86 |
|
87 | 1. Fork the repo.
|
88 |
|
89 | 2. Ensure you have the development requirements:
|
90 |
|
91 | * node (latest LTS recommended) -- *do not install node using sudo*
|
92 | * npm (3.x)
|
93 | * google chrome
|
94 |
|
95 | 3. Run the tests. We only take pull requests with passing tests, and it's great
|
96 | to know that you have a clean slate: `npm install && npm run test:all`.
|
97 |
|
98 | 4. Add a test for your change. Only refactoring and documentation changes
|
99 | require no new tests. If you are adding functionality or fixing a bug, we
|
100 | need a test!
|
101 |
|
102 | 5. Make the test pass.
|
103 |
|
104 | 6. Commit your changes. If your pull request fixes an issue specify it in the
|
105 | commit message. Here's an example: `git commit - m "Close #52 Fix
|
106 | generators"`
|
107 |
|
108 | 7. Push to your fork and submit a pull request. In the pull-request title,
|
109 | please prefix it with one of our tags: BUGFIX, FEATURE, ENHANCEMENT or
|
110 | INTERNAL
|
111 |
|
112 | * FEATURE and ENHANCEMENT tags are for things that users are interested in.
|
113 | Avoid super technical talk. Craft a concise description of the change.
|
114 | - FEATURE tag is a standalone new addition, an example of this would be
|
115 | adding a new command
|
116 | - ENHANCEMENT tag is an improvement on an existing feature
|
117 | * BUGFIX tag is a link to a bug + a link to a patch.
|
118 | * INTERNAL tag is an internal log of changes.
|
119 |
|
120 | In the description, please provide us with some explanation of why you made
|
121 | the changes you made. For new features make sure to explain a standard use
|
122 | case to us.
|
123 |
|
124 | If a change requires a user to change their configuration, `bower.json`,
|
125 | `package.json` or `Brocfile.js` also add a BREAKING tag within the brackets
|
126 | before any other tags (example [BREAKING BUGFIX]).
|
127 |
|
128 | We try to be quick about responding to tickets but sometimes we get a bit
|
129 | backlogged. If the response is slow, try to find someone on IRC(#ember-cli) to
|
130 | give the ticket a review.
|
131 |
|
132 | Some things that will increase the chance that your pull request is accepted,
|
133 | taken straight from the Ruby on Rails guide:
|
134 |
|
135 | * Use Node idioms and helpers.
|
136 | * Include tests that fail without your code, and pass with it.
|
137 | * Update the documentation, the surrounding one, examples elsewhere, guides,
|
138 | whatever is affected by your contribution.
|
139 |
|
140 | #### Syntax
|
141 |
|
142 | * Two spaces, no tabs.
|
143 | * No trailing whitespace. Blank lines should not have any space.
|
144 | * Follow the conventions you see used in the source already.
|
145 |
|
146 | #### Inline Documentation Guidelines
|
147 |
|
148 | All inline documentation is written using YUIDoc. Follow these rules when
|
149 | updating or writing new documentation:
|
150 |
|
151 | 1. All code blocks must be fenced.
|
152 | 2. All code blocks must have a language declared.
|
153 | 3. All code blocks must be valid code for syntax highlighting.
|
154 | 4. All examples in code blocks must be aligned.
|
155 | 5. Use two spaces between the code and the example: `foo(); // result`.
|
156 | 6. All references to code words must be enclosed in backticks.
|
157 | 7. Prefer a single space between sentences.
|
158 | 8. Wrap long markdown blocks > 80 characters.
|
159 | 9. Don't include blank lines after `@param` definitions.
|
160 |
|
161 | #### Website
|
162 |
|
163 | The codebase for the website [ember-cli.com](https://ember-cli.com) is located
|
164 | at: https://github.com/ember-cli/ember-cli.github.io
|
165 |
|
166 | #### Code Words
|
167 |
|
168 | * `thisPropertyName`
|
169 | * `Global.Class.attribute`
|
170 | * `thisFunction()`
|
171 | * `Global.CONSTANT_NAME`
|
172 | * `true`, `false`, `null`, `undefined` (when referring to programming values)
|
173 |
|
174 | And in case we didn't emphasize it enough: **we love tests!**
|
175 |
|
176 | #### Testing
|
177 |
|
178 | Testing is done with mocha. You can invoke the tests by running `npm test` or `npm run-script
|
179 | test-all`. Both scripts are running `node tests/runner` may be with additional params. To contribute
|
180 | with a test, write your test and add `.only` to it's `describe` or `it` block. E.g.
|
181 |
|
182 | ```javascript
|
183 | describe.only("My new feature", function() {
|
184 | it("is neat", function() {
|
185 | //...
|
186 | });
|
187 | });
|
188 | ```
|
189 |
|
190 | Then simply run `npm test` for your test to run. If the test(s) pass and you are happy with the
|
191 | result, remove the `.only` and run the whole suite again, in order to make sure that you didn't
|
192 | break anything.
|
193 |
|
194 | NOTE: Partially copied from https://raw.githubusercontent.com/emberjs/ember.js/master/CONTRIBUTING.md
|
195 |
|
196 | #### Experiments
|
197 |
|
198 | A new feature may require putting the changes behind an experiment. More
|
199 | information can be found at
|
200 | [Experiments](https://github.com/ember-cli/ember-cli/blob/master/docs/experiments.md).
|
201 |
|
202 | # Code Climate
|
203 |
|
204 | We can always use help improving our [Code Climate](https://codeclimate.com/github/ember-cli/ember-cli) score.
|
205 |
|
206 | # Docs
|
207 |
|
208 | Have you got enough knowledge in a specific feature and want to help with docs?
|
209 | Ember-cli documentation lives at the repository
|
210 | [ember-cli.github.io](https://github.com/ember-cli/ember-cli.github.io).
|
211 |
|
212 | Feel free to contribute and help us to keep an updated, clear and complete
|
213 | documentation.
|