Contributing Guide

Thank you for your interest in contributing to FIXS! Follow this guide to ensure your contributions are properly tracked and merged.

Branch Strategy

  • main — stable release branch; never commit directly

  • dev — integration branch; all PRs target here

  • Feature/fix branches — branch off dev, named <type>/<issue_number>_<short_desc>

main  ←── (release PR) ←── dev  ←── maintenance/128_unify_fixs_branding
                                ←── bug/84_python_xil_client
                                ←── feature/70_libsumo_direct_launch

Branch name types: feature/, bug/, maintenance/, docs/

Step 1: Fork and Clone

git clone https://github.com/<your-username>/FIXS.git
cd FIXS

Then initialize the checkout. This replaces the manual git submodule update --init step and also acquires the native dependencies, which are not in git:

powershell -ExecutionPolicy Bypass -File scripts\initialize_fixs.ps1

ProprietaryFiles is a private submodule — external contributors have no access, and that is expected. The script reports it as skipped and the public core still builds. See BUILD.md — First-Run Setup.

Step 2: Create a Branch off dev

git fetch origin
git checkout -b maintenance/NNN_short_desc origin/dev

Always include the GitHub issue number in the branch name.

Step 3: Make Changes and Test

  • Run Python unit tests (no simulator required):

    python -m pytest tests/Python/unit/ -v
python -m pytest tests/Python/test_repo_hygiene.py tests/Python/test_naming_consistency.py tests/Python/test_build_system.py -v

  • Add a test case if your change is testable without simulators

Building the documentation locally

The published docs are built by ReadTheDocs on Linux (.readthedocs.yml). To preview them yourself:

python -m venv .docvenv
.docvenv/bin/pip install -r doc/requirements_doc.txt      # Scripts\pip on Windows
.docvenv/bin/python -m sphinx -b html doc doc/_build/html

On Windows this segfaults, usually part-way through writing output..., sometimes surfacing first as a nonsense TypeError from inside Sphinx or markdown-it. The cause is stack exhaustion: docutils recurses deeply per document and Windows gives the main thread far less stack than Linux does, so the whole doc set no longer fits. It is not a problem with any individual page, and it does not affect the ReadTheDocs build.

Build on a thread with a larger stack instead:

# build_docs.py
import sys, threading
from sphinx.cmd.build import main
threading.stack_size(64 * 1024 * 1024)
sys.setrecursionlimit(20000)
t = threading.Thread(target=lambda: sys.exit(main(["-b", "html", "doc", "doc/_build/html"])))
t.start(); t.join()

Step 4: Commit and Open a PR

PR title format: #<issue_number>/<short_description>

Example: #130/python commonlib package structure and unit tests

PR must target the dev branch, not main. Fill in all sections of the PR template.

ProprietaryFiles Submodule

ProprietaryFiles is a private submodule containing CarMaker/VISSIM/dSPACE integration code (proprietary commercial software APIs). It lives at ORNL-Real-Sim/ProprietaryFiles (private — accessible to ORNL team members only).

Why it’s structured this way: The public FIXS repo stores only a commit hash pointer to the private submodule. Public contributors cannot see the proprietary contents, but can still build and use the open-source parts of FIXS without them.

If you are an ORNL team member modifying ProprietaryFiles

Goal: every merged FIXS commit must point to a ProprietaryFiles/main commit, so anyone cloning FIXS gets a stable PF state. The two PRs are reviewed in parallel but merged back-to-back: PF first, then FIXS.

# Step 1: Create a matching branch in the private submodule
cd ProprietaryFiles
git checkout -b maintenance/NNN_short_desc
# ... make changes, commit ...
git push origin maintenance/NNN_short_desc

# Step 2: Stage the updated submodule pointer in FIXS (points at your PF branch tip)
cd ..
git add ProprietaryFiles
git commit -m "chore: bump ProprietaryFiles to maintenance/NNN"
git push origin maintenance/NNN_short_desc

# Step 3: Open BOTH PRs at the same time, cross-referencing each other:
#   - ProprietaryFiles PR  →  PF/main
#   - FIXS PR              →  dev

# Step 4: When both PRs are approved, merge PF first, then re-point FIXS to PF/main:
cd ProprietaryFiles && git fetch origin && git checkout main && git pull
cd ..
git add ProprietaryFiles
git commit -m "chore: bump ProprietaryFiles pointer to merged main"
git push
# Then merge the FIXS PR.

Rules:

  • Never push directly to ProprietaryFiles/main — branch-protected (requires PR + review)

  • The ProprietaryFiles branch name must mirror the FIXS issue branch name

  • Reference the companion PR in each PR’s description so reviewers can find it

  • Step 4 re-point is mandatory: do not merge a FIXS PR while its submodule pointer is at a PF feature-branch tip

  • If the FIXS PR is rejected after the PF PR is merged, open a revert PR in PF — don’t leave orphan code on PF/main

If you are an external contributor

You do not need access to ProprietaryFiles to contribute to the open-source parts of FIXS (SUMO integration, Python helpers, build system, tests, documentation). Simply ignore the ProprietaryFiles/ directory — it will show as an inaccessible submodule on your clone.

PR Checklist

  • [ ] Branch is based on dev (not main)

  • [ ] PR title follows #NNN/short_description format

  • [ ] All template sections filled in

  • [ ] Python unit tests pass locally

  • [ ] If ProprietaryFiles was modified: companion PR opened, PF merged first, submodule pointer re-pointed to PF/main HEAD before merging FIXS

  • [ ] Relevant GitHub issue is linked in PR body