1- Guidelines
2- ---
1+ ###Guidelines
32
43All contributions, bug reports, bug fixes, documentation improvments,
54enhancements and ideas are welcome.
@@ -12,34 +11,70 @@ Please try and follow these guidelines, as this makes it easier for us to accept
1211your contribution or address the issue you're having.
1312
1413- When submitting a bug report:
15- - Please include a short, self-contained python snippet.
16- - Specify the pandas version used. (you can check ` pandas.__version__ ` ).
14+ - Please include a short, self-contained python snippet reproducing the problem.
15+ You can have the code formatted nicely by using [ GitHub Flavored Markdown] ( http://github.github.com/github-flavored-markdown/ ) :
16+
17+ ```
18+ ```python
19+
20+ print("I ♥ pandas!")
21+
22+ ``'
23+ ```
24+
25+ - Specify the pandas (and numpy) version used. (you can check `pandas.__version__`).
1726 - 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)
1830
1931- When submitting a Pull Request
2032 - **Make sure the test suite passes**., and that means on python3 as well.
2133 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.
2235 - We suggest you enable Travis-CI on your fork, to make it easier for the team
2336 to see that the PR does indeed pass all the tests.
2437 - Back-compatiblitiy **really** matters. Pandas already has a large user-base and
2538 a lot of existing user code. Don't break old code if you can avoid it
26- Explain the need if there is one in the PR.
27- Changes to method signatures should be made in a way which doesn't break existing
28- code, for example you should beware of changes to ordering and naming of keyword
29- arguments. Add deprecation warnings when needed.
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.
3043 - Performance matters. You can use the included "test_perf.sh"
3144 script to make sure your PR does not introduce any performance regressions
3245 in the library.
46+ - docstrings follow the [numpydoc](https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt) format.
3347 - **Don't** merge upstream into a branch you're going to submit as a PR,
3448 This can create all sorts of problems. Use "git rebase" instead. This ensures
3549 no merge conflicts occur when you're code is merged by the core team.
3650 - An informal commit message format is in effect for the project, please try
37- and adhere to it. Use a "ENH: ", "TST:", "BUG:", "DOC:", etc' prefix in
38- your commit title. Check the output of "git log" for examples.
39- - RELEASE.rst and doc/source/vx.y.z.txt contain an on-going changelog for each
40- release as it is worked on. Add entries to these files as needed in
41- a separate commit in your PR, documenting the fix, enhancement or (unavoidable)
42- breaking change.
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
77+ or (unavoidable) breaking change.
4378 - For extra brownie points, use "git rebase -i" to squash and reorder
4479 commits in your PR so that the history makes the most sense. Use your own
4580 judgment to decide what history needs to be preserved.
@@ -52,8 +87,58 @@ your contribution or address the issue you're having.
5287 - If your code changes are intermixed with style fixes, they are harder to review
5388 before merging. Keep style fixes in separate commits.
5489 - it's fine to clean-up a little around an area you just worked on.
90+ - Generally its a BAD idea to PEP8 on documentation.
5591
5692 Having said that, if you still feel a PEP8 storm is in order, go for it.
5793
94+ ### Notes on plotting functions convention
95+
96+ https://groups.google.com/forum/#!topic/pystatsmodels/biNlCvJPNNY/discussion
97+
98+ ###Getting Travis-CI going
99+
100+ 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,
101+ Here's a few high-level notes:
102+ - Travis-CI is a free service (with premium account available), that integrates
103+ well with Github.
104+ - Enabling Travis-CI on your github fork of a project will cause any *new* commit
105+ pushed to the repo to trigger a full build+test on Travis-CI's servers.
106+ - All the configuration for travis's builds is already specified by .travis.yml in the repo,
107+ That means all you have to do is enable Travis-CI once, and then just push commits
108+ and you'll get full testing across py2/3 with pandas's considerable test-suite.
109+ - Enabling travis-CI will attach the test results (red/green) to the Pull-Request
110+ page for any PR you submit. For example:
111+
112+ https://github.com/pydata/pandas/pull/2532,
113+
114+ See the Green "Good to merge!" banner? that's it.
115+
116+ This is especially important for new contributors, as memebers of the pandas dev team
117+ like to know the test suite passes before considering it for merging.
118+ Even regular contributors who test religiously on their local box (using tox
119+ for example) often rely on a PR+travis=green to make double sure everything
120+ works ok on another system, as occasionally, it doesn't.
121+
122+ ####Steps to enable Travis-CI
123+
124+ - go to https://travis-ci.org/
125+ - "Sign in with Github", on top panel.
126+ - \[your username\]/Account, on top-panel.
127+ - 'sync now' to refresh the list of repos on your GH account.
128+ - flip the switch on the repos you want Travis-CI enabled for,
129+ "pandas" obviously.
130+ - Then, pushing a *new* commit to a certain branch on that repo
131+ will trigger a build/test for that branch, for example the branch
132+ might be "master" or "PR1234_fix_all_the_things", if that's the
133+ name of your PR branch.
134+
135+ You can see the build history and current builds for your fork
136+ on: https://travis-ci.org/(your_GH_username)/pandas.
137+
138+ For example, the builds for the main pandas repo can be seen at:
139+ https://travis-ci.org/pydata/pandas.
140+
141+ ####More developer docs
142+
58143Please see [Developers](http://pandas.pydata.org/developers.html) page on
59144the project website for more details.
0 commit comments