Merge pull request #9639 from rockg/contributing-docs

Rearrange into logical sections and add relevant links

Author: shoyer

CONTRIBUTING.md

@@ -1,4 +1,4 @@
-###Guidelines
+### Guidelines
 
 All contributions, bug reports, bug fixes, documentation improvements,
 enhancements and ideas are welcome.
@@ -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
@@ -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.
+  - 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
@@ -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.
+  - `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.
-  - 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.
@@ -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)