Contributing to SIPNET¶
We welcome contributions. This page is the one‑stop guide for developers.
All contributors must follow the project Code of Conduct.
Developer Quickstart¶
- Clone the repository:
git clone git@github.com:PecanProject/sipnet cd sipnet
- Setup (once per clone, described below):
tools/setup.sh
- Build:
make
- Run a sample:
cd tests/smoke/niwot ../../../sipnet -i sipnet.in
Setup Script The tools/setup.sh
script verifies that Python ≥ 3.8 is available and that clang-format
, clang-tidy
, and git clang-format
are installed. Automatically installs clang
tools on macOS and prints installation instructions for Ubuntu/Debian. Then copies the clang pre‑commit hook into .git/hooks
so that code formatting is checked on every commit.
Note – running tools/setup.sh
is not necessary for documentation‑only edits,
but it will save you time whenever you touch C/C++ code.
GitHub Workflow¶
Branches¶
The master
branch is the default branch for SIPNET. Development should be done in feature branches. Feature branches should be named to clearly indicate the purpose, and may be combined with an associated issue, e.g. ISSUE#-feature-name
.
Pull Requests¶
Pull requests should be made from feature branches to the master
branch.
Pull request descriptions should include a brief summary of the changes and links to related issues.
Expectations for merging:
- Pass all unit and integration tests.
- Approved by at least one other developer before being merged.
- Include updates and additions to
- Documentation
- Tests
- CHANGELOG.md
- For new model features related to the structure, remove relevant \fraktur
font formatting from docs/model-structure.md
to indicate that the feature has been implemented.
Pull requests must pass all required checks to be merged into master, including the code format and style checks described below.
Code Format & Style¶
We follow the standard LLVM/Clang formatting rules. Formatting is automated with a pre-commit hook, so you wil rarely have to think about them.
To set up formatting and static analysis checks:
-
Run the setup script once (see Setup above).
It installs a pre‑commit hook that blocks any commit whose C/C++ files are not already formatted. -
If the hook stops your commit, run:
If# format only what you just staged git clang-format # restage fixes and commit again git add -u git commit
git clang-format
fails because not all changes are staged (likely agit commit -a
command), eithergit add
all the changes, or trygit clang-format -f
to reformat all modified files -
clang‑tidy static analysis runs automatically in CI.
If the bot leaves comments, adjust your code as instructed and push.To run
clang-tidy
manually before committing or pushing changes, use the following command from the project root:# Replace <path/to/filename.c> with the file you want to check clang-tidy <path/to/filename.c>
The hook and CI will tell you what to fix.
If a commit is blocked, format staged changes:
git clang-format
git add -u && git commit
git clang-format -f
.
- Optional local static analysis:
clang-tidy path/to/file.c
Documentation¶
- Build API docs (Doxygen) and site (MkDocs):
make document
-
Live preview while editing docs:
Updatepip install mkdocs mkdocs-material pymdown-extensions mkdocs serve # open http://127.0.0.1:8000/
mkdocs.yml
if you add/move pages. -
Build API docs (Doxygen) and site (MkDocs):
Outputs:make document
docs/api/
andsite/
. - Live preview while editing docs:
Update
pip install mkdocs mkdocs-material pymdown-extensions mkdocs serve # open http://127.0.0.1:8000/
mkdocs.yml
if you add/move pages.
Build¶
make
- See the project README.md for quick start. Use
make help
for all targets.
Testing¶
New features require tests.
- Unit tests:
make unit # or: make testbuild && ./tools/run_unit_tests.sh
- Smoke tests:
make smoke
-
Full check (unit + smoke):
make test
-
Clean up unit test artifacts:
make testclean
Per‑suite runners live under tests/sipnet/*
:
make -C tests/sipnet/test_events_infrastructure run
Releases¶
- Use Semantic Versioning v2 for SIPNET releases.
- Tag the git commit associated with the release
vX.Y.Z
. - Update versions in:
CITATION.cff
src/sipnet/version.h
docs/CHANGELOG.md
docs/Doxyfile
(PROJECT_NUMBER
)- Run tests (
make test
). - Publish the GitHub release; include
docs/CHANGELOG.md
content in release notes.