Skip to content

Rearrange into logical sections and add relevant links #9639

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Mar 13, 2015
+33 −26
Merged

Rearrange into logical sections and add relevant links #9639

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
59 changes: 33 additions & 26 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
###Guidelines
### Guidelines

All contributions, bug reports, bug fixes, documentation improvements,
enhancements and ideas are welcome.
Expand All @@ -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
Expand All @@ -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.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We should probably mention Travis-CI here, and the ease of setting up Travis on your own fork.

- 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
Expand All @@ -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.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Where did this line go?

- `doc/source/vx.y.z.txt` contains an ongoing
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is now doc/source/whatsnew/vx.y.z.txt

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.
Expand All @@ -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)