Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
169 lines (121 loc) · 4.76 KB

CONTRIBUTING.md

File metadata and controls

169 lines (121 loc) · 4.76 KB

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

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

The documentation is stored under the /docs folder and is written in Markdown files following the MyST-NB format.

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

pip install --group docs

The documentation can be updated by changing any of the *.md 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.

Building the documentation

You can build the documentation using either auto-building (recommended for active development) or manual building.

Auto-building

Run the following command from the docs folder in order to auto-rebuild the documentation when you save changes in any of the docs/*.md, src/sdf_xarray/*.py or update the CONTRIBUTING.md file:

make livehtml

This should spin up a local server for the documentation which you can open in your browser. Example output including what changing a file should produce in the terminal:

[sphinx-autobuild] Starting initial build
[sphinx-autobuild] > python -m sphinx build . _build/html --builder html --quiet
[sphinx-autobuild] Serving on http://127.0.0.1:8000
[sphinx-autobuild] Waiting to detect changes...
[sphinx-autobuild] Detected changes (key_functionality.md)
[sphinx-autobuild] Rebuilding...
[sphinx-autobuild] > python -m sphinx build . _build/html --builder html --quiet
[sphinx-autobuild] Serving on http://127.0.0.1:8000

Manual building

If you prefer to rebuild the documentation manually, run the following command from the docs folder:

make html

Once the html web pages have been made you can review them by installing the Live Server VS Code extension. Navigate to the docs/_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.

Alternatively if you do not wish to install a VS Code extension run the following command from the docs folder:

python -m http.server -d _build/html

Then open the link it gives you in the 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.