Development Workflow

June 23, 2026 · View on GitHub

This guide covers the day-to-day development workflow: branching, validation, committing, and submitting pull requests.

Branch Naming

Create a branch with a descriptive name using these prefixes:

PrefixPurposeExample
feat/New featuresfeat/add-sarif-output
fix/Bug fixesfix/pattern-handler-escaping
docs/Documentation updatesdocs/getting-started-guide
refactor/Code refactoringrefactor/simplify-sieve-pipeline
test/Test additions/fixestest/cel-expression-coverage
git checkout -b feat/my-feature

Pre-Commit Validation Checklist

Run all of these before every commit. They match the checks that CI will run on your pull request.

1. Lint

uv run ruff check .

To auto-fix issues:

uv run ruff check --fix .

To format code:

uv run ruff format .

2. Run tests

uv run pytest tests/ --ignore=tests/integration/ -q

To run only framework tests:

uv run pytest tests/darnit/ -v

To run only implementation tests:

uv run pytest tests/darnit_baseline/ -v

3. Validate spec sync

uv run python scripts/validate_sync.py --verbose

This checks that the framework-design spec matches the implementation. If you've changed framework behavior, update the spec first.

4. Rebase from upstream

git fetch upstream
git rebase upstream/main

Always rebase before pushing to keep history clean.

Commit Messages

Write clear, concise commit messages:

type: short description

Longer description if needed explaining the what and why.

Types: feat, fix, docs, test, refactor, ci, chore

Examples:

feat: Add SARIF output formatter for audit results

fix: Correct CEL expression escaping in TOML literal strings

docs: Add getting started guide for contributors

Pull Request Process

  1. Push your branch to your fork:

    git push origin feat/my-feature

  2. Open a Pull Request against the main branch on the upstream repository.

  3. Fill out the PR template with:

    • What changed and why
    • How to test the changes
    • Any breaking changes

  4. Wait for CI checks to pass and address review feedback.

Spec Change Workflow

If you're modifying framework behavior (sieve pipeline, plugin protocol, configuration), follow this order:

  1. Update the spec first: Edit docs/architecture/framework-design.md
  2. Validate sync: uv run python scripts/validate_sync.py --verbose
  3. Implement the change: Modify the code to match the spec
  4. Commit spec and code together

Code Style

  • Follow existing code patterns and conventions
  • Write clear, self-documenting code
  • Add comments only where necessary to explain complex logic
  • All public APIs should have type annotations

Next Steps