Code Contribution Guide

A guide for contributing to the MATLAB and Python implementations of the channel replay library, covering setup, coding standards, and pull requests.

Thank you for considering a contribution to UWA-Channels. Bug reports, feature requests, documentation improvements, and code changes are all welcome.

This guide explains how to contribute effectively to the two companion repositories hosted at https://github.com/uwa-channels:

RepositoryLanguageMain BranchFolder Layout
uwa-channels/matlabMATLAB (R2021a+)mainsrc/, tests/, examples/
uwa-channels/pythonPython (≥ 3.10)mainsrc/uwa_channels/, tests/, examples/

The library’s Julia support is hosted separately, in the UnderwaterAcoustics.jl package maintained by the Acoustic Research Laboratory. Please refer to that repository’s own contribution guidelines for Julia-specific bug reports and pull requests.

Getting started

Prerequisites

  • Familiarity with Git, GitHub, Markdown, and either MATLAB or Python.
    Helpful references: GitHub Quickstart, Markdown Guide.

  • Development environment:

    MATLAB repository

    git clone https://github.com/uwa-channels/matlab.git

    To run example scripts:

    cd examples
example_replay

    To run tests:

    cd tests
addpath('../src')
runtests('testReplay')

    Python repository: create a virtual environment and install dependencies:

    git clone https://github.com/uwa-channels/python.git
cd python
pip install numpy scipy matplotlib h5py pytest pre-commit

    To run example scripts:

    PYTHONPATH=src python examples/example_replay.py

    To run tests:

    PYTHONPATH=src pytest

    To initialize pre-commit:

    pre-commit install
pre-commit run --all-files

Code of conduct

We expect all contributors to be professional, respectful, and constructive. By participating, you agree to uphold these standards.

Bug reports, feature requests, and discussions

Bug reports

  • Search existing issues and pull requests; your bug may already be reported or fixed.
  • Provide a minimal, reproducible example (MATLAB .m file or live script, or a Python snippet), along with:
    • Package versions (uwa_channels.__version__ or MATLAB ver)
    • OS and MATLAB/Python version, if relevant

Feature requests

Describe both the motivation and the proposed change. Sketch a possible API or workflow if applicable.

Discussions

General Q&A, design ideas, and roadmap conversations belong in GitHub Discussions, not in Issues.

Issue labels

LabelMeaning
high-priority / low-priorityRelative urgency
good first issueSuitable for newcomers
breaking-changeAPI/behavior change

Issues planned for release are tracked with a GitHub milestone rather than a label.

Workflow for code and documentation changes

  1. Fork the repository and clone your fork.
  2. Create a branch from main, named like topic-short-description (lowercase, hyphen-separated).
  3. Develop locally:
    • MATLAB: run runtests('tests') and address Code Analyzer (MLint) warnings.
    • Python: run PYTHONPATH=src pytest frequently.
  4. Write tests for new features or bug fixes.
  5. Document your changes:
    • Use NumPy-style docstrings in Python functions and classes.
    • Use MATLAB help text headers; add usage examples for public APIs.
  6. Commit with clear messages, then push to your fork.
  7. Open a pull request (PR) against main. Mark it as “Draft” if it’s not yet ready for review. Reference any related issues.
  8. Address reviewer feedback. Once all checks pass and approvals are received, a maintainer will merge.

Commit message style

We follow a simplified version of Conventional Commits:

<type>(<scope>): <summary>

<body>
  • type ∈ {feat, fix, docs, test, perf, refactor, style, chore, revert}
  • scope identifies the module or subsystem (e.g., io, replay, noisegen)
  • Use imperative mood for the summary (e.g., “add support for…” not “added support for…”)
  • Limit the summary to ≤ 50 characters; wrap the body at 72 characters
  • If the change is breaking, begin the body with BREAKING CHANGE:

Examples:

feat(replay): add resampling support for replay channels
fix(io): handle empty .mat files (issue #42)

Coding standards

MATLAB

Follow the MATLAB Style Guide:

  • 4-space indentation; snake_case for functions, PascalCase for classes
  • Each function/class in its own .m file
  • Use arguments blocks for input validation where possible
  • Add unit tests as flat files directly under tests/ using MATLAB Unit Test
  • Vectorize where possible; comment non-obvious logic

Python

  • Formatting is enforced via Black and Ruff (Ruff handles import sorting, so a separate isort pass is unnecessary)
  • Static analysis via Flake8, Ruff, mypy, and Bandit
  • Use NumPy-style docstrings with LaTeX equations where helpful
  • Keep functions short, prefer clarity to cleverness, and avoid premature optimization

Testing and continuous integration

RepositoryLocal Test CommandCI Matrix
MATLABruntests('tests')MATLAB R2021a and latest
PythonPYTHONPATH=src pytestPython 3.10–3.12

All CI checks must pass before a pull request is merged.

Release process (Python only)

Maintainers tag releases using git tag -s vX.Y.Z following Semantic Versioning (SemVer).

Merged PRs are reflected in CHANGELOG.md, with entries auto-generated from commit messages.

Acknowledgements

This guide was inspired by the excellent UnderwaterAcoustics.jl contributing guide, as well as the contribution guidelines of NumPy and SciPy, and the MATLAB Style Guide.

Happy hacking: may your channels be peaceful and your SNR high!