This package is in very early stages. Lots of work is needed.
You can help out just by using
xhistogram and reporting
The following sections cover some general guidelines for maintainers and
contributors wanting to help develop
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
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.
Adding documentation is always helpful. This may include:
More complementary documentation. Have you perhaps found something unclear?
Example notebooks of
xhistogrambeing used in real analyses.
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 _build/html/index.html
To lint the reStructuredText documentation files run:
$ doc8 doc/*.rst
Preparing Pull Requests¶
Fork the xhistogram GitHub repository. It’s fine to use
xhistogramas your fork repository name because it will live under your username.
Clone your fork locally, connect your repository to the upstream (main project), and create a branch to work on:
$ git clone email@example.com:YOUR_GITHUB_USERNAME/xhistogram.git $ cd xhistogram $ git remote add upstream firstname.lastname@example.org:xgcm/xhistogram.git $ git checkout -b your-bugfix-feature-branch-name master
If you need some help with Git, follow this quick start guide
Install dependencies into a new conda environment:
$ conda env create -f ci/environment-3.9.yml $ conda activate xhistogram_test_env
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 .
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.
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-commitwill 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
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
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.
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.
xhistogramdevelopers and contributors can then review your code and offer suggestions.
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.
Add documentation for contributors. By Dougie Squire.
Minor bugfix release