Contributing to xsnow

Contributing to xsnow#

Contributions from users, developers, and researchers are welcome—whether you are reporting a bug, suggesting an improvement, or developing new features.

1. How to get started#

You can contribute to xsnow in several ways:

  • Report bugs or unexpected behavior

  • Suggest improvements to the API, implementation, or documentation

  • Submit merge requests with code or documentation

Development and collaboration is managed through AvaCollabra’s Gitlab group. The repository is accessible at avacollabra/postprocessing/xsnow.

To contribute, please sign up to GitLab and submit issues or merge requests through the xsnow repository. You can find the relevant links in the repository itself, or by hovering over the GitLab fox icon at the top of this page.

2. Reporting bugs and suggesting improvements#

You can report bugs or suggest improvements directly through the GitLab issue tracker.

Use the “Open issue” link by hovering over the Gitlab fox icon at the top of this page.

When reporting a bug, please include:

  • A clear description of the problem

  • Steps to reproduce (ideally with a small code example)

  • Your system and environment (OS, xsnow version)

  • Expected vs. actual behavior

If you are suggesting improvements:

  • Briefly sketch the status quo

  • Explain the use case of the modification or new feature and why it adds value

  • Include a minimal sketch or example if possible

Tip

You can also suggest improvements to documentation or tutorials directly via the “Suggest edit” link. This opens a pre-filled merge request with your changes.

3. Submitting changes via merge requests#

To propose changes to the code or documentation:

  1. Create a new branch from dev (see the next section on Branch strategy).

  2. Implement your changes and commit them with clear, descriptive messages.
    Tip: Follow this excellent short guide on how to write a good commit message.

  3. Open a merge request in GitLab targeting the dev branch.

Merge request checklist#

  • New features come with tests

  • Code runs without errors and passes local tests.

  • Documentation strings (docstrings) are complete.

  • Tutorials and docstring examples are updated if the interface changed.

  • No temporary debug prints or unused imports remain.

  • The feature branch merges cleanly into dev (no pending merge conflicts).

4. Branch strategy#

xsnow uses a simple and transparent branching model that keeps development organized.

Branch

Purpose

Description

main

Stable branch

Contains the latest stable version of xsnow. Every commit here is deployable and well tested.

dev

Development branch

Used for active integration of new features and fixes before merging to main.

feature/*

New features

For developing new functionality or modules. Example: feature/dask.

fix/*

Bug fixes

For resolving issues found during testing or usage. Example: fix/parser.

chore/*

Chores

For refactoring, maintenance, etc.

docs/*

Documentation

For improving or extending documentation/tutorials.

Key guidelines#

  • Always branch off from dev

  • Keep your branch focused—one topic, one branch.

  • Maintainers will handle reviews, approvals, and merges into main for release.

Note

Think of main as the stable (released) branch and dev as the active integration branch.
Feature branches are short-lived and should be merged or deleted once completed.

5. Testing strategy#

xsnow uses pytest for automated testing.

To run the test suite locally:

cd xsnow
pytest

All tests are located in the tests/ directory and include unit, integration, and performance tests. All new functionality should include appropriate test cases, and any existing tests broken by your changes should ideally be fixed before merging.

Further details on the testing structure and conventions are available in tests/README.md.

6. Code style#

We try to follow a clean, modern Python style:

  • Follow PEP8.

  • Use type hints for public interfaces.

  • Write docstrings following the NumPy style guide.

  • Each module and function should have a clear description of purpose, parameters, and returns.

7. Documentation and tutorials#

Tutorials and API documentation (auto-generated from the source code) live under docs/.
To preview locally:

cd xsnow/docs/
make html

The output appears under _build/html. You can view it in your browser.

All contributions that add or change functionality should include updates to relevant tutorials or docstrings.

Tip

If you just want to fix a typo or clarify a sentence, use the “Suggest edit” link directly from the docs—this will open a merge request automatically.

8. CPU versus GPU#

Developers should make sure that large computations can be carried out on CPU (default) as well as GPU soon as the user environment and installation supports that. Currently, xsnow.extensions.critical_crack_length is the only module that implements this capability and can be used as template.

Contents