Contributing

How to contribute to pycWB—pull request workflow, code style, and review process.

Getting Started

  1. Fork the repo on GitHub or LIGO GitLab. The repositories are mirrored; contributors outside LVK can use GitHub without an LVK account.

  2. Set up your dev environment (Development Setup).

  3. Find an issue or propose a new feature.

  4. Create a branch: feature/<description> or fix/<description>.

Pull Request Workflow

Submit a pull request on GitHub or a merge request on LIGO GitLab after pushing your branch to your fork.

# 1. Create a branch
git checkout -b feature/my-new-module

# 2. Make changes + tests
# ... edit code ...

# 3. Run tests locally
pytest
python -m unittest discover tests/

# 4. Commit with descriptive message
git commit -m "Add my_new_module: <one-line description>

<Paragraph explaining what, why, and any design decisions>"

# 5. Push and create MR/PR
git push origin feature/my-new-module

Code Style

  • Python: Follow PEP 8. Use type hints for all public functions.

  • Docstrings: NumPy-style with Parameters/Returns/Raises sections.

  • Naming: snake_case for functions/variables, CamelCase for classes, UPPER_CASE for constants.

  • Imports: standard library → third-party → pycwb internal, each group separated by a blank line.

  • Logging: use logging.getLogger(__name__), not print().

  • Config parameters: snake_case, descriptive names with units in the schema description.

What to Include in a PR

Every pull request should include:

  1. Code changes — focused, minimal diff.

  2. Unit tests — covering new functionality and edge cases.

  3. Docstring updates — if public API changes.

  4. Release notes — brief user-visible notes in the MR/PR description, or a statement that there are no user-visible changes.

  5. Schema update — if new config parameters are added.

Update affected guides, migration examples and scientific behavior documentation as part of the change. Maintainers consolidate release notes from merged MR/PR descriptions into CHANGES.md when preparing a release. Routine contributions do not need to edit that shared file.

For new modules, also include: - __init__.py with public API imports - tests/__init__.py - At least one test file

Review Checklist

Reviewers will check:

  • [ ] Tests pass locally and in CI

  • [ ] New code has tests

  • [ ] Docstrings are complete and accurate

  • [ ] No new ROOT dependencies (ROOT is being phased out)

  • [ ] Constants and generic utilities do not import workflows or scientific stages.

    Scientific modules may reuse domain algorithms and native payloads, but do not import workflows. Shared CUDA runtime code lives in pycwb.utils.gpu. Workflow modules own stage assembly, scheduling and output lifecycle.

  • [ ] Hot-path code uses Numba or JAX, not pure NumPy

  • [ ] JAX device buffers are freed after use

  • [ ] Config schema updated for new parameters

  • [ ] MR/PR description includes release notes for user-visible changes

  • [ ] No breaking changes to the YAML config format without migration path

Documentation Maintenance

Keep the documentation roles distinct:

  • Tutorials: one worked experiment with supplied inputs, runnable steps and an output to inspect. Keep general configuration alternatives in a linked guide.

  • How-to guides: procedures for the reader’s own data, configuration or environment. Maintain each procedure here once; link a tutorial for practice.

  • Task routes: short input/guide/completion summaries. Link the procedure instead of copying its YAML, commands or option tables into a recipe.

  • Concepts and methods: explanations and numerical/scientific conventions.

  • Reference: exact parameters, interfaces and data formats.

When moving content, update internal links and retain a forwarding page for existing URLs and section anchors. Keep shared tutorial inputs in examples/.

Every PR that changes user-facing behavior must update the docs:

If you changed…

Update…

A config parameter (new or modified)

user_parameters_schema.py + User Parameters

A pipeline stage or algorithm

The relevant Concepts and methods page + Pipeline Lifecycle

A CLI command or workflow

The owning How-to guides page + CLI Reference; update task routes and worked examples when affected

A public Python API

Docstring in the source file (auto-documented in pycwb)

The build or test system

Build & Test

A new term or concept

Glossary

Anything user-facing

PycWB documentation and the relevant section index (check navigation and links)

PR doc checklist (add to PR description):

- [ ] Docstring updated (if API changed)
- [ ] Schema page updated (if new/changed params)
- [ ] Core Concepts page updated (if algorithm changed)
- [ ] Owning how-to guide updated (if procedure changed)
- [ ] Task route links updated (if workflow changed)
- [ ] Tutorial/example inputs updated (if worked experiment changed)
- [ ] Glossary updated (if new terms)
- [ ] Release notes included in MR/PR description
- [ ] Migration/scientific behavior documentation updated (if affected)

Release Process

Releases are versioned with setuptools_scm from Git tags. Follow Release procedure for the release checklist and Releases and Compatibility for compatibility notes. The GitLab tag pipeline publishes the source distribution; do not duplicate that upload manually.

Where to Ask Questions

See Help and Community for public issues and an email contact for contributors who cannot access the tracker. LIGO Slack is an additional collaboration channel, not a prerequisite for contributing.