|
3 | 3 | All contributions, bug reports, bug fixes, documentation improvements, |
4 | 4 | enhancements and ideas are welcome. |
5 | 5 |
|
6 | | -The Github "issues" tab contains some issues labels "Good as first PR", these are |
7 | | -tasks which do not require deep knowledge of the package. Look those up if you're |
| 6 | +The [GitHub "issues" tab](https://github.com/pydata/pandas/issues) |
| 7 | +contains some issues labeled "Good as first PR"; Look those up if you're |
8 | 8 | looking for a quick way to help out. |
9 | 9 |
|
10 | | -Please try and follow these guidelines, as this makes it easier for us to accept |
11 | | -your contribution or address the issue you're having. |
| 10 | +#### Bug Reports |
12 | 11 |
|
13 | | -- When submitting a bug report: |
14 | | - - Please include a short, self-contained python snippet reproducing the problem. |
| 12 | + - Please include a short, self-contained Python snippet reproducing the problem. |
15 | 13 | You can have the code formatted nicely by using [GitHub Flavored Markdown](http://github.github.com/github-flavored-markdown/) : |
16 | 14 |
|
17 | | - ``` |
18 | | - ```python |
| 15 | + ```python |
19 | 16 |
|
20 | | - print("I ♥ pandas!") |
| 17 | + print("I ♥ pandas!") |
21 | 18 |
|
22 | | - ``' |
23 | | - ``` |
| 19 | + ``` |
24 | 20 |
|
25 | | - - Specify the pandas (and numpy) version used. (you can check `pandas.__version__`). |
| 21 | + - Specify the pandas version used and those of it's dependencies. You can simply include the output of |
| 22 | + [`ci/print_versions.py`](https://github.com/pydata/pandas/blob/master/ci/print_versions.py). |
26 | 23 | - Explain what the expected behavior was, and what you saw instead. |
27 | | - - If the issue seems to involve some of pandas' dependencies such as matplotlib |
28 | | - or PyTables, you should include (the relavent parts of) the output of |
29 | | - [ci/print_versions.py](https://github.com/pydata/pandas/blob/master/ci/print_versions.py) |
30 | 24 |
|
31 | | -- When submitting a Pull Request |
32 | | - - **Make sure the test suite passes**., and that means on python3 as well. |
33 | | - You can use "test_fast.sh", or tox locally and/or enable Travis-CI on your fork. |
34 | | - See the "Getting Travis-CI going" below. |
35 | | - - We suggest you enable Travis-CI on your fork, to make it easier for the team |
36 | | - to see that the PR does indeed pass all the tests. |
37 | | - - Back-compatibility **really** matters. Pandas already has a large user-base and |
38 | | - a lot of existing user code. Don't break old code if you can avoid it |
39 | | - Explain the need if there is one in the PR. |
40 | | - Changes to method signatures should be made in a way which doesn't break existing |
41 | | - code, for example you should beware of changes to ordering and naming of keyword |
42 | | - arguments. Add deprecation warnings when needed. |
43 | | - - Performance matters. You can use the included "test_perf.sh" |
44 | | - script to make sure your PR does not introduce any performance regressions |
45 | | - in the library. |
46 | | - - docstrings follow the [numpydoc](https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt) format. |
47 | | - - **Don't** merge upstream into a branch you're going to submit as a PR, |
48 | | - This can create all sorts of problems. Use "git rebase" instead. This ensures |
49 | | - no merge conflicts occur when you're code is merged by the core team. |
50 | | - - An informal commit message format is in effect for the project, please try |
51 | | - and adhere to it. View "git log" for examples. Here are some common prefixes |
52 | | - along with general guidelines for when to use them: |
53 | | - - ENH: Enhancement, new functionality |
54 | | - - BUG: Bug fix |
55 | | - - DOC: Additions/updates to documentation |
56 | | - - TST: Additions/updates to tests |
57 | | - - BLD: Updates to the build process/scripts |
58 | | - - PERF: Performance improvement |
59 | | - - CLN: Code cleanup |
60 | | - - Commit messages should have subject line <80 chars, followed by one blank line, |
61 | | - and finally a commit message body if there's a need for one. |
62 | | - - Please reference the GH issue number in your commit message using GH1234 |
63 | | - or #1234, either style is fine. |
64 | | - - Use "raise AssertionError" rather then plain `assert` in library code (using assert is fine |
65 | | - for test code). python -o strips assertions. better safe then sorry. |
66 | | - - When writing tests, don't use "new" assertion methods added to the unittest module |
67 | | - in 2.7 since pandas currently supports 2.6. The most common pitfall is: |
68 | | -
|
69 | | - with self.assertRaises(ValueError): |
70 | | - foo |
71 | | -
|
72 | | - which fails on python 2.6, use `self.assertRaises(TheException,func,args)` instead. |
73 | | -
|
74 | | - - doc/source/release.rst and doc/source/vx.y.z.txt contain an on-going |
75 | | - changelog for each release as it is worked on. Add entries to these files |
76 | | - as needed in a separate commit in your PR, documenting the fix, enhancement |
| 25 | +#### Pull Requests |
| 26 | + |
| 27 | + - **Make sure the test suite passes** on your box, Use the provided `test_*.sh` scripts or tox. |
| 28 | + - Use [proper commit messages](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html): |
| 29 | + - a subject line with `< 80` chars. |
| 30 | + - One blank line. |
| 31 | + - Optionally, a commit message body. |
| 32 | + - Please reference relevant Github issues in your commit message using `GH1234` |
| 33 | + or `#1234`. Either style is fine but the '#' style generates nose when your rebase your PR. |
| 34 | + - `doc/source/release.rst` and `doc/source/vx.y.z.txt` contain an ongoing |
| 35 | + changelog for each release. Add entries to these files |
| 36 | + as needed in a separate commit in your PR: document the fix, enhancement, |
77 | 37 | or (unavoidable) breaking change. |
78 | | - - For extra brownie points, use "git rebase -i" to squash and reorder |
79 | | - commits in your PR so that the history makes the most sense. Use your own |
80 | | - judgment to decide what history needs to be preserved. |
81 | | - - Pandas source code should not (with some exceptions, such as 3rd party licensed code), |
82 | | - generally speaking, include an "Authors:" list or attribution to individuals in source code. |
83 | | - The RELEASE.rst details changes and enhancements to the code over time, |
84 | | - a "thanks goes to @JohnSmith." as part of the appropriate entry is a suitable way to acknowledge |
85 | | - contributions, the rest is git blame/log. |
86 | | - Feel free to ask the commiter who merges your code to include such an entry |
87 | | - or include it directly yourself as part of the PR if you'd like to. We're always glad to have |
88 | | - new contributors join us from the ever-growing pandas community. |
89 | | - You may also be interested in the copyright policy as detailed in the pandas [LICENSE](https://github.com/pydata/pandas/blob/master/LICENSE). |
| 38 | + - Keep style fixes to a separate commit to make your PR more readable. |
| 39 | + - An informal commit message format is in effect for the project. Please try |
| 40 | + and adhere to it. Check `git log` for examples. Here are some common prefixes |
| 41 | + along with general guidelines for when to use them: |
| 42 | + - **ENH**: Enhancement, new functionality |
| 43 | + - **BUG**: Bug fix |
| 44 | + - **DOC**: Additions/updates to documentation |
| 45 | + - **TST**: Additions/updates to tests |
| 46 | + - **BLD**: Updates to the build process/scripts |
| 47 | + - **PERF**: Performance improvement |
| 48 | + - **CLN**: Code cleanup |
| 49 | + - Maintain backward-compatibility. Pandas has lots of users with lots of existing code. Don't break it. |
| 50 | + - If you think breakage is required clearly state why as part of the PR. |
| 51 | + - Be careful when changing method signatures. |
| 52 | + - Add deprecation warnings where needed. |
| 53 | + - Performance matters. Make sure your PR hasn't introduced perf regressions by using `test_perf.sh`. |
| 54 | + - Docstrings follow the [numpydoc](https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt) format. |
| 55 | + - When writing tests, use 2.6 compatible `self.assertFoo` methods. Some polyfills such as `assertRaises` |
| 56 | + can be found in `pandas.util.testing`. |
| 57 | + - Generally, pandas source files should not contain attributions. You can include a "thanks to..." |
| 58 | + in the release changelog. The rest is `git blame`/`git log`. |
| 59 | + - When you start working on a PR, start by creating a new branch pointing at the latest |
| 60 | + commit on github master. |
| 61 | + - **Do not** merge upstream into a branch you're going to submit as a PR. |
| 62 | + Use `git rebase` against the current github master. |
| 63 | + - For extra brownie points, you can squash and reorder the commits in your PR using `git rebase -i`. |
| 64 | + Use your own judgment to decide what history needs to be preserved. If git frightens you, that's OK too. |
| 65 | + - Use `raise AssertionError` over `assert` unless you want the assertion stripped by `python -o`. |
| 66 | + - The pandas copyright policy is detailed in the pandas [LICENSE](https://github.com/pydata/pandas/blob/master/LICENSE). |
90 | 67 | - On the subject of [PEP8](http://www.python.org/dev/peps/pep-0008/): yes. |
91 | | - - On the subject of massive PEP8 fix PRs touching everything, please consider the following: |
92 | | - - They create merge conflicts for people working in their own fork. |
93 | | - - They makes git blame less effective. |
94 | | - - Different tools / people achieve PEP8 in different styles. This can create |
95 | | - "style wars" and churn that produces little real benefit. |
96 | | - - If your code changes are intermixed with style fixes, they are harder to review |
97 | | - before merging. Keep style fixes in separate commits. |
98 | | - - it's fine to clean-up a little around an area you just worked on. |
99 | | - - Generally its a BAD idea to PEP8 on documentation. |
100 | | -
|
101 | | - Having said that, if you still feel a PEP8 storm is in order, go for it. |
| 68 | + - On the subject of a massive PEP8-storm touching everything: not too often (once per release works). |
102 | 69 |
|
103 | | -### Notes on plotting functions convention |
| 70 | +### Notes on plotting function conventions |
104 | 71 |
|
105 | 72 | https://groups.google.com/forum/#!topic/pystatsmodels/biNlCvJPNNY/discussion |
106 | 73 |
|
107 | | -###Getting Travis-CI going |
108 | | -
|
109 | | -Instructions for getting Travis-CI installed are available [here](http://about.travis-ci.org/docs/user/getting-started/). For those users who are new to travis-ci and continuous-integration in particular, |
110 | | -Here's a few high-level notes: |
111 | | -- Travis-CI is a free service (with premium account available), that integrates |
112 | | -well with Github. |
113 | | -- Enabling Travis-CI on your github fork of a project will cause any *new* commit |
114 | | -pushed to the repo to trigger a full build+test on Travis-CI's servers. |
115 | | -- All the configuration for travis's builds is already specified by .travis.yml in the repo, |
116 | | -That means all you have to do is enable Travis-CI once, and then just push commits |
117 | | -and you'll get full testing across py2/3 with pandas's considerable test-suite. |
118 | | -- Enabling travis-CI will attach the test results (red/green) to the Pull-Request |
119 | | -page for any PR you submit. For example: |
120 | | -
|
121 | | - https://github.com/pydata/pandas/pull/2532, |
122 | | -
|
123 | | -See the Green "Good to merge!" banner? that's it. |
124 | | -
|
125 | | -This is especially important for new contributors, as members of the pandas dev team |
126 | | -like to know the test suite passes before considering it for merging. |
127 | | -Even regular contributors who test religiously on their local box (using tox |
128 | | -for example) often rely on a PR+travis=green to make double sure everything |
129 | | -works ok on another system, as occasionally, it doesn't. |
130 | | -
|
131 | | -####Steps to enable Travis-CI |
132 | | -
|
133 | | -- go to https://travis-ci.org/ |
134 | | -- "Sign in with Github", on top panel. |
135 | | -- \[your username\]/Account, on top-panel. |
136 | | -- 'sync now' to refresh the list of repos on your GH account. |
137 | | -- flip the switch on the repos you want Travis-CI enabled for, |
138 | | -"pandas" obviously. |
139 | | -- Then, pushing a *new* commit to a certain branch on that repo |
140 | | -will trigger a build/test for that branch, for example the branch |
141 | | -might be "master" or "PR1234_fix_all_the_things", if that's the |
142 | | -name of your PR branch. |
143 | | -
|
144 | | -You can see the build history and current builds for your fork |
145 | | -on: https://travis-ci.org/(your_GH_username)/pandas. |
146 | | -
|
147 | | -For example, the builds for the main pandas repo can be seen at: |
148 | | -https://travis-ci.org/pydata/pandas. |
149 | | -
|
150 | 74 | ####More developer docs |
151 | 75 |
|
152 | | -Please see [Developers](http://pandas.pydata.org/developers.html) page on |
153 | | -the project website for more details. |
| 76 | +* See the [developers](http://pandas.pydata.org/developers.html) page on the |
| 77 | + project website for more details. |
| 78 | +* [`pandas` wiki](https://github.com/pydata/pandas/wiki) |
| 79 | +* [Tips and tricks](https://github.com/pydata/pandas/wiki/Tips-&-Tricks) |
| 80 | +* [Git tips and tricks](https://github.com/pydata/pandas/wiki/Using-Git) |
| 81 | +* [Testing advice and best practices in `pandas`](https://github.com/pydata/pandas/wiki/Testing) |
0 commit comments