Skip to content

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:

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

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

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