Contributor Guide

This package is in very early stages. Lots of work is needed.

You can help out just by using xhistogram and reporting issues.

The following sections cover some general guidelines for maintainers and contributors wanting to help develop xhistogram.

Feature requests, suggestions and bug reports

We are eager to hear about any bugs you have found, new features you would like to see and any other suggestions you may have. Please feel free to submit these as issues.

When suggesting features, please make sure to explain in detail how the proposed feature should work and to keep the scope as narrow as possible. This makes features easier to implement in small PRs.

When report bugs, please include:

  • Any details about your local setup that might be helpful in troubleshooting, specifically the Python interpreter version, installed libraries, and xhistogram version.

  • Detailed steps to reproduce the bug, ideally a Minimal, Complete and Verifiable Example.

  • If possible, a demonstration test that currently fails but should pass when the bug is fixed.

Write documentation

Adding documentation is always helpful. This may include:

  • More complementary documentation. Have you perhaps found something unclear?

  • Docstrings.

  • Example notebooks of xhistogram being used in real analyses.

The xhistogram documentation is written in reStructuredText. You can follow the conventions in already written documents. Some helpful guides can be found here and here.

When writing and editing documentation, it can be useful to see the resulting build without having to push to Github. You can build the documentation locally by running:

$ # Install the packages required to build the docs in a conda environment
$ conda env create -f doc/environment.yml
$ conda activate xhistogram_doc_env
$ # Install the latest xhistogram
$ pip install --no-deps -e .
$ cd doc/
$ make html

This will build the documentation locally in doc/_build/. You can then open _build/html/index.html in your web browser to view the documentation. For example, if you have xdg-open installed:

$ xdg-open _build/html/index.html

To lint the reStructuredText documentation files run:

$ doc8 doc/*.rst

Preparing Pull Requests

  1. Fork the xhistogram GitHub repository. It’s fine to use xhistogram as your fork repository name because it will live under your username.

  2. Clone your fork locally, connect your repository to the upstream (main project), and create a branch to work on:

    $ git clone git@github.com:YOUR_GITHUB_USERNAME/xhistogram.git
    $ cd xhistogram
    $ git remote add upstream git@github.com:xgcm/xhistogram.git
    $ git checkout -b your-bugfix-feature-branch-name master
    

    If you need some help with Git, follow this quick start guide

  3. Install dependencies into a new conda environment:

    $ conda env create -f ci/environment-3.9.yml
    $ conda activate xhistogram_test_env
    
  4. Install xhistogram using the editable flag (meaning any changes you make to the package will be reflected directly in your environment):

    $ pip install --no-deps -e .
    
  5. Start making your edits. Please try to type annotate your additions as much as possible. Adding type annotations to existing unannotated code is also very welcome. You can read about Python typing here.

  6. Break your edits up into reasonably sized commits:

    $ git commit -a -m "<commit message>"
    $ git push -u
    

    It can be useful to manually run pre-commit as you make your edits. pre-commit will run checks on the format and typing of your code and will show you where you need to make changes. This will mean your code is more likely to pass the CI checks when you push it:

    $ pip install pre_commit # you only need to do this once
    $ pre-commit run --all-files
    
  7. Run the tests (including those you add to test your edits!):

    $ pytest xhistogram
    

    You can also test that your contribution and tests increased the test coverage:

    $ coverage run --source xhistogram -m py.test
    $ coverage report
    
  8. Add a new entry describing your contribution to the Release History in doc/contributing.rst. Please try to follow the format of the existing entries.

  9. Submit a pull request through the GitHub website.

    Note that you can create the Pull Request while you’re working on your PR. The PR will update as you add more commits. xhistogram developers and contributors can then review your code and offer suggestions.

Release History

v0.3.0

  • Add support for histograms over non-float dtypes (e.g. datetime objects) GH25. By Dougie Squire.

  • Refactor histogram calculation to use dask.array.blockwise when input arguments are dask arrays, resulting in significant performance improvements GH49. By Ryan Abernathy, Tom Nicholas and Gabe Joseph.

  • Fixed bug with density calculation when NaNs are present GH51. By Dougie Squire.

  • Implemented various options for users for providing bins to xhistogram that mimic the numpy histogram API. This included adding a range argument to the xhistogram API GH13. By Dougie Squire.

  • Added a function to check if the object passed to xhistogram is an xarray.DataArray and if not, throw an error. GH14. By Yang Yunyi.

v0.2.0

v0.1.3

v0.1.2

v0.1.1

Minor bugfix release

  • Imroved documentation examples. By Dhruv Balwada.

  • Fixed issue GH5 related to incorrect dimension order and dropping of dimension coordinates. By Ryan Abernathey.

v0.1

First release