> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sightmap.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Contributing to Sightmap: DCO Sign-Off, SEPs, and the Monorepo

> Choose the right contribution path, follow the SEP process for spec changes, and sign off every commit.

Sightmap accepts contributions to the spec, reference implementation, documentation, and website. This page summarizes the process; the files in the [`sightmap/sightmap`](https://github.com/sightmap/sightmap) repository define the policy.

## The monorepo

Everything lives in one repository:

```text github.com/sightmap/sightmap theme={null}
sightmap/
├── spec/    the canonical spec: schema.md, sightmap.schema.json, SEPs, conformance fixtures
├── go/      the reference implementation: the sightmap CLI and Go library
├── docs/    this documentation site
└── web/     the sightmap.org marketing site
```

For the YAML format and its semantics, `spec/v1/` is authoritative.

## Where to discuss

| Topic                  | Where                                                                                                                                                                                                    |
| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Question               | [GitHub Discussions](https://github.com/sightmap/sightmap/discussions)                                                                                                                                   |
| Bug report             | Open the [Bug report form](https://github.com/sightmap/sightmap/issues/new?template=bug_report.yml)                                                                                                      |
| Small docs/website fix | Open a PR directly                                                                                                                                                                                       |
| Spec change            | Start a [Discussion](https://github.com/sightmap/sightmap/discussions) or [spec proposal issue](https://github.com/sightmap/sightmap/issues/new?template=spec_proposal.yml), then follow the SEP process |
| Code of Conduct report | Email **[subtext@fullstory.com](mailto:subtext@fullstory.com)**                                                                                                                                          |
| Security report        | Email **[subtext@fullstory.com](mailto:subtext@fullstory.com)**; do **not** open a public issue                                                                                                          |

## Spec changes go through SEPs

Changes such as adding or renaming a field, changing route or merge semantics, or introducing a top-level concept require a Sightmap Enhancement Proposal. The SEP records the design and gives implementations a shared basis for review. [`spec/seps/README.md`](https://github.com/sightmap/sightmap/blob/main/spec/seps/README.md) defines the scope, numbering, lifecycle, and review windows.

AI-assisted contributions (including SEP drafts) are accepted as long as you've read the output yourself and can defend it under review.

## Pull request expectations

* **One concern per PR.** If you fix two unrelated bugs, that's two PRs.
* **Explain why the change is needed.** The diff already shows what changed.
* **Update related files in the same PR.** If you change a schema field, update `spec/v1/schema.md`, `spec/v1/sightmap.schema.json`, and any affected examples.
* **Don't reformat unrelated code.** Keep diffs focused.
* **Expect review.** Maintainers aim to provide a first response within three business days.

## Developer Certificate of Origin

Sightmap does not require a CLA. Every commit needs a [Developer Certificate of Origin](https://developercertificate.org/) sign-off confirming that you wrote the contribution or have the right to submit it under the project's license.

Sign off every commit with `-s`:

```bash theme={null}
git commit -s -m "Your commit message"
```

This appends a `Signed-off-by: Your Name <your@email>` trailer to the commit. The name and email must match `git config user.name` and `git config user.email`. The DCO check examines every commit on the branch.

To sign off the latest commit, amend it:

```bash theme={null}
git commit --amend --signoff
```

To add the sign-off to a range of commits, rebase against `main`. This rewrites history, so force-push with a lease if the branch is already remote:

```bash theme={null}
git rebase --signoff main
git push --force-with-lease
```

## Branch and commit conventions

* Branch names: `feat/<topic>`, `fix/<topic>`, `docs/<topic>`, `spec/<topic>`, or `sep/<number>-<slug>` for SEP drafts.
* Commit messages: short imperative subject, optional body explaining *why*. Conventional Commits welcome but not required.
* Every commit ends with `Signed-off-by: …`.

## License

By contributing, you agree that your contributions will be licensed under the project's [MIT License](https://github.com/sightmap/sightmap/blob/main/LICENSE).

## Canonical documents

* [`CONTRIBUTING.md`](https://github.com/sightmap/sightmap/blob/main/CONTRIBUTING.md): contributor guide
* [`SECURITY.md`](https://github.com/sightmap/sightmap/blob/main/SECURITY.md): security policy and reporting process
* [`MAINTAINERS.md`](https://github.com/sightmap/sightmap/blob/main/MAINTAINERS.md): current maintainers and contact paths
* [`CODE_OF_CONDUCT.md`](https://github.com/sightmap/.github/blob/main/CODE_OF_CONDUCT.md): organization-wide community standards
* [`GOVERNANCE.md`](https://github.com/sightmap/.github/blob/main/GOVERNANCE.md): organization-wide decision process
* [`spec/seps/README.md`](https://github.com/sightmap/sightmap/blob/main/spec/seps/README.md): SEP process