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:
```
# format only what you just staged
git clang-format
# restage fixes and commit again
git add -u
git commit
```
If git clang-format fails because not all changes are staged (likely a git commit -a command), either git add all the changes, or try git 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

To reformat all modified files: 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:

pip install mkdocs mkdocs-material pymdown-extensions
mkdocs serve
# open http://127.0.0.1:8000/

Update mkdocs.yml if you add/move pages.

Build API docs (Doxygen) and site (MkDocs):
```
make document
```
Outputs: docs/api/ and site/.

Live preview while editing docs:

pip install mkdocs mkdocs-material pymdown-extensions
mkdocs serve
# open http://127.0.0.1:8000/

Update 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.