1 | # Contributing to Carrot
|
2 |
|
3 | First off, thank you for considering contributing to Carrot. It's people like you that make Carrot such a great tool.
|
4 |
|
5 | Please take a moment to review this document in order to make the contribution
|
6 | process easy and effective for everyone involved.
|
7 |
|
8 | Following these guidelines helps to communicate that you respect the time of
|
9 | the developers managing and developing this open source project. In return,
|
10 | they should reciprocate that respect in addressing your issue, assessing
|
11 | changes, and helping you finalize your pull requests.
|
12 |
|
13 | Contributions to Carrot are governed by our [Code of Conduct][6] and a set of
|
14 | Project Bylaws (TBD). Come join us!
|
15 |
|
16 |
|
17 | ## Using the issue tracker
|
18 |
|
19 | First things first: **Do NOT report security vulnerabilities in public issues!**
|
20 | Please disclose responsibly by letting [the Carrot Security team](mailto:people@liquidcarrot.io?subject=Security)
|
21 | know upfront. We will assess the issue as soon as possible on a best-effort
|
22 | basis and will give you an estimate for when we have a fix and release available
|
23 | for an eventual public disclosure.
|
24 |
|
25 | The GitHub issue tracker is the preferred channel for [bug reports](#bugs),
|
26 | [features requests](#features) and [submitting pull requests](#pull-requests),
|
27 | but please respect the following restrictions:
|
28 |
|
29 | * Please **do not** use the issue tracker for personal support requests. Use
|
30 | [Carrot Chat][8] instead. Alternately, help us to help more people by
|
31 | using our publicly archived user(TODO) or developer(TODO) mailing lists.
|
32 |
|
33 | * Please **do not** derail or troll issues. Keep the discussion on topic and
|
34 | respect the opinions of others.
|
35 |
|
36 | If you need to learn how to open an issue on Github we invite you to check out [this resource](https://help.github.com/en/articles/creating-an-issue)!
|
37 |
|
38 | ## Bug reports
|
39 |
|
40 | A bug is a _demonstrable problem_ that is caused by the code in our
|
41 | repositories. Good bug reports are extremely helpful - thank you!
|
42 |
|
43 | Guidelines for bug reports:
|
44 |
|
45 | 1. **Use the GitHub issue search** — check if the issue has already been
|
46 | reported.
|
47 |
|
48 | 2. **Check if the issue has been fixed** — try to reproduce it using the
|
49 | latest `master` or `next` branch in the repository.
|
50 |
|
51 | 3. **Isolate the problem** — ideally create a reduced test case.
|
52 |
|
53 | A good bug report shouldn't leave others needing to chase you up for more
|
54 | information. Please try to be as detailed as possible in your report. What is
|
55 | your environment? What steps will reproduce the issue? What OS experiences the
|
56 | problem? What would you expect to be the outcome? All these details will help
|
57 | people to fix any potential bugs. Our issue template will help you include all
|
58 | of the relevant detail.
|
59 |
|
60 | Example:
|
61 |
|
62 | > Short and descriptive example bug report title
|
63 | >
|
64 | > A summary of the issue and the browser/OS environment in which it occurs. If
|
65 | > suitable, include the steps required to reproduce the bug.
|
66 | >
|
67 | > 1. This is the first step
|
68 | > 2. This is the second step
|
69 | > 3. Further steps, etc.
|
70 | >
|
71 | > `<url>` - a link to the reduced test case
|
72 | >
|
73 | > Any other information you want to share that is relevant to the issue being
|
74 | > reported. This might include the lines of code that you have identified as
|
75 | > causing the bug, and potential solutions (and your opinions on their
|
76 | > merits).
|
77 |
|
78 |
|
79 | ## Feature requests
|
80 |
|
81 | Feature requests are welcome. But take a moment to find out whether your idea
|
82 | fits with the scope and aims of the project. It's up to *you* to make a strong
|
83 | case to convince the project's developers of the merits of this feature. Please
|
84 | provide as much detail and context as possible.
|
85 |
|
86 |
|
87 | ## Pull requests
|
88 |
|
89 | Good pull requests - patches, improvements, new features - are a fantastic
|
90 | help. They should remain focused in scope and avoid containing unrelated
|
91 | commits.
|
92 |
|
93 | **Please ask first** before embarking on any significant pull request (e.g.
|
94 | implementing features, refactoring code), otherwise you risk spending a lot of
|
95 | time working on something that the project's developers might not want to merge
|
96 | into the project. You can talk with the community on our
|
97 | developer mailing list(TODO). We're always open to suggestions and will get
|
98 | back to you as soon as we can!
|
99 |
|
100 |
|
101 | ### For new Contributors
|
102 |
|
103 | If you never created a pull request before, welcome :tada: :smile: [Here is a great tutorial](https://egghead.io/series/how-to-contribute-to-an-open-source-project-on-github)
|
104 | on how to send one :)
|
105 |
|
106 | 1. [Fork](http://help.github.com/fork-a-repo/) the project, clone your fork,
|
107 | and configure the remotes:
|
108 |
|
109 | ```bash
|
110 | # Clone your fork of the repo into the current directory
|
111 | git clone https://github.com/<your-username>/<repo-name>
|
112 | # Navigate to the newly cloned directory
|
113 | cd <repo-name>
|
114 | # Assign the original repo to a remote called "upstream"
|
115 | git remote add upstream https://github.com/liquid-carrot/<repo-name>
|
116 | ```
|
117 |
|
118 | 2. If you cloned a while ago, get the latest changes from upstream:
|
119 |
|
120 | ```bash
|
121 | git checkout master
|
122 | git pull upstream master
|
123 | ```
|
124 |
|
125 | 3. Create a new topic branch (off the main project development branch) to
|
126 | contain your feature, change, or fix:
|
127 |
|
128 | ```bash
|
129 | git checkout -b <topic-branch-name>
|
130 | ```
|
131 |
|
132 | 4. Make sure to update, or add to the tests when appropriate. Patches and
|
133 | features will not be accepted without tests. Run `make check` to check that
|
134 | all tests pass after you've made changes. Look for a `Testing` section in
|
135 | the project’s README for more information.
|
136 |
|
137 | 5. If you added or changed a feature, make sure to document it accordingly in
|
138 | the [Carrot documentation](https://github.com/liquid-carrot/carrot-documentation)
|
139 | repository.
|
140 |
|
141 | 6. Push your topic branch up to your fork:
|
142 |
|
143 | ```bash
|
144 | git push origin <topic-branch-name>
|
145 | ```
|
146 |
|
147 | 8. [Open a Pull Request](https://help.github.com/articles/using-pull-requests/)
|
148 | with a clear title and description.
|
149 |
|
150 |
|
151 | ### For Carrot Committers
|
152 |
|
153 | 1. Be sure to set up [GitHub two-factor authentication](https://help.github.com/articles/about-two-factor-authentication/),
|
154 | then [link your account to your GitHub account](https://gitbox.liquid-carrot.org/setup/).
|
155 | You will need to wait about 30 minutes after completing this process
|
156 | for it to complete. Follow the instructions in the organisational
|
157 | invite email you receive. Alternately, you can use the mirror
|
158 | of the repository at `https://gitbox.liquid-carrot.org/repos/asf/carrot.git`
|
159 | if you do not agree to the GitHub Terms of Service.
|
160 |
|
161 | 2. Clone the repo and create a branch.
|
162 |
|
163 | ```bash
|
164 | git clone https://github.com/liquidcarrot/carrot.git
|
165 | cd carrot
|
166 | git checkout -b <topic-branch-name>
|
167 | ```
|
168 |
|
169 | 3. Make sure to update, or add to the tests when appropriate. Patches and
|
170 | features will not be accepted without tests. Run `npm test` to check that
|
171 | all tests pass after you've made changes. Look for a `Testing` section in
|
172 | the project’s README for more information.
|
173 |
|
174 | 4. If you added or changed a feature, make sure to document it accordingly in
|
175 | the [Carrot documentation](https://liquidcarrot.github.io/carrot)
|
176 | using [JSDoc](http://usejsdoc.org/about-getting-started.html).
|
177 |
|
178 | 5. Push your topic branch up to our repo
|
179 |
|
180 | ```bash
|
181 | git push origin <topic-branch-name>
|
182 | ```
|
183 |
|
184 | 6. Open a Pull Request using your branch with a clear title and description.
|
185 | Please also add any appropriate labels to the pull request for clarity.
|
186 |
|
187 | Optionally, you can help us with these things. But don’t worry if they are too
|
188 | complicated, we can help you out and teach you as we go :)
|
189 |
|
190 | 1. Update your branch to the latest changes in the upstream master branch. You
|
191 | can do that locally with
|
192 |
|
193 | ```bash
|
194 | git pull --rebase upstream master
|
195 | ```
|
196 |
|
197 | Afterwards force push your changes to your remote feature branch.
|
198 |
|
199 | 2. Once a pull request is good to go, you can tidy up your commit messages using
|
200 | Git's [interactive rebase](https://help.github.com/articles/interactive-rebase).
|
201 |
|
202 | **IMPORTANT**: By submitting a patch, you agree to license your work under the
|
203 | License, per your signed CLA.
|
204 |
|
205 |
|
206 | ## Triagers
|
207 |
|
208 | Carrot committers who have completed the GitHub account linking
|
209 | process may triage issues. This helps to speed up releases and minimises both
|
210 | user and developer pain in working through our backlog.
|
211 |
|
212 | Briefly, to triage an issue, review the report, validate that it is an actual
|
213 | issue (reproducing if possible), and add one or more labels. We have a
|
214 | [summary of our label taxonomy](https://github.com/liquid-carrot/carrot/issues/499)
|
215 | for your reference.
|
216 |
|
217 | If you are not an official committer, please reach out to our mailing list(TODO)
|
218 | or [chat][8] to learn how you can assist with triaging indirectly.
|
219 |
|
220 |
|
221 | ## Maintainers
|
222 |
|
223 | If you have commit access, please follow this process for merging patches and cutting new releases.
|
224 |
|
225 | ### Reviewing changes
|
226 |
|
227 | 1. Check that a change is within the scope and philosophy of the component.
|
228 | 2. Check that a change has any necessary tests.
|
229 | 3. Check that a change has any necessary documentation.
|
230 | 4. If there is anything you don’t like, leave a comment below the respective
|
231 | lines and submit a "Request changes" review. Repeat until everything has
|
232 | been addressed.
|
233 | 5. If you are not sure about something, mention specific people for help in a
|
234 | comment.
|
235 | 6. If there is only a tiny change left before you can merge it and you think
|
236 | it’s best to fix it yourself, you can directly commit to the author’s fork.
|
237 | Leave a comment about it so the author and others will know.
|
238 | 7. Once everything looks good, add an "Approve" review. Don’t forget to say
|
239 | something nice 👏🐶💖✨
|
240 | 8. If the commit messages follow [our conventions](@commit-message-conventions)
|
241 |
|
242 | 1. If the pull request fixes one or more open issues, please include the
|
243 | text "Fixes #472" or "Fixes liquid-carrot/carrot#472".
|
244 | 2. Use the "Rebase and merge" button to merge the pull request.
|
245 | 3. Done! You are awesome! Thanks so much for your help 🤗
|
246 |
|
247 | 9. If the commit messages _do not_ follow our conventions
|
248 |
|
249 | 1. Use the "squash and merge" button to clean up the commits and merge at
|
250 | the same time: ✨🎩
|
251 | 2. If the pull request fixes one or more open issues, please include the
|
252 | text "Fixes #472" or "Fixes liquid-carrot/carrot#472".
|
253 |
|
254 | Sometimes there might be a good reason to merge changes locally. The process
|
255 | looks like this:
|
256 |
|
257 | ### Reviewing and merging changes locally
|
258 |
|
259 | ```
|
260 | git checkout master # or the main branch configured on github
|
261 | git pull # get latest changes
|
262 | git checkout feature-branch # replace name with your branch
|
263 | git rebase master
|
264 | git checkout master
|
265 | git merge feature-branch # replace name with your branch
|
266 | git push
|
267 | ```
|
268 |
|
269 | When merging PRs from forked repositories, we recommend you install the
|
270 | [hub](https://github.com/github/hub) command line tools.
|
271 |
|
272 | This allows you to do:
|
273 |
|
274 | ```
|
275 | hub checkout link-to-pull-request
|
276 | ```
|
277 |
|
278 | meaning that you will automatically check out the branch for the pull request,
|
279 | without needing any other steps like setting git upstreams! :sparkles:
|
280 |
|
281 |
|
282 | ## Thanks
|
283 |
|
284 | Special thanks to [Hoodie](https://github.com/hoodiehq/hoodie) for the great
|
285 | CONTRIBUTING.md template.
|
286 |
|
287 | [1]: https://liquidcarrot.io/carrot
|
288 | [5]: https://liquidcarrot.io/carrot
|
289 | [6]: https://github.com/liquidcarrot/carrot/blob/master/CODE_OF_CONDUCT.md
|
290 | [7]: https://liquidcarrot.io/carrot
|
291 | [8]: https://gitter.im/carrot-ai/community?utm_source=share-link&utm_medium=link&utm_campaign=share-link
|
292 |
|
\ | No newline at end of file |