Skip to content

Latest commit

 

History

History
105 lines (88 loc) · 5.59 KB

CONTRIBUTING.md

File metadata and controls

105 lines (88 loc) · 5.59 KB
Raw

Guidelines

All contributions, bug reports, bug fixes, documentation improvements, enhancements and ideas are welcome.

The GitHub "issues" tab contains some issues labeled "Good as first PR"; Look those up if you're looking for a quick way to help out.

Bug Reports

  • Please include a short, self-contained Python snippet reproducing the problem. You can have the code formatted nicely by using GitHub Flavored Markdown :

    ```python

>>> from pandas import DataFrame
>>> df = DataFrame(...)
...
```

  • Include the full version string of pandas and its dependencies. In recent (>0.12) versions of pandas you can use a built in function:

    >>> from pandas.util.print_versions import show_versions
>>> show_versions()

    and in 0.13.1 onwards:

    >>> pd.show_versions()

  • Explain what the expected behavior was, and what you saw instead.

Pull Requests

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 wiki for more information on running these tests.
  • For more information on testing see Testing advice and best practices in pandas
Documentation / Commit Messages:
  • Docstrings follow the numpydoc 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 along with general guidelines for when to use them:
    • ENH: Enhancement, new functionality
    • BUG: Bug fix
    • DOC: Additions/updates to documentation
    • TST: Additions/updates to tests
    • BLD: Updates to the build process/scripts
    • PERF: Performance improvement
    • CLN: Code cleanup
  • Use proper commit messages:
    • 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.
  • 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. Use git rebase against the current github master.
  • For extra brownie points, you can squash and reorder the commits in your PR using git rebase -i. Use your own judgment to decide what history needs to be preserved. If git frightens you, that's OK too.
  • Use raise AssertionError over assert unless you want the assertion stripped by python -o.
  • The pandas copyright policy is detailed in the pandas LICENSE.
  • On the subject of PEP8: yes.
  • Git tips and tricks
Code standards:
  • We've written a tool to check that your commits are PEP8 great, pip install 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

Notes on plotting function conventions

https://groups.google.com/forum/#!topic/pystatsmodels/biNlCvJPNNY/discussion

More developer docs