# Contributing to Sorcery-Go

> *"The Coven grows stronger with every mage who joins the circle."*

Thank you for your interest in improving Sorcery-Go. This document describes
how to contribute code, spells, documentation, and toolchains to the
Sovereign Coven.

**Sorcery-Go is developed by dcos.net. It is not affiliated with Source Mage
GNU/Linux or sourcemage.org.**

## Code Contributions

1. **Fork & branch** — create a feature branch off `master`:
   `git checkout -b feature/your-feature`

2. **Build & test** — every PR must pass `make build && make test`:
   ```bash
   make build
   go test ./pkg/...
   ```

3. **Style** — follow [Effective Go](https://go.dev/doc/effective_go) and
   `gofmt -s`. Run `go vet ./...` before pushing.

4. **Doc comments** — every exported type and function must have a Go doc
   comment that starts with the identifier name. See `pkg/dag/dag.go` for
   the house style.

5. **Tests** — every new package must include a `_test.go` file. The DAG,
   Warding, Legal, and Tomb packages already have tests you can use as
   templates.

6. **Commit messages** — follow the conventional-commits style:
   ```
   feat(cast): add --matrix flag for parallel arch builds
   fix(tomb): handle empty epitaph in VerifyRoot
   docs(security): add firewall rules reference for new deployments
   ```

## Spell Contributions (Grimoire)

New spells go under `grimoire/<section>/<spell>/` and must include:

- `DETAILS` — required metadata (see `docs/SPELL_SPEC.md`)
- `DEPENDS` — runtime/build/optional dependencies
- `BUILD` — compilation script (runs inside the OverlayFS sandbox)
- `CONFIGURE` — optional ICE y/n queries

Use `quill new <name>` to scaffold a new spell — it auto-hashes the source
tarball and emits the four files in the correct format.

## Toolchain Contributions

If you maintain a custom GCC/LLVM toolchain that should be admitted to the
Coven:

1. Add a `TOOLCHAIN.md` (see `docs/TOOLCHAIN_SPEC.md`) under
   `/opt/sorcery-go/toolchains/<triple>/`.
2. Run `pkg/toolchain.Validate(path)` — the report must show `Passed: true`.
3. Sign the toolchain directory with your PGP key.

## Documentation

The SGDS (Sorcery-Go Documentation Standard) lives in `docs/METADATA.md`.
Every new module or major feature must include a corresponding markdown
file. Keep the arcane vocabulary consistent — see `docs/RITUAL_OF_CASTING.md`
for the canonical names (Cauldron, Tomb, Warding, Sanctum, Coven, etc.).

## Legal

Sorcery-Go is developed by dcos.net and is not affiliated with Source Mage
GNU/Linux or sourcemage.org. By submitting a pull request you agree to license
your contribution under AGPL-3.0-or-later. The Legal Sentinel's
`strict_copyleft` posture is the default for the project itself — please do
not introduce proprietary code.

## Code of Conduct

Be excellent to each other. The Coven is a circle of mutual respect —
hostility will not be tolerated.