Skip to content

Latest commit

 

History

History
108 lines (72 loc) · 3.66 KB

CONTRIBUTING.md

File metadata and controls

108 lines (72 loc) · 3.66 KB

Contributing Guide

This tutorial repository is a great opportunity to start contributing to Xarray.

  • Report bugs, request features or submit feedback as a GitHub Issue. First check existing issues !

  • Make fixes, add content or improvements using GitHub Pull Requests, the sections below go over this process in more detail:

The Project Pythia Foundations material on  [Github](https://foundations.projectpythia.org/foundations/getting-started-github.html) and Github workflows is a great place to start if you are new to this.

Content Guidelines

Please note that examples submitted to this repository should follow these guidelines:

  1. Run top-to-bottom without intervention from the user
  2. Not require external data sources that may disappear over time (external data sources that are highly unlikely to disappear are fine). Small datasets for tutorial purposes can be added here if necessary.
  3. Not be resource intensive, and should run within 2GB of memory
  4. Be clear and contain enough prose to explain the topic at hand
  5. Be concise and limited to one or two topics, such that a reader can get through the example within a few minutes of reading
  6. Be of general relevance to Xarray users, and so not too specific on a particular problem or use case.

Contribution process

Fork this repository

We recommend first forking this repository and creating a local copy:

git clone https://github.com/YOURACCOUNT/xarray-tutorial.git
cd xarray-tutorial

Create a Python environment

You'll need pixi or conda or mamba, which can be installed from https://github.com/conda-forge/miniforge

We also use pre-commit hooks to run styling and other checks before committing code.

Using pixi (recommended)

pixi install
pixi shell  # exit

Using conda

mamba env create -f .binder/environment.yml -n xarray-tutorial
conda activate xarray-tutorial  # conda deactivate
pre-commit install

Add content

Develop your new content on a branch. See JupyterBook Docs for guides on adding .md, .ipynb and other content.

git checkout -b newcontent
git add .
git commit -m "added pages x,y and improved z"

Preview your changes

Running jupyterbook will execute notebooks and render HTML pages for the website. Be sure to fix any execution errors and preview the website in your web browser to make sure everything looks good!

jupyter-book build ./ --warningiserror --keep-going
# Or "pixi run build"

Open a pull request

git push

Follow the link reported in a terminal to open a pull request!

Instructions for environment management

pixi can be used to create and update a multi-platform lockfile, so a reproducible set of package versions is installed across different operating systems.

Dependencies (with optional pins) are specified in the pyproject.toml file, and specific locked versions for all platforms are kept in pixi.lock.

Install environment from the lockfile

pixi install
pixi shell # activate environment, "exit" to deactivate

Upgrade all packages to latest versions:

pixi upgrade

Render conda/mamba environment files

pixi project export conda-environment -p linux-64 .binder/environment.yml
pixi project export conda-explicit-spec -p linux-64 /tmp