1
- Guidelines
2
- ---
1
+ ###Guidelines
3
2
4
3
All contributions, bug reports, bug fixes, documentation improvments,
5
4
enhancements and ideas are welcome.
@@ -12,34 +11,70 @@ Please try and follow these guidelines, as this makes it easier for us to accept
12
11
your contribution or address the issue you're having.
13
12
14
13
- 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__`).
17
26
- 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)
18
30
19
31
- When submitting a Pull Request
20
32
- **Make sure the test suite passes**., and that means on python3 as well.
21
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.
22
35
- We suggest you enable Travis-CI on your fork, to make it easier for the team
23
36
to see that the PR does indeed pass all the tests.
24
37
- Back-compatiblitiy **really** matters. Pandas already has a large user-base and
25
38
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.
30
43
- Performance matters. You can use the included "test_perf.sh"
31
44
script to make sure your PR does not introduce any performance regressions
32
45
in the library.
46
+ - docstrings follow the [numpydoc](https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt) format.
33
47
- **Don't** merge upstream into a branch you're going to submit as a PR,
34
48
This can create all sorts of problems. Use "git rebase" instead. This ensures
35
49
no merge conflicts occur when you're code is merged by the core team.
36
50
- 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.
43
78
- For extra brownie points, use "git rebase -i" to squash and reorder
44
79
commits in your PR so that the history makes the most sense. Use your own
45
80
judgment to decide what history needs to be preserved.
@@ -52,8 +87,58 @@ your contribution or address the issue you're having.
52
87
- If your code changes are intermixed with style fixes, they are harder to review
53
88
before merging. Keep style fixes in separate commits.
54
89
- 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.
55
91
56
92
Having said that, if you still feel a PEP8 storm is in order, go for it.
57
93
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
+
58
143
Please see [Developers](http://pandas.pydata.org/developers.html) page on
59
144
the project website for more details.
0 commit comments