Merge pull request statsmodels#1052 from jseabold/contrib-docs

DOC: Updating contributing docs

CONTRIBUTING.rst

@@ -7,23 +7,40 @@ by submitting patches, statistical tests, new models, or examples.
 `statsmodels` is developed on `Github <https://github.com/statsmodels/statsmodels>`_ 
 using the `Git <http://git-scm.com/>`_ version control system. 
 
-License
-~~~~~~~
+Submitting a Bug Report
+~~~~~~~~~~~~~~~~~~~~~~~
 
-Statsmodels is released under the 
-`Modified (3-clause) BSD license <http://www.opensource.org/licenses/BSD-3-Clause>`_.
+- Include a short, self-contained code snippet that reproduces the problem
+- Specify the statsmodels version used. You can do this with ``sm.version.full_version``
+- If the issue looks to involve other dependencies, also include the output of ``sm.show_versions()``
+
+Making Changes to the Code
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+For a pull request to be accepted, you must meet the below requirements. This greatly helps in keeping the job of maintaining and releasing the software a shared effort.
+
+- **One branch. One feature.** Branches are cheap and github makes it easy to merge and delete branches with a few clicks. Avoid the temptation to lump in a bunch of unrelated changes when working on a feature, if possible. This helps us keep track of what has changed when preparing a release.
+- Commit messages should be clear and concise. This means a subject line of less than 80 characters, and, if necessary, a blank line followed by a commit message body. We have an `informal commit format standard <http://statsmodels.sourceforge.net/devel/dev/maintainer_notes.html#commit-comments>`_ that we try to adhere to. You can see what this looks like in practice by ``git log --oneline -n 10``. If your commit references or closes a specific issue, you can close it by mentioning it in the `commit message <https://help.github.com/articles/closing-issues-via-commit-messages>`_.  (*For maintainers*: These suggestions go for Merge commit comments too. These are partially the record for release notes.)
+- Code submissions must always include tests. See our `notes on testing <https://statsmodels.sourceforge.net/devel/dev/test_notes.html>`_.
+- Each function, class, method, and attribute needs to be documented using docstrings. We conform to the `numpy docstring standard <https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt#docstring-standard>`_.
+- If you are adding new functionality, you need to add it to the documentation by editing (or creating) the appropriate file in ``docs/source``.
+- Make sure your documentation changes parse correctly. Change into the top-level ``docs/`` directory and type::
+  
+   make clean
+   make html
 
-Submitting a Patch
-~~~~~~~~~~~~~~~~~~
+  Check that the build output does not have *any* warnings due to your changes. 
+- Finally, please add your changes to the release notes. Open the ``docs/source/release/versionX.X.rst`` file that has the version number of the next release and add your changes to the appropriate section.
 
-So you want to submit a patch to `statsmodels`?. Great news! Here are the 
-steps you need to take.
+How to Submit a Pull Request
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+So you want to submit a patch to `statsmodels` but aren't too familiar with github? Here are the steps you need to take.
 
 1. `Fork <https://help.github.com/articles/fork-a-repo>`_ the `statsmodels repository <https://github.com/statsmodels/statsmodels>`_ on Github.
-2. `Create a new feature branch <http://git-scm.com/book/en/Git-Branching-Basic-Branching-and-Merging>`_
-    + Each branch must be self-contained, with a single new feature or bugfix. 
-    + Patches must always include tests. See our `notes on testing <test_notes.html>`_.
-3. `Submit a pull request <https://help.github.com/articles/using-pull-requests>`_ 
+2. `Create a new feature branch <http://git-scm.com/book/en/Git-Branching-Basic-Branching-and-Merging>`_. Each branch must be self-contained, with a single new feature or bugfix. 
+3. Make sure the test suite passes. This includes testing on Python 3. The easiest way to do this is to either enable `Travis-CI <https://travis-ci.org/>`_ on your fork, or to make a pull request and check there.
+4. `Submit a pull request <https://help.github.com/articles/using-pull-requests>`_ 
 
 Mailing List
 ~~~~~~~~~~~~
@@ -35,3 +52,9 @@ Learn More
 
 The ``statsmodels`` documentation's `developer page <http://statsmodels.sourceforge.net/stable/dev/index.html>`_ 
 offers much more detailed information about the process.
+
+License
+~~~~~~~
+
+Statsmodels is released under the 
+`Modified (3-clause) BSD license <http://www.opensource.org/licenses/BSD-3-Clause>`_.

docs/source/dev/index.rst

@@ -8,29 +8,52 @@ by submitting patches, statistical tests, new models, or examples.
 <https://github.com/statsmodels/statsmodels>`_ using the `Git
 <http://git-scm.com/>`_ version control system. 
 
-License
-~~~~~~~
+Submitting a Bug Report
+~~~~~~~~~~~~~~~~~~~~~~~
 
-Statsmodels is released under
-the `Modified (3-clause) BSD license <http://www.opensource.org/licenses/BSD-3-Clause>`_.
+- Include a short, self-contained code snippet that reproduces the problem
+- Specify the statsmodels version used. You can do this with ``sm.version.full_version``
+- If the issue looks to involve other dependencies, also include the output of ``sm.show_versions()``
+
+Making Changes to the Code
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+For a pull request to be accepted, you must meet the below requirements. This greatly helps the job of maintaining and releasing the software a shared effort.
+
+- **One branch. One feature.** Branches are cheap and github makes it easy to merge and delete branches with a few clicks. Avoid the temptation to lump in a bunch of unrelated changes when working on a feature, if possible. This helps us keep track of what has changed when preparing a release.
+- Commit messages should be clear and concise. This means a subject line of less than 80 characters, and, if necessary, a blank line followed by a commit message body. We have an `informal commit format standard <http://statsmodels.sourceforge.net/devel/dev/maintainer_notes.html#commit-comments>`_ that we try to adhere to. You can see what this looks like in practice by ``git log --oneline -n 10``. If your commit references or closes a specific issue, you can close it by mentioning it in the `commit message <https://help.github.com/articles/closing-issues-via-commit-messages>`_.  (*For maintainers*: These suggestions go for Merge commit comments too. These are partially the record for release notes.)
+- Code submissions must always include tests. See our `notes on testing <https://statsmodels.sourceforge.net/devel/dev/test_notes.html>`_.
+- Each function, class, method, and attribute needs to be documented using docstrings. We conform to the `numpy docstring standard <https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt#docstring-standard>`_.
+- If you are adding new functionality, you need to add it to the documentation by editing (or creating) the appropriate file in ``docs/source``.
+- Make sure your documentation changes parse correctly. Change into the top-level ``docs/`` directory and type::
+  
+   make clean
+   make html
 
-Submitting a Patch
-~~~~~~~~~~~~~~~~~~~
+  Check that the build output does not have *any* warnings due to your changes. 
+- Finally, please add your changes to the release notes. Open the ``docs/source/release/versionX.X.rst`` file that has the version number of the next release and add your changes to the appropriate section.
 
-So you want to submit a patch to `statsmodels`?. Great news! Here are the 
-steps you need to take.
+How to Submit a Pull Request
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+So you want to submit a patch to `statsmodels` but aren't too familiar with github? Here are the steps you need to take.
 
 1. `Fork <https://help.github.com/articles/fork-a-repo>`_ the `statsmodels repository <https://github.com/statsmodels/statsmodels>`_ on Github.
-2. `Create a new feature branch <http://git-scm.com/book/en/Git-Branching-Basic-Branching-and-Merging>`_
-    + Each branch must be self-contained, with a single new feature or bugfix. 
-    + Patches must always include tests. See our `notes on testing <test_notes.html>`_.
-3. `Submit a pull request <https://help.github.com/articles/using-pull-requests>`_ 
+2. `Create a new feature branch <http://git-scm.com/book/en/Git-Branching-Basic-Branching-and-Merging>`_. Each branch must be self-contained, with a single new feature or bugfix. 
+3. Make sure the test suite passes. This includes testing on Python 3. The easiest way to do this is to either enable `Travis-CI <https://travis-ci.org/>`_ on your fork, or to make a pull request and check there.
+4. `Submit a pull request <https://help.github.com/articles/using-pull-requests>`_ 
 
 Mailing List
 ~~~~~~~~~~~~
 
 Conversations about development take place on the `statsmodels mailing list <http://groups.google.com/group/pystatsmodels?hl=en>`__.
 
+License
+~~~~~~~
+
+Statsmodels is released under
+the `Modified (3-clause) BSD license <http://www.opensource.org/licenses/BSD-3-Clause>`_.
+
 Contents
 ~~~~~~~~
 

docs/source/release/version0.6.rst

@@ -0,0 +1,46 @@
+:orphan:
+
+===========
+0.6 Release
+===========
+
+Release 0.6.0
+=============
+
+Release summary.
+
+Major changes:
+
+Header for Change
+~~~~~~~~~~~~~~~~~
+
+Change blurb and example code.
+
+Other important new features
+----------------------------
+
+* Other new changes can go
+* In a 
+* Bullet list
+
+Major Bugs fixed
+----------------
+
+* Bullet list of major bugs
+* With a link to its github issue.
+* Use the syntax ``:ghissue:`###```.
+
+Backwards incompatible changes and deprecations
+-----------------------------------------------
+
+* Note any backwards incompatible changes here
+
+Development summary and credits
+-------------------------------
+
+A blurb about the number of changes and the contributors list.
+
+.. note:: 
+
+   Obtained by running ``git log v0.5.0..HEAD --format='* %aN <%aE>' | sed 's/@/\-at\-/' | sed 's/<>//' | sort -u``.
+