Contributing

Contributing#

We welcome contributions to the BEAM ecosystem! Whether it’s reporting issues, suggesting features, improving the documentation, or submitting pull requests, your input helps improve these tools for the community.

How to contribute#

There are many ways to get involved:

  • Report bugs - Found something not working as expected? Open an issue with as much detail as possible.

  • Request a feature - Got an idea for a new feature or enhancement? Open a feature request on GitHub Issues.

  • Improve the documentation - If something is missing or unclear, feel free to suggest edits or open a pull request.

  • Submit code changes - Bug fixes, refactoring, and new features are all welcome.

Code#

git clone --recursive https://github.com/epochpic/sdf-xarray.git
cd sdf-xarray
pip install .

Style#

We use Ruff to maintain code quality and formatting. This can be installed locally via the lint dependency group:

pip install --group lint

Ruff can then be run with:

ruff check src tests

Alternatively, uv users can do this in one step with uv run:

uv run ruff check src tests

Many of the issues raised by Ruff can be fixed automatically:

ruff check --fix src tests

Ruff may also be used to format the code to a style similar to that enforced by Black, which (almost) matches the PEP-8 standard:

ruff format src tests

Running and adding tests#

We use pytest to run tests. All new functionality should include relevant tests, placed in the tests/ directory and following the existing structure.

When running the tests for the first time you will need an internet connection in order to download the datasets.

Before submitting code changes, ensure that all tests pass:

pip install --group test
pytest

Alternatively, uv users can use:

uv run pytest

Documentation#

Style#

When contributing to the documentation:

  • Wrap lines at 80 characters.

  • Follow the format of existing .rst files.

  • Link to external functions or tools when possible.

Compiling and adding documentation#

When compiling the documentation for the first time you will need an internet connection in order to download the datasets.

To build the documentation locally, first install the required packages:

pip install --group docs
cd docs
make html

The documentation can be updated by changing any of the *.rst files located in the main docs directory. The existing documentation hopefully includes most of the snippets you’d need to write or update it, however if you are stuck please don’t hesitate to reach out.

Every time you make changes to the documentation or add a new page, you must re-run the make html command to regenerate the HTML files.

Previewing documentation#

Using VS Code extensions#

Once the html web pages have been made you can review them installing the Live Server VS Code extension. Navigate to the _build/html folder, right-click the index.html, and select “Open with Live Server”. This will open a live preview of the documentation in your web browser.

Using a simple python server#

Alternatively, if you’re not using VS Code, you can start a simple local server with Python:

python -m http.server -d _build/html

Then open http://localhost:8000 in your browser to view the documentation.

Continuous integration#

All pull requests are automatically checked using GitHub Actions for:

  • Linting and formatting (ruff)

  • Testing (pytest)

  • Cross-platform building (cibuildwheel)

These checks must pass before a pull request can be merged.

Contents