scratch – Blame information for rev 134
?pathlinks?
Rev | Author | Line No. | Line |
---|---|---|---|
134 | office | 1 | # Contributing to this project |
2 | |||
3 | Please take a moment to review this document in order to make the contribution |
||
4 | process easy and effective for everyone involved. |
||
5 | |||
6 | Following these guidelines helps to communicate that you respect the time of |
||
7 | the developers managing and developing this open source project. In return, |
||
8 | they should reciprocate that respect in addressing your issue or assessing |
||
9 | patches and features. |
||
10 | |||
11 | |||
12 | ## Using the issue tracker |
||
13 | |||
14 | The issue tracker is the preferred channel for [bug reports](#bugs), |
||
15 | [features requests](#features) and [submitting pull |
||
16 | requests](#pull-requests), but please respect the following restrictions: |
||
17 | |||
18 | * Please **do not** use the issue tracker for personal support requests (use |
||
19 | [Stack Overflow](http://stackoverflow.com)). |
||
20 | |||
21 | * Please **do not** derail or troll issues. Keep the discussion on topic and |
||
22 | respect the opinions of others. |
||
23 | |||
24 | |||
25 | <a name="bugs"></a> |
||
26 | ## Bug reports |
||
27 | |||
28 | A bug is a _demonstrable problem_ that is caused by the code in the repository. |
||
29 | Good bug reports are extremely helpful - thank you! |
||
30 | |||
31 | Guidelines for bug reports: |
||
32 | |||
33 | 1. **Use the GitHub issue search** — check if the issue has already been |
||
34 | reported. |
||
35 | |||
36 | 2. **Check if the issue has been fixed** — try to reproduce it using the |
||
37 | latest `master` or development branch in the repository. |
||
38 | |||
39 | 3. **Isolate the problem** — create a [reduced test |
||
40 | case](http://css-tricks.com/6263-reduced-test-cases/) and **a live example** (preferrably using jsfiddle). Please understand that it takes a lot of time to re-create your issue without a live example. **Issues without live examples will be ignored**. |
||
41 | |||
42 | A good bug report shouldn't leave others needing to chase you up for more |
||
43 | information. Please try to be as detailed as possible in your report. What is |
||
44 | your environment? What steps will reproduce the issue? What browser(s) and OS |
||
45 | experience the problem? What would you expect to be the outcome? All these |
||
46 | details will help people to fix any potential bugs. |
||
47 | |||
48 | Example: |
||
49 | |||
50 | > Short and descriptive example bug report title |
||
51 | > |
||
52 | > A summary of the issue and the browser/OS environment in which it occurs. If |
||
53 | > suitable, include the steps required to reproduce the bug. |
||
54 | > |
||
55 | > 1. This is the first step |
||
56 | > 2. This is the second step |
||
57 | > 3. Further steps, etc. |
||
58 | > |
||
59 | > `<url>` - a link to the reduced test case |
||
60 | > |
||
61 | > Any other information you want to share that is relevant to the issue being |
||
62 | > reported. This might include the lines of code that you have identified as |
||
63 | > causing the bug, and potential solutions (and your opinions on their |
||
64 | > merits). |
||
65 | |||
66 | |||
67 | <a name="features"></a> |
||
68 | ## Feature requests |
||
69 | |||
70 | Feature requests are welcome. But take a moment to find out whether your idea |
||
71 | fits with the scope and aims of the project. It's up to *you* to make a strong |
||
72 | case to convince the project's developers of the merits of this feature. Please |
||
73 | provide as much detail and context as possible. |
||
74 | |||
75 | |||
76 | <a name="pull-requests"></a> |
||
77 | ## Pull requests |
||
78 | |||
79 | Good pull requests - patches, improvements, new features - are a fantastic |
||
80 | help. They should remain focused in scope and avoid containing unrelated |
||
81 | commits. |
||
82 | |||
83 | **Please ask first** before embarking on any significant pull request (e.g. |
||
84 | implementing features, refactoring code, porting to a different language), |
||
85 | otherwise you risk spending a lot of time working on something that the |
||
86 | project's developers might not want to merge into the project. |
||
87 | |||
88 | Please adhere to the coding conventions used throughout a project (indentation, |
||
89 | accurate comments, etc.) and any other requirements (such as test coverage). |
||
90 | |||
91 | Follow this process if you'd like your work considered for inclusion in the |
||
92 | project: |
||
93 | |||
94 | 1. [Fork](http://help.github.com/fork-a-repo/) the project, clone your fork, |
||
95 | and configure the remotes: |
||
96 | |||
97 | ```bash |
||
98 | # Clone your fork of the repo into the current directory |
||
99 | git clone https://github.com/<your-username>/<repo-name> |
||
100 | # Navigate to the newly cloned directory |
||
101 | cd <repo-name> |
||
102 | # Assign the original repo to a remote called "upstream" |
||
103 | git remote add upstream https://github.com/<upstream-owner>/<repo-name> |
||
104 | ``` |
||
105 | |||
106 | 2. If you cloned a while ago, get the latest changes from upstream: |
||
107 | |||
108 | ```bash |
||
109 | git checkout <dev-branch> |
||
110 | git pull upstream <dev-branch> |
||
111 | ``` |
||
112 | |||
113 | 3. Create a new topic branch (off the main project development branch) to |
||
114 | contain your feature, change, or fix: |
||
115 | |||
116 | ```bash |
||
117 | git checkout -b <topic-branch-name> |
||
118 | ``` |
||
119 | |||
120 | 4. Commit your changes in logical chunks. Please adhere to these [git commit |
||
121 | message guidelines](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html) |
||
122 | or your code is unlikely be merged into the main project. Use Git's |
||
123 | [interactive rebase](https://help.github.com/articles/interactive-rebase) |
||
124 | feature to tidy up your commits before making them public. |
||
125 | |||
126 | 5. Locally merge (or rebase) the upstream development branch into your topic branch: |
||
127 | |||
128 | ```bash |
||
129 | git pull [--rebase] upstream <dev-branch> |
||
130 | ``` |
||
131 | |||
132 | 6. Push your topic branch up to your fork: |
||
133 | |||
134 | ```bash |
||
135 | git push origin <topic-branch-name> |
||
136 | ``` |
||
137 | |||
138 | 7. [Open a Pull Request](https://help.github.com/articles/using-pull-requests/) |
||
139 | with a clear title and description. |
||
140 | |||
141 | **IMPORTANT**: By submitting a patch, you agree to allow the project owner to |
||
142 | license your work under the same license as that used by the project. |