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.

New contributors are encouraged to start with good first issues.

For a short quickstart and how to get the site and examples running, see the user guide: Getting Started

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.

This repository has a PR template; when opening a PR, make sure to fill out the template as indicated.

Prior to merging a PR, it must: - Pass all unit and integration tests - Be approved by at least one CODEOWNER - Include updates and additions to: - Tests (if code changes) - Documentation (if applicable) - docs/CHANGELOG.md for noteworthy changes - 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

All required checks must pass before merging, including the code format and style checks described below.

Propose and Receive Feedback¶

Before opening a pull request (PR), express your interest and get feedback by:

Asking to be assigned to an existing issue (comment on the issue and request assignment).
If the idea has not been proposed, or you want additional feedback, discuss it in the #pecan Slack channel.
Optional: if the task is complex and no issue exists, open a new issue summarizing the discussion, including motivation and a proposed solution.
Begin implementation once you have a thumbs-up (review/assignment) from a core maintainer (for example, @Alomir or @dlebauer).

This helps avoid duplicate work and ensures contributors receive early feedback on scope and design.

PR expectations¶

kindly refer to this PULL_REQUEST_TEMPLATE.md for PR template

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.

Using anchors for stable cross-references¶

When creating or updating documentation links, prefer explicit heading anchors so references remain stable when headings change slightly. We use the attr_list MkDocs extension to allow adding anchors directly to headings. To add an anchor, append {#id} to the heading, for example:

## Notation {#sec-notation}

Then link to that section from other pages using the file path plus #id, for example:

[Notation](parameters.md#sec-notation)

This makes cross-references robust to small edits in heading text and reduces broken links during refactors. Ensure attr_list is enabled in mkdocs.yml (it is enabled in this repo).

Compiling Documentation¶

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.
Update versions in:
CITATION.cff
src/sipnet/version.h
docs/CHANGELOG.md
docs/Doxyfile (PROJECT_NUMBER)
Run tests (make test).
Tag the git commit associated with the release vX.Y.Z and push tag to master.
```
git tag v<X.Y.Z>
```
Push tag to master branch, this will trigger a draft release
```
git push origin v0.0.0-test
```
Open draft on https://github.com/pecanProject/sipnet/releases.
Add content from docs/CHANGELOG.md to release notes.
Publish the GitHub release; this will trigger archiving on Zenodo
Get doi for this release from Zenodo and add to release notes. (note: README has a doi that represents all versions, and resolves to latest)