Skip to content

Latest commit

 

History

History
152 lines (103 loc) · 5.5 KB

CONTRIBUTING.rst

File metadata and controls

152 lines (103 loc) · 5.5 KB
Raw

Contributing Guidelines

We welcome user contributions to nbodykit, but be sure to read this guide first to make the process as smooth as possible!

Requesting a Feature

You can use GitHub issues to request features you would like to see in nbodykit.

  1. Provide a clear and detailed explanation of the feature you want to add and its use case in large-scale structure data analysis. Keep in mind that the goal is to include features that are useful for a wide set of users.
  2. If you are able, start writing some code and attempt a pull request. Be sure to read the :ref:`submission guidelines <PR-guide>`. There are often several features competing for time commitments, and user pull requests are greatly appreciated!

Bug Reporting

If you think you've found a bug in nbodykit, follow these steps to submit a report:

  1. First, double check that your bug isn't already fixed. Follow our :ref:`instructions <local-dev>` for setting up a local development environment and make sure you've installed the tip of the master branch.

  2. Search for similar issues on GitHub. Make sure to delete is:open on the issue search to find solved tickets as well. It is possible that this bug has been encountered before.

  3. Please include the versions of Python, nbodykit, and other dependency libraries if they are applicable (numpy, scipy, etc)

  4. Provide us with the logging output of the script from when the bug was encountered, including a traceback if appropriate. If at all possible, provide us with a standalone script that will reproduce the issue. Issues have a much higher chance of being resolved quickly if we can easily reproduce the bug.

  5. Take a stab at fixing the bug yourself! The :mod:`runtests` module used by nbodykit supports on-line debugging via the PDB interface. It also supports drop-in replacements for PDB such as PDB++. A common debugging route is to add a regression unit test to the nbodykit test suite that fails due the bug and then run the test in debugging mode:

    $ python run-tests.py nbodykit/path/to/your/test --pdb

    :ref:`Pull requests <PR-guide>` for bug fixes are always welcome!

We strongly recommend following the above steps and providing as much information as possible when bugs are encountered. This will help us resolve issues faster -- and get everyone back to doing more accurate science!

Setting up for Local Development

  1. Fork nbodykit on GitHub:

    $ git clone https://github.com/bccp/nbodykit.git
$ cd nbodykit

  2. Install the dependencies. We recommend using the Anaconda environment manager. To create a new environment for nbodykit development, use:

    # create and activate a new conda environment
$ conda create -n nbodykit-dev python=3
$ source activate nbodykit-dev

# install requirements
$ conda install -c bccp --file requirements.txt --file requirements-extras.txt

  3. Install nbodykit in develop mode using pip:

    # install in develop mode
$ pip install -e .

Opening a Pull Request

  1. Write the code implementing your bug fix or feature, making sure to use detailed commit messages.

  2. Ensure that any new code is properly documented, with docstrings following the NumPy/Scipy documentation style guide.

  3. Write tests of the new code, ensuring that it has full unit test coverage. This is a crucial step as new pull requests will not be merged if they reduce the overall test coverage of nbodykit.

  4. Run the test suite locally. From the main nbodykit directory, run:

    $ python run-tests.py --with-coverage --html-cov

    This will also output the test coverage statistics to build/coverage/index.html.

  5. Make sure all of the tests have passed and that the coverage statistics indicate that any new code is fully covered by the test suite.

  6. Be sure to update the changelog to indicate what was added/modified.

  7. Submit your pull request to nbodykit:master. The Travis CI build must be passing before your pull request can be merged. Additionally, the overall coverage of the test suite must not decrease for the pull request to be merged.

Contributing to the Cookbook

If you have an application of nbodykit that is concise and interesting, please consider adding it to our :ref:`cookbook of recipes <cookbook>`. We also welcome feedback and improvements for these recipes. Users can submit issues or open a pull request on the nbodykit cookbook repo on GitHub.

Cookbook recipes should be in the form of Jupyter notebooks. See the existing recipes for examples. The recipes are designed to illustrate interesting uses of nbodykit for other users to learn from.

We appreciate any and all contributions!