Contributing#
Thank you for your interest in contributing to the BIOMASS Processing Suite (BPS). We welcome contributions from the scientific community, industrial partners, and external developers.
How a contribution flows#
Every contribution follows the same five steps. No code is written before the issue has been approved. This is a deliberate guardrail that protects contributors from wasted effort and protects the project from scope creep.
Pick one of the five templates: bug report, feature or enhancement request, algorithm proposal, documentation issue, or security report.
A maintainer reviews the issue and applies routing labels:
needs-triage, needs-sme, or needs-discussion.
The issue is labelled status:approved, good-first-issue,
or help-wanted. Until one of these labels is set, do not code.
Fork, branch, commit with Signed-off-by (DCO), open a pull request
that links the issue.
CODEOWNERS review, CI green, squash merge. The linked issue closes automatically.
For questions or open-ended discussions that are not yet a concrete issue, use GitHub Discussions. Issues are reserved for actionable items.
The three stages#
flowchart TD
subgraph Before["1. Proposal and approval"]
direction TB
Backlog["Backlog"]
PathA["Path A<br/>Pick an approved issue"]
PathB["Path B<br/>Propose a new issue"]
Gate{"Wait for the label<br/><code>status:approved</code><br/><code>good-first-issue</code><br/><code>help-wanted</code>"}
Backlog --> PathA
Backlog --> PathB
PathA --> Gate
PathB --> Gate
end
subgraph Building["2. Implementation"]
direction TB
Fork["Fork & branch"]
Implement["Implement + tests"]
Local["Local checks<br/>ruff · mypy · pytest"]
Commit["Commit signed off"]
OpenPR["Open the PR"]
Fork --> Implement --> Local --> Commit --> OpenPR
end
subgraph After["3. Review and integration"]
direction TB
CI{"CI status"}
Review["Review"]
Merge["Squash merge"]
Released["Released<br/>tag + DOI"]
Iterate["Iterate<br/>push fixes"]
CI -->|green| Review
Review --> Merge
Merge --> Released
CI -->|red| Iterate
Iterate --> CI
end
Gate -->|approved| Fork
OpenPR --> CI
classDef gate fill:#FFE082,stroke:#FFB300,color:#000
class Gate gate
1. Proposal and approval
Backlog, issue templates, triage, and the approval gate. Do not code until the issue is approved.
2. Implementation
Fork, implement, local checks, DCO-signed commits, and open the pull request.
3. Review and integration
CI green/red loop, review, baseline changes, merge, and release path.
Foundations#
Licensing
Apache 2.0 terms, REUSE compliance, SPDX headers, and dependency licence requirements. Every contribution must comply.
Code of Conduct
Community standards that govern interactions inside the project. Required reading for all contributors.
Governance
Roles (Maintainer, SME, ESA), decision authority, and the chain of approvals. Who decides what, and when.
Quick reference#
CI automation and contribution tiers
Tier classification, CI job catalog, branch protection, and judge-from-base policy.
Templates and checklists
Issue and PR templates, CODEOWNERS routing, and pre-submission checklists.
Quality and validation
Testing, scientific validation, backwards compatibility, and documentation expectations.
Practical workflow
Environment setup, Git commands, and code examples for tests and standards.
Becoming a maintainer
Path from contributor to maintainer: stages, qualities, and responsibilities.
Community
Meetings, GitHub Discussions categories, workshops, and communication channels.
Release process
Maintainer runbook: develop to release to main, versioning, and ESA gate.
Technical reference#
Architecture
Monorepo layout, bps-* modules, dependency graph, and processor structure.
Code standards
Naming, formatting, type hints, tests, error handling, and logging.
Documentation standards
Docstrings, writing conventions, and documentation update expectations.
Interface specifications
Official ICD, IODD, and auxiliary product format PDFs for integrators.
Need help? Use GitHub Discussions. The Q&A category is the recommended place for usage questions, and Scientific discussions is the right space for algorithm and methodology questions.