---
title: Contributing
---
# 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](https://github.com/smg-project/smg). This documentation lives in a separate repository, [smg-project/smg-docs](https://github.com/smg-project/smg-docs), and is published at [lightseek.org/smg](https://lightseek.org/smg). The smg repository's `CONTRIBUTING.md` is the front door; these pages hold the details.
---
## Ways to Contribute
- :material-bug:{ .lg .middle } **Report Bugs**
---
Found a bug? The bug report form asks for reproduction steps, expected and actual behavior, the component, routing policy, and connection mode, your configuration, and logs.
[:octicons-arrow-right-24: Report a bug](https://github.com/smg-project/smg/issues)
- :material-lightbulb:{ .lg .middle } **Suggest Features**
---
Describe the problem you're solving and your proposed solution. Latency, throughput, and memory problems have their own performance issue form.
[:octicons-arrow-right-24: Request a feature](https://github.com/smg-project/smg/issues)
- :material-code-tags:{ .lg .middle } **Contribute Code**
---
Set up the toolchain, build and test the workspace, and open a pull request.
[:octicons-arrow-right-24: Development guide](development.md)
- :material-file-document:{ .lg .middle } **Improve Docs**
---
Fix typos, clarify explanations, or document a missing feature. Every page links to its source file in smg-docs.
[:octicons-arrow-right-24: Edit on GitHub](https://github.com/smg-project/smg-docs/tree/main/src/lib/content)
---
## Quick Start
### 1. Fork and Clone
```bash
# Fork smg-project/smg on GitHub, then:
git clone https://github.com/YOUR_USERNAME/smg.git
cd smg
```
### 2. Install the Toolchain
```bash
# Install rustup; rust-toolchain.toml pins Rust 1.98.0 (the version CI uses),
# which rustup installs on your first cargo command in the checkout
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
# Nightly, used only for rustfmt
rustup toolchain install nightly --profile minimal --component rustfmt
# Git hooks: formatting, lint, DCO sign-off, commit-message, and branch-name
# checks; one install covers the pre-commit, commit-msg, and pre-push hooks
pip install pre-commit
pre-commit install
```
You also need `protoc` and a C toolchain with OpenSSL headers; see [Prerequisites](development.md#prerequisites).
### 3. Branch, Build, and Test
```bash
# Branch names must be / or /
git checkout -b feat/my-change
# The first cargo command installs the pinned Rust 1.98.0 toolchain
cargo build
cargo test
```
### 4. Commit and Open a Pull Request
```bash
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, which GitHub pre-fills from the repository's `.github/PULL_REQUEST_TEMPLATE.md`.
---
## 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.
| # | Command | Expectation |
|---|---------|-------------|
| 1 | `cargo +nightly fmt --all` | No output (silent success) |
| 2 | `cargo clippy --all-targets --all-features -- -D warnings` | Zero warnings, zero errors |
| 3 | `cargo test` | `test result: ok` with 0 failures |
| 4 | `make python-dev` (only if `config/types.rs`, `protocols/`, or `bindings/` changed) | Builds successfully |
| 5 | Commit format | Conventional commit, DCO sign-off present, no AI attribution |
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](development.md#linting-and-formatting) for a lint that skips it.
---
## Commits
SMG uses [Conventional Commits](https://www.conventionalcommits.org/):
```text
():
Signed-off-by: Your Name
```
- **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](https://developercertificate.org/): 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:
```text
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 `/` (for example `feat/add-auth` or `fix/null-pointer`) or `/` (for example `changsu/fix-routing`), in lowercase letters, digits, `.`, `_`, and `-`. More `/`-separated segments may follow the first (`fix/pd/rooms` is also valid), and a `dependabot/` branch keeps the tool's own case after that prefix. The rule lives in one script, `scripts/branch-name-check.sh`, which both the PR check and the pre-push hook run: 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` pre-push hook — installed by `pre-commit install` above — checks the name before each 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 (listed in `.github/CODEOWNERS`)
- 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` at the repository root. Prefix every inline comment with a severity marker:
| Marker | Severity | Meaning |
|--------|----------|---------|
| 🔴 | **Important** | A bug that should be fixed before merging |
| 🟡 | **Nit** | A minor issue, worth fixing but not blocking |
| 🟣 | **Pre-existing** | A bug in the codebase that this PR did not introduce |
- 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 (`main.rs`), `config/types.rs`, the two conversion paths in `cli/configure.rs`, the Python bindings, and the Go SDK. Two bot reviewers, Claude and Codex, also review every pull request — drafts included — that a user with write access opens from a branch of smg-project/smg; a PR from a fork gets neither. Both post inline comments with the same severity markers, request changes when they find something 🔴 Important, grade each other's findings in-thread, and run a fresh full review on `@claude review` or `@codex review` in a PR comment.
---
## Governance
SMG's `GOVERNANCE.md` follows the spirit of the Linux Foundation's [Minimum Viable Governance](https://github.com/github/MVG) framework.
| Role | Who | Responsibilities |
|------|-----|------------------|
| **Contributors** | Anyone who files issues, joins discussions, or opens pull requests | No special status required |
| **Code owners** | Contributors with sustained, high-quality work in an area, listed in `.github/CODEOWNERS` | Review and approve changes in their areas |
| **Core maintainers** | Listed in GOVERNANCE.md; the default (`*`) owners in CODEOWNERS | Direction, architecture, releases, and the health of the project |
- 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 `docs/` folder holds internal CI notes only. The documentation lives in [smg-project/smg-docs](https://github.com/smg-project/smg-docs). The docs repository follows the same conventions as smg (`/` or `/` branch names, Conventional Commits PR titles, DCO sign-off, no AI attribution) and runs the same PR checks. See [Documentation](development.md#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 `.github/CODEOWNERS`, or reach out in the `#security` channel of the [Lightseek Slack](https://slack.lightseek.org).
---
## Getting Help
- **Questions**: [GitHub Discussions](https://github.com/smg-project/smg/discussions)
- **Bugs**: [GitHub Issues](https://github.com/smg-project/smg/issues)
- **Chat**: [Slack](https://slack.lightseek.org) (`#sig-smg` for discussing, reviewing, and merging PRs) or [Discord](https://discord.lightseek.org)
---
## Code of Conduct
We are committed to providing a welcoming and inclusive environment. The repository's Code of Conduct (`CODE_OF_CONDUCT.md`) 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](https://www.apache.org/licenses/LICENSE-2.0) (the repository's `LICENSE` file).