Thank you for your interest in contributing to openswmm.engine! This document outlines the governance model, contribution workflow, and standards that keep the project healthy, reproducible, and scientifically rigorous. Please read it carefully before opening an issue, submitting a pull request, or proposing a major change.
- Community Governance
- Repository & Technical Management
- Succession & Delegation
- Licensing, Intellectual Property & CLA
- Author Acknowledgment
- How to Cite openswmm.engine
- Versioning Strategy
- Deprecation & Backward Compatibility Policy
- Branching Model
- Bug Fixes & Small Improvements
- Pull Request Process
- Continuous Integration & Automated Testing
- Issue Reporting
- Review Timeline Expectations
- Major Project Formulation Changes
- Conflict of Interest in Reviews
- Regression & Validation Testing
- Documentation Standards
- Dependency Evaluation Policy
- Security Vulnerability Reporting
- Roadmap & Prioritization
- Code of Conduct
openswmm.engine is a community-driven open source project. All contributors are welcome regardless of affiliation, background, or experience level. The community operates on a model of open discussion, merit-based evaluation, and transparent decision-making. Key decisions affecting the project direction are made openly on GitHub, and all community members are encouraged to participate.
Repository and technical management is the responsibility of the Technical Manager (currently @cbuahin).
The Technical Manager is responsible for:
- Maintaining the integrity and health of the
main,dev, andexperimentalbranches. - Setting and enforcing coding standards, testing requirements, and documentation guidelines.
- Triaging issues and pull requests in a timely manner.
- Making final decisions on merges, releases, and branch management.
- Coordinating with the community on roadmap items and governance questions.
Community members who wish to take on elevated responsibilities (e.g., becoming a recurring reviewer or branch maintainer) may express interest by opening a discussion on GitHub.
The Technical Manager role is a single point of authority, which must be protected against absence or unavailability.
- In the event the Technical Manager is unavailable for an extended period (e.g., travel, illness, or leave), they may designate a Temporary Delegate with equivalent merge and release authority. The delegation will be announced publicly in GitHub Discussions.
- If the Technical Manager steps down permanently, the outgoing manager will nominate a successor from the active contributor community. The nomination is subject to a community feedback period of at least two weeks before taking effect.
- In the absence of a named delegate and in urgent situations (e.g., a critical security fix), any two senior community reviewers may jointly approve and merge a patch to
main, with a written rationale posted to GitHub Discussions immediately afterward.
openswmm.engine is released under the MIT License.
All contributors must sign the project Contributor License Agreement (CLA) before their pull request can be merged. The CLA is detailed in CLA.md. Key points:
- You retain your copyright. The CLA grants a license; it does not transfer ownership.
- Broad license grant. You grant the Technical Manager a perpetual, irrevocable license to use, distribute, and relicense your contribution (e.g., for future dual open-source/commercial licensing).
- Patent grant. You grant a royalty-free patent license covering patents necessarily infringed by your contribution.
- Representation of authority. You confirm you have the right to submit the contribution and that it contains no unlicensed third-party material.
- Corporate contributors must additionally submit a Corporate CLA (CCLA) — see CLA.md §6.
The project uses CLA Assistant. When you open your first pull request, a bot will post a comment with a signing link. You may also sign manually by posting the following comment on your PR:
I have read the CLA Document and I hereby sign the CLA.
Once signed, the CLA covers all future contributions. You do not need to sign again.
If your contribution includes third-party code or data, you are responsible for ensuring that the third-party license is compatible with MIT and that proper attribution is included in your submission.
The full license text is available in LICENSE.
All contributors whose work is incorporated into openswmm.engine will be recognized in AUTHORS.md.
- Name, affiliation (if any), and scope of contribution will be documented for each contributor.
- The Technical Manager maintains
AUTHORS.mdand will update it at each release. - If you believe your contribution has been omitted or mis-described, please open an issue or contact the Technical Manager directly.
Contributors are encouraged to add themselves to AUTHORS.md as part of their pull request, subject to review and formatting consistency.
If you use openswmm.engine in published research, teaching materials, or engineering reports, please cite the software to give appropriate credit and help others discover the project.
Until a formal publication is available, please cite the software repository directly:
Buahin, C. (2026). openswmm.engine [Computer software]. GitHub. https://github.com/cbuahin_github/openswmm.engine
Each stable release of openswmm.engine is archived and assigned a DOI via Zenodo. The DOI for each release is listed in the GitHub Releases page and in the repository badge. When citing a specific version, use the version-specific DOI so that your reference is reproducible.
If a peer-reviewed publication describing the software or a specific formulation becomes available, it will be listed here and should be preferred over the repository citation. Authors of accepted publications describing openswmm.engine contributions are encouraged to notify the Technical Manager so the reference can be added.
openswmm.engine follows Semantic Versioning (SemVer) as defined at semver.org, with formal pre-release trajectories during testing periods.
MAJOR.MINOR.PATCH[-PRERELEASE]
| Component | When to increment |
|---|---|
MAJOR |
Incompatible API or formulation changes; fundamental engine restructuring |
MINOR |
New features or model components added in a backward-compatible manner |
PATCH |
Backward-compatible bug fixes, documentation updates, or performance improvements |
During active release testing periods, the following pre-release labels are used in sequence:
| Stage | Label example | Purpose |
|---|---|---|
| Alpha | 1.2.0-alpha.1 |
Early feature-complete builds, internal or limited testing; may be unstable |
| Beta | 1.2.0-beta.1 |
Feature-frozen; broader community testing; known issues may exist |
| Release Candidate | 1.2.0-rc.1 |
Final candidate for release; only critical bug fixes accepted |
| Stable | 1.2.0 |
Fully validated, production-ready release |
Pre-release builds are tagged in Git and published to the appropriate distribution channel with clear labels to prevent unintended use in production workflows.
openswmm.engine is committed to giving users adequate notice before breaking changes are introduced.
- Announcement — A feature, API, or behavior to be removed is first marked as deprecated in the release notes and in code (via comments or compiler warnings, as applicable). The deprecation announcement will state the planned removal version.
- Minimum notice period — Deprecated items will not be removed for at least one full minor version cycle following the deprecation announcement. For widely-used public APIs, a minimum of one major version cycle is preferred.
- Removal — Deprecated items are removed in a
MAJORversion bump, never in aMINORorPATCHrelease.
PATCHreleases are guaranteed to be fully backward-compatible.MINORreleases are backward-compatible for all stable public APIs.MAJORreleases may introduce breaking changes, which will be documented in a migration guide published alongside the release.
Experimental APIs (clearly marked as such) carry no backward compatibility guarantee and may change or be removed in any release.
| Branch | Purpose |
|---|---|
main |
Stable, production-ready code. Only receives merges from release candidates. |
dev |
Integration branch for ongoing development. All feature and bug-fix branches target here. |
experimental/<name> |
Sandboxed branches for exploratory or major formulation changes. See Section 15. |
bugfix/<issue-id>-desc |
Short-lived branches forked from dev to address specific bug reports. |
feature/<name> |
Short-lived branches for minor feature additions, forked from dev. |
release/<version> |
Release preparation branches (alpha → beta → rc) cut from dev. |
For small, well-scoped bug fixes and minor improvements, follow this workflow:
- Open or reference an issue. Verify the bug is reproducible and link the relevant issue number in all subsequent commits and pull requests.
- Fork the
devbranch. Name your branchbugfix/<issue-id>-short-description(e.g.,bugfix/42-overflow-in-routing). - Write a failing unit test first. The test must demonstrate the defect before the fix is applied.
- Implement the minimal fix. Touch only the code necessary to resolve the issue. Do not refactor adjacent code.
- Ensure all regression tests pass. If a regression test fails as a result of your change, you must either:
- Fix the regression, or
- Provide a written, technically justified explanation for why the regression failure is acceptable (included in the pull request description).
- Submit a pull request against
devfollowing the process described in Section 11.
All contributions enter the codebase through a pull request (PR). PRs must satisfy the following requirements before they can be merged:
Every PR requires all three of the following approvals:
| Reviewer | Role |
|---|---|
| Technical Manager | @cbuahin (current Technical Manager) — final authority on code quality, architecture, and correctness |
| AI Copilot Review | Automated AI-assisted review for style, logic, and common error patterns |
| Community Reviewer | At least one community contributor other than the PR author must approve |
Self-approvals are not permitted. The PR author may not count toward the community reviewer requirement.
Before requesting review, confirm that your PR:
- Targets the correct branch (
devfor bug fixes and features; see Section 15 for experimental work) - CLA signed — first-time contributors must sign the CLA before the PR can be merged
- Includes a clear description of what was changed and why
- References any related issues (e.g.,
Closes #42) - Includes new or updated unit tests covering the change
- All existing regression tests pass (or failures are documented and justified)
- CI pipeline passes (see Section 12)
- Documentation has been updated where applicable (Doxygen comments, README, etc.)
-
AUTHORS.mdentry has been added or updated if this is your first contribution
- Merges into
mainare performed exclusively by the Technical Manager at release time. - Squash merging is preferred for
bugfixandfeaturebranches to keep thedevhistory clean. - Merge commits are used when integrating
devinto areleasebranch to preserve the full history.
All pull requests are automatically tested via the project's CI pipeline (GitHub Actions) before human review begins. A failing CI pipeline will block merge regardless of approvals.
The CI pipeline runs on every push to a PR branch and includes:
| Stage | Description |
|---|---|
| Build | Compiles the engine and test suite across all supported platforms (Linux, macOS, Windows) |
| Unit Tests | Runs the full unit test suite; any failure blocks the PR |
| Regression Tests | Runs the analytical benchmark suite; deviations outside tolerance thresholds block the PR |
| Static Analysis | Runs a linter and static analyzer (e.g., clang-tidy) to catch common errors |
| Documentation Build | Verifies that Doxygen documentation builds without errors or warnings |
Contributors are expected to run the test suite locally before opening a PR to minimize unnecessary CI failures. Instructions for running tests locally are in the README.
Use the Bug Report issue template on GitHub. A complete bug report must include:
- A clear, descriptive title.
- The version of openswmm.engine affected (e.g.,
1.2.0-beta.1). - The operating system and compiler version.
- A minimal reproducible example — the smallest input file or code snippet that demonstrates the problem.
- Observed vs. expected behavior, including any relevant output or error messages.
Incomplete bug reports may be closed or deprioritized pending clarification.
Use the Feature Request issue template for small, well-scoped additions. For proposals that would change the core physical or mathematical formulation, use the GitHub Discussions Ideas section instead (see Section 15).
The Technical Manager or a designated reviewer will triage new issues within two weeks of submission, assigning labels (e.g., bug, enhancement, needs-clarification, wontfix) and priority. Contributors are encouraged to comment on existing issues before opening duplicates.
openswmm.engine is maintained by volunteers. The following timelines are targets, not guarantees, but the Technical Manager is committed to keeping them:
| Action | Target Timeline |
|---|---|
| Initial issue triage | Within 2 weeks |
| First review response on a PR | Within 3 weeks |
| Follow-up review after requested changes | Within 2 weeks |
| Major formulation discussion response | Within 4 weeks |
If you have not received a response within the stated window, you are welcome to post a polite follow-up comment on the issue or PR. PRs that become stale (no activity for 60 days) may be closed with a note that they can be reopened when the contributor is ready to continue.
Changes that affect the core physical or mathematical formulation of the engine — including new process models, numerical schemes, or significant algorithmic restructuring — follow a more rigorous governance process to protect the scientific integrity of the project.
Start a new thread in the Ideas section of the GitHub Discussions tab. Your proposal should describe:
- The scientific or engineering motivation for the change.
- The anticipated impact on existing functionality and results.
- Any known limitations, tradeoffs, or open questions.
- References to relevant literature or prior implementations.
Allow a minimum of four weeks for community members to respond. The Technical Manager will facilitate the discussion and summarize the consensus or key points of disagreement. A proposal may be:
- Accepted for prototyping — community finds sufficient merit to proceed.
- Revised — further refinement is needed before prototyping.
- Deferred — not a current priority; may be revisited in a future release cycle.
- Declined — not aligned with the project scope or scientifically unsound.
Accepted proposals are implemented in a dedicated experimental/<name> branch. Requirements for this phase:
- Rigorous unit tests covering the new formulation's behavior across the expected parameter space.
- Regression tests as described in Section 17.
- Code must compile cleanly and not break the existing test suite on the
devbranch. - Implementation notes and algorithm descriptions must be maintained in Doxygen-compatible documentation.
Where the improvement represents a meaningful scientific advance, contributors are strongly encouraged to submit a peer-reviewed publication describing the formulation, validation methodology, and results. Publication is not a hard requirement, but it significantly strengthens the case for incorporation into the core engine and signals readiness for production use. The Technical Manager can advise on suitable journals or conferences.
See Section 17 for full details. At minimum, the experimental implementation must demonstrate:
- Correctness against problems with known analytical solutions.
- Agreement within acceptable tolerance with the legacy engine and previous versions on benchmark problems.
- No unacceptable degradation in computational performance or numerical stability.
Before a major formulation change can be merged into dev, the following documentation must be complete:
- Doxygen comments on all new and modified public APIs, structs, and functions.
- Inline citations linking to peer-reviewed references where the formulation is derived from published work.
- Updated user-facing documentation (e.g., README sections, wiki pages) describing the new capability and how to invoke it.
- A changelog entry summarizing the change for the next release notes.
Scientific software reviews can intersect with contributors' professional interests. To protect the integrity of the review process:
- A reviewer who has a competing or closely related implementation, active publication, or financial interest in the outcome of a review must disclose this conflict before participating in the review.
- A conflicted reviewer may participate in discussion but may not serve as one of the three required approvers for that PR.
- The Technical Manager makes the final determination on whether a disclosed conflict disqualifies a reviewer on a case-by-case basis.
- Undisclosed conflicts of interest, if discovered after a merge, may trigger a re-review of the affected contribution.
Validation testing is a cornerstone of scientific software development. openswmm.engine uses two complementary regression testing modes:
Test cases are constructed for which a closed-form or exact analytical solution exists. The engine output must agree with the analytical solution within a specified tolerance (defined per test case). These tests verify the mathematical correctness of the implementation independent of any reference implementation.
Examples include: mass balance checks, steady-state flow solutions, unit hydrograph convolutions, and simplified routing scenarios with exact solutions.
A suite of reference problems is maintained that have been previously executed with:
- The legacy engine (EPA SWMM or equivalent predecessor), and/or
- A prior stable release of openswmm.engine.
New implementations must reproduce reference outputs within acceptable tolerance bounds. Deviations must be documented and scientifically justified — they may be acceptable if the new formulation is demonstrably more correct, but the deviation must be explicit and reviewed.
All benchmarks are evaluated across three dimensions:
| Criterion | Description |
|---|---|
| Stability | The solver must not exhibit divergence, oscillation, or blow-up under standard test conditions |
| Conservativeness | Mass, volume, or energy conservation must be maintained within defined tolerances |
| Computational Performance | Runtime must not degrade unacceptably relative to the previous version for equivalent problem sizes |
Performance benchmarks are run on a reference hardware configuration documented in the test suite. Significant regressions in performance require justification and, where possible, mitigation.
openswmm.engine uses Doxygen for API documentation. All public-facing code elements (functions, classes, structs, enumerations, and their members) must include Doxygen-compatible documentation comments.
Minimum documentation per element:
@brief— one-line summary.@param— description of each parameter including units where applicable.@return— description of the return value.@note/@warning— any important behavioral caveats.@refor@cite— citation of the relevant literature where the implementation follows a published formulation.
Documentation is reviewed as part of the pull request process. PRs with undocumented public APIs will not be approved.
Adding a third-party dependency increases the maintenance burden and risk surface of the project. All proposed new dependencies must be evaluated against the following criteria before inclusion:
| Criterion | Requirement |
|---|---|
| License compatibility | The dependency's license must be compatible with MIT (e.g., MIT, BSD, Apache 2.0). Copyleft licenses such as GPL are not permitted. |
| Maintenance status | The dependency must be actively maintained with a responsive upstream community. |
| Stability | The dependency must have a stable, versioned API. Unpinned or volatile dependencies are not acceptable. |
| Binary footprint | Dependencies that substantially increase compiled binary size must be justified by proportional benefit. |
| Platform support | The dependency must support all officially targeted platforms (Linux, macOS, Windows). |
Proposals to add a new dependency should be raised in a GitHub Discussion or issue before implementation. Optional or experimental dependencies that are not required for the core build may be included under a feature flag, with lower scrutiny, provided they meet the license requirement.
Do not report security vulnerabilities through public GitHub issues.
If you discover a potential security vulnerability in openswmm.engine, please report it privately so that a fix can be prepared before the issue is publicly disclosed:
- GitHub Private Advisory: Use the Security Advisories tab to submit a draft advisory directly on GitHub. Tag @cbuahin (current Technical Manager) in the advisory.
Please include in your report:
- A description of the vulnerability and its potential impact.
- Steps to reproduce, including any relevant input files or code.
- The version(s) of openswmm.engine affected.
- Any known mitigations or workarounds.
The Technical Manager will acknowledge receipt within five business days and work with you on a coordinated disclosure timeline. Credit for responsibly disclosed vulnerabilities will be given in the release notes and security advisory, unless the reporter prefers to remain anonymous.
The project maintains a public roadmap that communicates the planned direction of openswmm.engine across upcoming releases. The roadmap is updated by the Technical Manager and is available in ROADMAP.md.
The roadmap includes:
- Features and formulation improvements targeted for upcoming
MINORandMAJORreleases. - Known issues and technical debt items scheduled for resolution.
- Research directions under exploration in
experimentalbranches. - Items that have been explicitly deferred or declined, along with the rationale.
The roadmap is a living document and is updated at each release and after significant community discussions. Contributors are encouraged to align their proposals with roadmap priorities to maximize the likelihood of acceptance. Proposals that fall outside the current roadmap scope are still welcome and will be evaluated on merit, but may be deferred to a future cycle.
Community members who wish to influence roadmap priorities should participate in the GitHub Discussions Ideas section. The Technical Manager reviews discussion threads when updating the roadmap and will reference specific threads in roadmap entries where community input shaped a decision.
openswmm.engine is committed to providing a welcoming, respectful, and inclusive environment for all contributors. All participants are expected to:
- Engage constructively and professionally in all project spaces (issues, pull requests, discussions).
- Respect differing viewpoints and scientific perspectives.
- Accept constructive criticism of their contributions in good faith.
- Prioritize the long-term health of the project over individual preferences.
Harassment, personal attacks, or exclusionary behavior of any kind will not be tolerated. Violations may be reported to the Technical Manager at @cbuahin. Reported incidents will be reviewed and addressed promptly and confidentially.
This document is maintained by the Technical Manager of openswmm.engine (currently @cbuahin). Last updated: May 2026.