|
| 1 | +# How to contribute |
| 2 | + |
| 3 | +We welcome users' contributions! However, we do have some requests for how contributions |
| 4 | +should be made. Please read these guidelines in order to avoid surprises down the road. |
| 5 | + |
| 6 | +## Choosing something to work on |
| 7 | + |
| 8 | +The issue tracker has a list of items that you can start working on, classified by the labels: |
| 9 | + |
| 10 | +* [`type:feature`](https://github.com/bokeh/bokeh/labels/type:%20feature) |
| 11 | +* [`type:task`](https://github.com/bokeh/bokeh/labels/type:%20task) |
| 12 | +* [`type:bug`](https://github.com/bokeh/bokeh/labels/type:%20bug) |
| 13 | + |
| 14 | +In order to avoid duplication of effort, it's always a good idea to comment on an issue |
| 15 | +and let everybody know that you intend to work on it. |
| 16 | + |
| 17 | +## Opening a new issue |
| 18 | + |
| 19 | +1. Avoid duplicate reports. Search [GitHub](https://github.com/bokeh/bokeh/issues) and |
| 20 | + the [mailing list](https://groups.google.com/a/continuum.io/forum/#!forum/bokeh) for |
| 21 | + similar or identical issues. Keyword searches for your error messages are usually effective. |
| 22 | +2. The issue may already be resolved. If possible, try to reproduce the issue using most recent |
| 23 | + [development build](http://bokeh.pydata.org/docs/installation.html#developer-builds) of bokeh, |
| 24 | + or even better, by building and installed from the `master` branch. |
| 25 | +3. Try to include a *minimal*, self-contained, reproducible test case or example. The more code |
| 26 | + or data we have to have to reproduce the issue, the less likely we will be able to. |
| 27 | +4. Include relevant system information. At minimum, you should provide output of: |
| 28 | + |
| 29 | + `python -c "import bokeh; print(bokeh.__version__)"` |
| 30 | + |
| 31 | +5. Include relevant browser information (if the issue is browser-related). Just saying that you |
| 32 | + use Chrome is generally not sufficient. We may ask you for additional information to |
| 33 | + reproduce and fix the issue. |
| 34 | +6. Include relevant JavaScript console and/or `bokeh serve` logs. |
| 35 | +7. If the problem is user interface related, it is *always* good to include a screenshot. |
| 36 | +8. State the expected behavior. |
| 37 | + |
| 38 | +## Creating a pull request (PR) |
| 39 | + |
| 40 | +1. Make sure that there is a corresponding issue for your change first. If there isn't yet, |
| 41 | + create one. |
| 42 | +2. Create a fork of the Bokeh repository on GitHub (this is only done before *first*) contribution). |
| 43 | +3. Create a branch off the `master` branch with a meaningful name. Preferably include issue number |
| 44 | + and a few keywords, so that we will have a rough idea what the branch refers to, without looking |
| 45 | + up the issue. As an example: `786_property_names`. |
| 46 | +4. Commit your changes and push them to GitHub. |
| 47 | +5. Create a pull request against the origin's `master` branch. The PR must have a meaningful title |
| 48 | + and a message explaining what was achieved, what remains to be done, maybe an example, etc. |
| 49 | +6. We don't accept code contributions without tests. If there are valid reasons for not including a |
| 50 | + test, please discuss this in the issue. |
| 51 | +7. We will review your PR as time permits. Reviewers may comment on your contributions, ask |
| 52 | + you questions regarding the implementation or request changes. If changes are requested, don't |
| 53 | + start a new PR, (push new commits to the existing one). Do *NOT* rebase, amend, or cherry-pick |
| 54 | + published commits. Any of those actions will make us start the review from scratch. If you need |
| 55 | + updates from `master`, just merge it into your branch. |
| 56 | + |
| 57 | +## DOs and DON'Ts |
| 58 | + |
| 59 | +* **DO** follow our coding style. |
| 60 | +* **DO** include new tests when adding new features. |
| 61 | +* **DO** include regression tests when fixing bugs. |
| 62 | +* **DO** keep the discussions focused. When a new or related topic comes up it's often better to |
| 63 | + create new issue than to side track the discussion. |
| 64 | +* **DON'T** surprise us with big pull requests. Instead, file an issue and start a discussion so we |
| 65 | + can agree on a direction before you invest a large amount of time. |
| 66 | +* **DON'T** commit code that you didn't write. If you find BSD license compatible code that you |
| 67 | + think would be useful to add to this project, file an issue and start a discussion first. |
0 commit comments