Skip to content

Commit 239d1be

Browse files
jtratnerjtratner
committed
Merge pull request #5086 from westurner/patch-2
DOC: CONTRIBUTING.md: Gold plating: syntax, punctuation, Markdown format...
2 parents bc3a3bb + 372226c commit 239d1be

File tree

1 file changed

+104
-90
lines changed

1 file changed

+104
-90
lines changed

‎CONTRIBUTING.md

Lines changed: 104 additions & 90 deletions
Original file line numberDiff line numberDiff line change
@@ -3,147 +3,161 @@
33
All contributions, bug reports, bug fixes, documentation improvements,
44
enhancements and ideas are welcome.
55

6-
The Github "issues" tab contains some issues labels "Good as first PR", these are
6+
The [GitHub "issues" tab](https://github.com/pydata/pandas/issues)
7+
contains some issues labeled "Good as first PR"; these are
78
tasks which do not require deep knowledge of the package. Look those up if you're
89
looking for a quick way to help out.
910

1011
Please try and follow these guidelines, as this makes it easier for us to accept
1112
your contribution or address the issue you're having.
1213

13-
- When submitting a bug report:
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/) :
14+
#### Bug Reports
1615

17-
```
18-
```python
16+
- Please include a short, self-contained Python snippet reproducing the problem.
17+
You can have the code formatted nicely by using [GitHub Flavored Markdown](http://github.github.com/github-flavored-markdown/) :
1918

20-
print("I ♥ pandas!")
19+
```python
20+
21+
print("I ♥ pandas!")
2122

22-
``'
23-
```
23+
```
2424

25-
- Specify the pandas (and numpy) version used. (you can check `pandas.__version__`).
25+
- A [test case](https://github.com/pydata/pandas/tree/master/pandas/tests) may be more helpful.
26+
- Specify the pandas (and NumPy) version used. (check `pandas.__version__`
27+
and `numpy.__version__`)
2628
- 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)
30-
31-
- When submitting a Pull Request
32-
- **Make sure the test suite passes**., and that means on python3 as well.
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.
35-
- If you are changing any code, you need to enable Travis-CI on your fork,
29+
- If the issue seems to involve some of [pandas' dependencies](https://github.com/pydata/pandas#dependencies)
30+
such as
31+
[NumPy](http://numpy.org),
32+
[matplotlib](http://matplotlib.org/), and
33+
[PyTables](http://www.pytables.org/)
34+
you should include (the relevant parts of) the output of
35+
[`ci/print_versions.py`](https://github.com/pydata/pandas/blob/master/ci/print_versions.py).
36+
37+
#### Pull Requests
38+
39+
- **Make sure the test suite passes** for both python2 and python3.
40+
You can use `test_fast.sh`, **tox** locally, and/or enable **Travis-CI** on your fork.
41+
See "Getting Travis-CI going" below.
42+
- An informal commit message format is in effect for the project. Please try
43+
and adhere to it. Check `git log` for examples. Here are some common prefixes
44+
along with general guidelines for when to use them:
45+
- **ENH**: Enhancement, new functionality
46+
- **BUG**: Bug fix
47+
- **DOC**: Additions/updates to documentation
48+
- **TST**: Additions/updates to tests
49+
- **BLD**: Updates to the build process/scripts
50+
- **PERF**: Performance improvement
51+
- **CLN**: Code cleanup
52+
- Commit messages should have:
53+
- a subject line with `< 80` chars
54+
- one blank line
55+
- a commit message body, if there's a need for one
56+
- If you are changing any code, you should enable Travis-CI on your fork
3657
to make it easier for the team to see that the PR does indeed pass all the tests.
37-
- Back-compatibility **really** matters. Pandas already has a large user-base and
38-
a lot of existing user code. Don't break old code if you can avoid it
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.
43-
- Performance matters. You can use the included "test_perf.sh"
44-
script to make sure your PR does not introduce any performance regressions
58+
- **Backward-compatibility really matters**. Pandas already has a large user base and
59+
a lot of existing user code.
60+
- Don't break old code if you can avoid it.
61+
- If there is a need, explain it in the PR.
62+
- Changes to method signatures should be made in a way which doesn't break existing
63+
code. For example, you should beware of changes to ordering and naming of keyword
64+
arguments.
65+
- Add deprecation warnings where needed.
66+
- Performance matters. You can use the included `test_perf.sh`
67+
script to make sure your PR does not introduce any new performance regressions
4568
in the library.
46-
- docstrings follow the [numpydoc](https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt) format.
47-
- **Don't** merge upstream into a branch you're going to submit as a PR,
48-
This can create all sorts of problems. Use "git rebase" instead. This ensures
49-
no merge conflicts occur when you're code is merged by the core team.
50-
- An informal commit message format is in effect for the project, please try
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
69+
- Docstrings follow the [numpydoc](https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt) format.
70+
- **Don't** merge upstream into a branch you're going to submit as a PR.
71+
This can create all sorts of problems. Use `git rebase` instead. This ensures
72+
no merge conflicts occur when your code is merged by the core team.
73+
- Please reference the GH issue number in your commit message using `GH1234`
74+
or `#1234`. Either style is fine.
75+
- Use `raise AssertionError` rather then plain `assert` in library code (`assert` is fine
76+
for test code). `python -o` strips assertions. Better safe than sorry.
77+
- When writing tests, don't use "new" assertion methods added to the `unittest` module
6778
in 2.7 since pandas currently supports 2.6. The most common pitfall is:
6879

69-
with self.assertRaises(ValueError):
70-
foo
80+
with self.assertRaises(ValueError):
81+
foo
82+
7183

72-
which fails on python 2.6. You need to use `assertRaises` from
84+
which fails with Python 2.6. You need to use `assertRaises` from
7385
`pandas.util.testing` instead (or use `self.assertRaises(TheException,func,args)`).
7486

75-
- doc/source/release.rst and doc/source/vx.y.z.txt contain an on-going
76-
changelog for each release as it is worked on. Add entries to these files
77-
as needed in a separate commit in your PR, documenting the fix, enhancement
87+
- `doc/source/release.rst` and `doc/source/vx.y.z.txt` contain an ongoing
88+
changelog for each release. Add entries to these files
89+
as needed in a separate commit in your PR: document the fix, enhancement,
7890
or (unavoidable) breaking change.
79-
- For extra brownie points, use "git rebase -i" to squash and reorder
91+
- For extra brownie points, use `git rebase -i` to squash and reorder
8092
commits in your PR so that the history makes the most sense. Use your own
8193
judgment to decide what history needs to be preserved.
82-
- Pandas source code should not (with some exceptions, such as 3rd party licensed code),
83-
generally speaking, include an "Authors:" list or attribution to individuals in source code.
84-
The RELEASE.rst details changes and enhancements to the code over time,
85-
a "thanks goes to @JohnSmith." as part of the appropriate entry is a suitable way to acknowledge
86-
contributions, the rest is git blame/log.
94+
- Pandas source code should not -- with some exceptions, such as 3rd party licensed code --
95+
generally speaking, include an "Authors" list or attribution to individuals in source code.
96+
`RELEASE.rst` details changes and enhancements to the code over time.
97+
A "thanks goes to @JohnSmith." as part of the appropriate entry is a suitable way to acknowledge
98+
contributions. The rest is `git blame`/`git log`.
8799
Feel free to ask the commiter who merges your code to include such an entry
88-
or include it directly yourself as part of the PR if you'd like to. We're always glad to have
89-
new contributors join us from the ever-growing pandas community.
100+
or include it directly yourself as part of the PR if you'd like to.
101+
**We're always glad to have new contributors join us from the ever-growing pandas community.**
90102
You may also be interested in the copyright policy as detailed in the pandas [LICENSE](https://github.com/pydata/pandas/blob/master/LICENSE).
91103
- On the subject of [PEP8](http://www.python.org/dev/peps/pep-0008/): yes.
92104
- On the subject of massive PEP8 fix PRs touching everything, please consider the following:
93-
- They create merge conflicts for people working in their own fork.
94-
- They makes git blame less effective.
105+
- They create noisy merge conflicts for people working in their own fork.
106+
- They make `git blame` less effective.
95107
- Different tools / people achieve PEP8 in different styles. This can create
96108
"style wars" and churn that produces little real benefit.
97109
- If your code changes are intermixed with style fixes, they are harder to review
98110
before merging. Keep style fixes in separate commits.
99-
- it's fine to clean-up a little around an area you just worked on.
100-
- Generally its a BAD idea to PEP8 on documentation.
111+
- It's fine to clean-up a little around an area you just worked on.
112+
- Generally it's a BAD idea to PEP8 on documentation.
101113

102114
Having said that, if you still feel a PEP8 storm is in order, go for it.
103115

104-
### Notes on plotting functions convention
116+
### Notes on plotting function conventions
105117

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

108-
###Getting Travis-CI going
120+
### Getting Travis-CI going
109121

110-
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,
122+
Instructions for getting Travis-CI installed are available [here](http://about.travis-ci.org/docs/user/getting-started/).
123+
For those users who are new to Travis-CI and [continuous integration](https://en.wikipedia.org/wiki/Continuous_integration) in particular,
111124
Here's a few high-level notes:
112-
- Travis-CI is a free service (with premium account available), that integrates
113-
well with Github.
114-
- Enabling Travis-CI on your github fork of a project will cause any *new* commit
115-
pushed to the repo to trigger a full build+test on Travis-CI's servers.
116-
- All the configuration for travis's builds is already specified by .travis.yml in the repo,
117-
That means all you have to do is enable Travis-CI once, and then just push commits
118-
and you'll get full testing across py2/3 with pandas's considerable test-suite.
119-
- Enabling travis-CI will attach the test results (red/green) to the Pull-Request
120-
page for any PR you submit. For example:
125+
- Travis-CI is a free service (with premium account upgrades available) that integrates
126+
well with GitHub.
127+
- Enabling Travis-CI on your GitHub fork of a project will cause any *new* commit
128+
pushed to the repo to trigger a full build+test on Travis-CI's servers.
129+
- All the configuration for Travis-CI builds is already specified by `.travis.yml` in the repo.
130+
That means all you have to do is enable Travis-CI once, and then just push commits
131+
and you'll get full testing across py2/3 with pandas' considerable
132+
[test-suite](https://github.com/pydata/pandas/tree/master/pandas/tests).
133+
- Enabling Travis-CI will attach the test results (red/green) to the Pull-Request
134+
page for any PR you submit. For example:
121135

122136
https://github.com/pydata/pandas/pull/2532,
123137

124138
See the Green "Good to merge!" banner? that's it.
125139

126140
This is especially important for new contributors, as members of the pandas dev team
127-
like to know the test suite passes before considering it for merging.
141+
like to know that the test suite passes before considering it for merging.
128142
Even regular contributors who test religiously on their local box (using tox
129143
for example) often rely on a PR+travis=green to make double sure everything
130144
works ok on another system, as occasionally, it doesn't.
131145

132-
####Steps to enable Travis-CI
146+
#### Steps to enable Travis-CI
133147

134-
- go to https://travis-ci.org/
135-
- "Sign in with Github", on top panel.
136-
- \[your username\]/Account, on top-panel.
137-
- 'sync now' to refresh the list of repos on your GH account.
138-
- flip the switch on the repos you want Travis-CI enabled for,
139-
"pandas" obviously.
148+
- Open https://travis-ci.org/
149+
- Select "Sign in with GitHub" (Top Navbar)
150+
- Select \[your username\] -> "Accounts" (Top Navbar)
151+
- Select 'Sync now' to refresh the list of repos from your GH account.
152+
- Flip the switch for the repos you want Travis-CI enabled for.
153+
"pandas", obviously.
140154
- Then, pushing a *new* commit to a certain branch on that repo
141-
will trigger a build/test for that branch, for example the branch
142-
might be "master" or "PR1234_fix_all_the_things", if that's the
143-
name of your PR branch.
155+
will trigger a build/test for that branch. For example, the branch
156+
might be `master` or `PR1234_fix_everything__atomically`, if that's the
157+
name of your PR branch.
144158

145159
You can see the build history and current builds for your fork
146-
on: https://travis-ci.org/(your_GH_username)/pandas.
160+
at: https://travis-ci.org/(your_GH_username)/pandas.
147161

148162
For example, the builds for the main pandas repo can be seen at:
149163
https://travis-ci.org/pydata/pandas.

0 commit comments

Comments
 (0)