1Contributing guidelines 2======================= 3 4This page explains how you can contribute to the development of `statsmodels` 5by submitting patches, statistical tests, new models, or examples. 6 7`statsmodels` is developed on `Github <https://github.com/statsmodels/statsmodels>`_ 8using the `Git <https://git-scm.com/>`_ version control system. 9 10Submitting a Bug Report 11~~~~~~~~~~~~~~~~~~~~~~~ 12 13- Include a short, self-contained code snippet that reproduces the problem 14- Specify the statsmodels version used. You can do this with ``sm.version.full_version`` 15- If the issue looks to involve other dependencies, also include the output of ``sm.show_versions()`` 16 17Making Changes to the Code 18~~~~~~~~~~~~~~~~~~~~~~~~~~ 19 20For 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. 21 22- **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. 23- 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 <https://www.statsmodels.org/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.) 24- Code submissions must always include tests. See our `notes on testing <https://www.statsmodels.org/devel/dev/test_notes.html>`_. 25- Each function, class, method, and attribute needs to be documented using docstrings. We conform to the `numpy docstring standard <https://numpydoc.readthedocs.io/en/latest/format.html#docstring-standard>`_. 26- If you are adding new functionality, you need to add it to the documentation by editing (or creating) the appropriate file in ``docs/source``. 27- Make sure your documentation changes parse correctly. Change into the top-level ``docs/`` directory and type:: 28 29 make clean 30 make html 31 32 Check that the build output does not have *any* warnings due to your changes. 33- 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. 34 35Linting 36~~~~~~~ 37 38Due to the way we have the CI builds set up, the linter will not do anything unless the environmental variable $LINT is set to a truthy value. 39 40- On MacOS/Linux 41 42 LINT=true ./lint.sh 43 44- Dependencies: flake8, git 45 46How to Submit a Pull Request 47~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 48 49So you want to submit a patch to `statsmodels` but are not too familiar with github? Here are the steps you need to take. 50 511. `Fork <https://help.github.com/articles/fork-a-repo>`_ the `statsmodels repository <https://github.com/statsmodels/statsmodels>`_ on Github. 522. `Create a new feature branch <https://git-scm.com/book/en/Git-Branching-Basic-Branching-and-Merging>`_. Each branch must be self-contained, with a single new feature or bugfix. 533. Make sure the test suite passes. This includes testing on Python 3. The easiest way to do this is to make a pull request and let the bot check for you. This can be slow, and if you are unsure about the fix or enhancement, it is best to run pytest locally. 544. Document your changes by editing the appropriate file in ``docs/source/``. If it is a big, new feature add a note and an example to the latest ``docs/source/release/versionX.X.rst`` file. See older versions for examples. If it's a minor change, it will be included automatically in our release notes. 555. Add an example. If it is a big, new feature please submit an example notebook by following `these instructions <https://www.statsmodels.org/devel/dev/examples.html>`_. 566. `Submit a pull request <https://help.github.com/articles/using-pull-requests>`_ 57 58Mailing List 59~~~~~~~~~~~~ 60 61Conversations about development take place on the `statsmodels mailing list <https://groups.google.com/group/pystatsmodels?hl=en>`__. 62 63Learn More 64~~~~~~~~~~ 65 66The ``statsmodels`` documentation's `developer page <https://www.statsmodels.org/stable/dev/index.html>`_ 67offers much more detailed information about the process. 68 69License 70~~~~~~~ 71 72statsmodels is released under the 73`Modified (3-clause) BSD license <https://www.opensource.org/licenses/BSD-3-Clause>`_. 74