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