51 lines
1.6 KiB
Markdown
51 lines
1.6 KiB
Markdown
# Conventions
|
|
|
|
Repository rules that should stay true as the project changes.
|
|
|
|
## Layout
|
|
|
|
- Shippable binaries live under `cmd/<name>/`.
|
|
- The bootstrap installer lives under `setup/`; shared install logic lives in
|
|
`internal/installer/`.
|
|
- Shared Go code lives under `internal/`. Add no top-level `pkg/` until there is
|
|
an external consumer.
|
|
- `README.md` is a short description plus a docs index.
|
|
- `VERSION` is the release version source of truth.
|
|
|
|
## Go
|
|
|
|
- Module path: `gitea.alexandru.macocian.me/amacocian/sherlock`.
|
|
- Target Go version: the `go` directive in `go.mod`.
|
|
- One `package main` per `cmd/<binary>/`.
|
|
- Non-main packages have a package doc comment in their leading source file.
|
|
- New third-party dependencies need a short justification with the change.
|
|
|
|
## Docs
|
|
|
|
- Keep docs short and functional.
|
|
- Prefer links to source files over copied API/tool examples.
|
|
- Do not add layout diagrams. Use prose for relationships and source links for
|
|
details.
|
|
- One topic per `docs/*.md` file; link from `README.md`.
|
|
|
|
## Naming
|
|
|
|
- Binaries are kebab-case: `gitea-mcp`, `gssh-mcp`, `searxng-mcp`.
|
|
- Agent names match the wrapped CLI: `copilot`, `claude`.
|
|
- Service names are the config key and wallet key: `gitea`, `grafana`, `gssh`,
|
|
`searxng`.
|
|
|
|
## Commits and CI
|
|
|
|
- Commit style: `area: short imperative`.
|
|
- Keep one logical change per commit.
|
|
- `.gitea/workflows/release.yaml` runs formatting, static analysis, race tests,
|
|
and build.
|
|
- Tags are created from `VERSION` only after the main-branch release workflow
|
|
passes.
|
|
|
|
## Security
|
|
|
|
No secrets in the repository. OAuth tokens live in the OS keyring; config files
|
|
contain deployment metadata only.
|