diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e6ae1d0a36bd1..876daa97313e8 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,4 +1,4 @@ -###Guidelines +### Guidelines All contributions, bug reports, bug fixes, documentation improvements, enhancements and ideas are welcome. @@ -14,8 +14,9 @@ looking for a quick way to help out. ```python - print("I ♥ pandas!") - + >>> from pandas import DataFrame + >>> df = DataFrame(...) + ... ``` - Include the full version string of pandas and it's dependencies. In recent (>0.12) versions @@ -30,22 +31,21 @@ looking for a quick way to help out. ```python >>> pd.show_versions() ``` - - Explain what the expected behavior was, and what you saw instead. #### Pull Requests - - **Make sure the test suite passes** on your box, Use the provided `test_*.sh` scripts or tox. - - Use [proper commit messages](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html): - - a subject line with `< 80` chars. - - One blank line. - - Optionally, a commit message body. - - Please reference relevant Github issues in your commit message using `GH1234` - or `#1234`. Either style is fine but the '#' style generates noise when your rebase your PR. - - `doc/source/vx.y.z.txt` contains an ongoing - changelog for each release. Add an entry to this file - as needed in your PR: document the fix, enhancement, - or (unavoidable) breaking change. +##### Testing: + - Every addition to the codebase whether it be a bug or new feature should have associated tests. The can be placed in the `tests` directory where your code change occurs. + - When writing tests, use 2.6 compatible `self.assertFoo` methods. Some polyfills such as `assertRaises` + can be found in `pandas.util.testing`. + - Do not attach doctrings to tests. Make the test itself readable and use comments if needed. + - **Make sure the test suite passes** on your box, use the provided `test_*.sh` scripts or tox. Pandas tests a variety of platforms and Python versions so be cognizant of cross-platorm considerations. + - Performance matters. Make sure your PR hasn't introduced performance regressions by using `test_perf.sh`. See [vbench performance tests](https://github.com/pydata/pandas/wiki/Performance-Testing) wiki for more information on running these tests. + - For more information on testing see [Testing advice and best practices in `pandas`](https://github.com/pydata/pandas/wiki/Testing) + +##### Documentation / Commit Messages: + - Docstrings follow the [numpydoc](https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt) format. - Keep style fixes to a separate commit to make your PR more readable. - An informal commit message format is in effect for the project. Please try and adhere to it. Check `git log` for examples. Here are some common prefixes @@ -57,18 +57,24 @@ looking for a quick way to help out. - **BLD**: Updates to the build process/scripts - **PERF**: Performance improvement - **CLN**: Code cleanup + - Use [proper commit messages](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html): + - a subject line with `< 80` chars. + - One blank line. + - Optionally, a commit message body. + - Please reference relevant Github issues in your commit message using `GH1234` + or `#1234`. Either style is fine but the '#' style generates noise when your rebase your PR. + - `doc/source/vx.y.z.txt` contains an ongoing + changelog for each release. Add an entry to this file + as needed in your PR: document the fix, enhancement, + or (unavoidable) breaking change. - Maintain backward-compatibility. Pandas has lots of users with lots of existing code. Don't break it. - If you think breakage is required clearly state why as part of the PR. - Be careful when changing method signatures. - Add deprecation warnings where needed. - - Performance matters. Make sure your PR hasn't introduced perf regressions by using `test_perf.sh`. - - Docstrings follow the [numpydoc](https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt) format. - - Write tests. - - When writing tests, use 2.6 compatible `self.assertFoo` methods. Some polyfills such as `assertRaises` - can be found in `pandas.util.testing`. - - Do not attach doctrings to tests. Make the test itself readable and use comments if needed. - Generally, pandas source files should not contain attributions. You can include a "thanks to..." in the release changelog. The rest is `git blame`/`git log`. + +##### Workflow/Git - When you start working on a PR, start by creating a new branch pointing at the latest commit on github master. - **Do not** merge upstream into a branch you're going to submit as a PR. @@ -78,21 +84,22 @@ looking for a quick way to help out. - Use `raise AssertionError` over `assert` unless you want the assertion stripped by `python -o`. - The pandas copyright policy is detailed in the pandas [LICENSE](https://github.com/pydata/pandas/blob/master/LICENSE). - On the subject of [PEP8](http://www.python.org/dev/peps/pep-0008/): yes. + - [Git tips and tricks](https://github.com/pydata/pandas/wiki/Using-Git) + +##### Code standards: - We've written a tool to check that your commits are PEP8 great, [`pip install pep8radius`](https://github.com/hayd/pep8radius). Look at PEP8 fixes in your branch vs master with `pep8radius master --diff` and make these changes with `pep8radius master --diff --in-place`. - On the subject of a massive PEP8-storm touching everything: not too often (once per release works). + - Additional standards are outlined on the [code style wiki page](https://github.com/pydata/pandas/wiki/Code-Style-and-Conventions) ### Notes on plotting function conventions https://groups.google.com/forum/#!topic/pystatsmodels/biNlCvJPNNY/discussion -####More developer docs - +#### More developer docs * See the [developers](http://pandas.pydata.org/developers.html) page on the project website for more details. -* [`pandas` wiki](https://github.com/pydata/pandas/wiki) +* [`pandas` wiki](https://github.com/pydata/pandas/wiki) constains useful pages for development and general pandas usage * [Tips and tricks](https://github.com/pydata/pandas/wiki/Tips-&-Tricks) -* [Git tips and tricks](https://github.com/pydata/pandas/wiki/Using-Git) -* [Testing advice and best practices in `pandas`](https://github.com/pydata/pandas/wiki/Testing)