Bug reports and feature requests#
To report bugs or request new features, head over to the xbatcher repository.
GitHub has instructions for installing git, setting up your SSH key, and configuring git. All these steps need to be completed for you to work between your local repository and GitHub.
You will need your own fork to work on the code. Go to the xbatcher project
page and hit the
You will need to clone your fork to your machine:
git clone firstname.lastname@example.org:yourusername/xbatcher.git cd xbatcher git remote add upstream email@example.com:xarray-contrib/xbatcher.git
This creates the directory
xbatcher and connects your repository to
the upstream (main project) xbatcher repository.
Creating a development environment#
To test out code changes, you’ll need to build xbatcher from source, which requires a Python environment. If you’re making documentation changes, you can skip to Contributing to the documentation but you won’t be able to build the documentation locally before pushing your changes.
Creating a Python Environment#
Before starting any development, you’ll need to create an isolated xbatcher development environment:
Make sure your conda is up to date (
conda update conda)
Make sure that you have cloned the repository
cdto the xbatcher source directory
First we’ll create and activate the build environment:
conda env create --file ci/requirements/environment.yml conda activate xbatcher-tests
At this point you should be able to import xbatcher from your locally built version:
$ python # start an interpreter >>> import xbatcher >>> xbatcher.__version__
This will create the new environment, and not touch any of your existing environments, nor any existing Python installation.
To view your environments:
conda info --envs
To return to your base environment:
See the full conda docs here.
Setting up pre-commit#
We use pre-commit to manage code linting and style. To set up pre-commit after activating your conda environment, run:
Creating a branch#
You want your
main branch to reflect only production-ready code, so create a
feature branch before making your changes. For example:
git branch shiny-new-feature git checkout shiny-new-feature
The above can be simplified to:
git checkout -b shiny-new-feature
This changes your working directory to the shiny-new-feature branch. Keep any
changes in this branch specific to one bug or feature so it is clear
what the branch brings to xbatcher. You can have many “shiny-new-features”
and switch in between them using the
git checkout command.
To update this branch, you need to retrieve the changes from the
git fetch upstream git merge upstream/main
This will combine your commits with the latest xbatcher git
main. If this
leads to merge conflicts, you must resolve these before submitting your pull
request. If you have uncommitted changes, you will need to
git stash them
prior to updating. This will effectively store your changes, which can be
reapplied after updating.
Running the test suite#
xbatcher uses the pytest framework for testing. You can run the test suite using:
Running the performance test suite#
xbatcher is starting a suite of benchmarking tests using
asv to enable easy monitoring of
the performance of critical operations. These benchmarks are all found in the
To use all features of asv, you will need either
For more details please check the asv installation webpage.
To install asv:
pip install git+https://github.com/airspeed-velocity/asv
If you need to run a benchmark, change your directory to
asv_bench/ and run:
asv continuous -f 1.1 main <my-branch>
You can replace
my-branch with the name of the branch you are working on.
The output will include “BENCHMARKS NOT SIGNIFICANTLY CHANGED” if the
benchmarks did not change by more than 10%.
The command uses
conda by default for creating the benchmark
environments. If you want to use virtualenv instead, write:
asv continuous -f 1.1 -E virtualenv main <my-branch>
-E virtualenv option should be added to all
that run benchmarks. The default value is defined in
If you want to only run a specific group of tests from a file, you can do it
. as a separator. For example:
asv continuous -f 1.1 main HEAD -b benchmarks.Generator.time_batch_preload
will only run the
Generator.time_batch_preload benchmark defined in
Information on how to write a benchmark and how to use asv can be found in the asv documentation.
We greatly appreciate documentation improvements. The docs are built from the docstrings
in the code and the docs in the
To build the documentation, you will need to requirements listed in
You can create an environment for building the documentation using:
conda env create --file ci/requirements/docs.yml conda activate xbatcher-docs
You can then build the documentation using:
cd docs make html
Once you’ve made changes, you can see them by typing:
If you have created a new file, it is not being tracked by git. Add it by typing:
git add path/to/file-to-be-added.py
The following defines how a commit message should be structured:
A subject line with < 72 chars.
One blank line.
Optionally, a commit message body.
Now you can commit your changes in your local repository:
git commit -m
When you want your changes to appear publicly on your GitHub page, push your commits to a branch off your fork:
git push origin shiny-new-feature
origin is the default name given to your remote repository on GitHub.
You can see the remote repositories:
git remote -v
If you navigate to your branch on GitHub, you should see a banner to submit a pull request to the xbatcher repository.
Continuous integration is done with GitHub Actions.
There are currently 3 workflows configured: