Contributing to SMG¶

Thank you for your interest in contributing to Shepherd Model Gateway (SMG). The gateway's source code lives in smg-project/smg. This documentation lives in a separate repository, smg-project/smg-docs, and is published at lightseek.org/smg. The smg repository's CONTRIBUTING.md is the front door; these pages hold the details.

Ways to Contribute¶

Quick Start¶

1. Fork and Clone¶

# Fork smg-project/smg on GitHub, then:
git clone https://github.com/YOUR_USERNAME/smg.git
cd smg

2. Install the Toolchain¶

# Rust 1.98.0 (the version CI uses) for this checkout, plus nightly rustfmt
rustup toolchain install 1.98.0
rustup override set 1.98.0
rustup toolchain install nightly --profile minimal --component rustfmt

# Git hooks: formatting, lint, DCO sign-off, and commit-message checks
pip install pre-commit
pre-commit install
pre-commit install --hook-type commit-msg

You also need protoc and a C toolchain with OpenSSL headers; see Prerequisites.

3. Branch, Build, and Test¶

# Branch names must be <type>/<description> or <username>/<description>
git checkout -b feat/my-change

cargo build --locked
cargo test --locked

4. Commit and Open a Pull Request¶

git commit -s -m "feat(policies): describe the change"
git push origin feat/my-change

Open the pull request against main and fill in the PR template.

The Pre-PR Gate¶

Every PR must pass these checks locally before you request review. "Probably passes" is not passing: paste the output or re-run.

Check 2 uses --all-features, which turns on the opencv-video feature and needs system OpenCV. Install it once with make opencv-deps, or see Linting and Formatting for a lint that skips it.

Commits¶

SMG uses Conventional Commits:

<type>(<scope>): <short summary>

<optional body explaining why>

Signed-off-by: Your Name <your.email@example.com>

• Types: feat, fix, docs, style, refactor, perf, test, chore, ci
• Scope: the crate or subsystem, such as mesh, grpc_client, worker, or protocols
• One logical change per commit. Prefer many small commits to one large one.
• Sign off every commit with git commit -s. The sign-off certifies the Developer Certificate of Origin: you wrote the code or have the right to submit it.
• No AI attribution. Co-authored-by or Signed-off-by lines that name Claude or noreply@anthropic.com are rejected by the no-ai-co-author hook and by the PR check.

Examples from the smg history:

feat(routers): compile provider routers behind per-provider Cargo features
fix(protocols): preserve Responses tool namespaces and content-array outputs
ci: upgrade Rust toolchain to 1.98

Pull requests are squash-merged, and the PR title becomes the commit title on main, so the title must follow the same format. The PR Title & Commit Messages check accepts the types feat, fix, chore, docs, refactor, test, ci, perf, lint, style, revert, and build, an optional lowercase scope, and ! for a breaking change (feat(api)!: ...).

Branch Names¶

Name branches <type>/<description> (for example feat/add-auth or fix/null-pointer) or <username>/<description> (for example changsu/fix-routing), in lowercase. For branches pushed to smg-project/smg, the Branch Naming Convention check comments on and closes a PR whose branch does not match. Locally, the branch-name-check hook checks the name at push time (lowercase letters, digits, ., _, and -, with one /) once you install the pre-push hook (pre-commit install --hook-type pre-push).

Pull Requests¶

• Fill in the PR template: Problem and Solution, Changes, and especially the Test Plan. "Ran cargo test" is not a test plan; name the scenarios the reviewer can reproduce.
• Keep PRs small. Aim for 400 changed lines or fewer. Above that, split the PR or coordinate with reviewers in advance.
• One concern per PR. A refactor or a feature, not both.
• Link the issue with Closes #1234 or Refs: #1234.
• Answer review comments with a commit SHA and a one-line reason, for example Fixed in abc1234 — capped total_chunks at 1024 before allocation. Silence or "Fixed!" makes reviewers hunt for your change.
• Propose significant changes first. New architecture, breaking API changes, new workspace crates, and deprecations start as a GitHub issue or design discussion that the core maintainers decide on.
• Keep the PR active. A stale bot labels a non-draft PR stale after 14 days without activity and closes it 16 days later. Draft PRs are exempt.

Merge Requirements¶

main accepts squash merges only. A pull request can merge once it has:

• two approving reviews, including one from a code owner of the changed paths
• every review thread resolved
• passing required checks: finish (the summary job of the PR test workflow, which fails if any lint, test, or e2e job failed), DCO, and PR Title & Commit Messages

If the DCO check fails, Mergify comments with the fix (git rebase HEAD~N --signoff, then git push --force-with-lease). A PR with merge conflicts gets the needs-rebase label until you rebase it on origin/main.

Using Code Agents¶

Agents such as Claude Code, Cursor, and Copilot are welcome. Three ground rules:

1. You own the PR, not the agent. Read every line before you open it.
2. Show the gate output. Paste the real cargo fmt, clippy, and test output, not "I have run the tests."
3. No AI attribution in commits, PR bodies, or review replies. The hook rejects it, and so will the reviewer.

Reviewing¶

Reviews follow REVIEW.md. Prefix every inline comment with a severity marker:

• Cite file:line in every substantive comment, and finish with a short summary that counts findings per severity.
• Focus on logic errors, security problems, missing error handling (swallowed errors, silent fallbacks to defaults), incorrect defaults or config values, and broken cross-references. Skip formatting-only changes and dependency bumps with no code changes.
• Approve small, clean PRs fast. The faster the turnaround, the fewer giant PRs reviewers face later.

REVIEW.md also lists the subsystem pitfalls reviewers look for; config changes, for example, must reach the CLI arguments, config/types.rs, main.rs, the Python bindings, and the Go SDK. Automated reviewers comment on PRs as well: CodeRabbit, and, for branches pushed to smg-project/smg rather than forks, a Claude-based review that uses the same severity markers.

Governance¶

SMG's GOVERNANCE.md follows the spirit of the Linux Foundation's Minimum Viable Governance framework.

• Day-to-day technical decisions use lazy consensus on pull requests and issues.
• Significant changes (new architecture, breaking API changes, new workspace crates, release planning, deprecations) are proposed as a GitHub issue or design discussion and decided by consensus among the core maintainers.
• The usual path is contributor, then code owner, then core maintainer. Each addition needs the core maintainers' agreement and lands as a pull request that updates CODEOWNERS.

Documentation Changes¶

These docs are not in the smg repository: its old docs/ folder was removed when the documentation moved to smg-project/smg-docs (smg-project/smg#2012). The docs repository follows the same conventions as smg (<type>/<description> or <username>/<description> branch names, Conventional Commits PR titles, DCO sign-off, no AI attribution) and runs the same PR checks. See Documentation for the local preview workflow.

Reporting Security Issues¶

Do not open a public issue for a security vulnerability. Report it privately instead: contact a maintainer listed in CODEOWNERS, or reach out in the #security channel of the Lightseek Slack.

Getting Help¶

• Questions: GitHub Discussions
• Bugs: GitHub Issues
• Chat: Slack (#sig-smg for discussing, reviewing, and merging PRs) or Discord

Code of Conduct¶

We are committed to providing a welcoming and inclusive environment. The Code of Conduct applies to every interaction in the repository and in community spaces.

License¶

By contributing, you agree that your contributions will be licensed under the Apache License 2.0.