docs: add CONTRIBUTING guide and expand README

Add CONTRIBUTING.md for testing, PR checks, and release-please flow; link from README and AGENTS. Document envc bash sourcing (set -a, source <(...)) for YAML/INI. Co-authored-by: Cursor <cursoragent@cursor.com>
2026-05-03 10:29:27 +01:00
parent 2d674de546
commit 36f0ed9b52
3 changed files with 161 additions and 47 deletions
@@ -0,0 +1,64 @@
+# Contributing to go-config
+
+Thank you for helping improve this module. This document covers **testing expectations**,
+**local checks**, and **how releases are cut** (so nobody tags or edits versions by hand).
+
+For repository purpose, public API notes, and agent-oriented context, see [AGENTS.md](AGENTS.md).
+
+## Testing policy
+
+This project follows the eSlider **no synthetic mocks** policy (see [.cursor/rules/no-synthetic-mocks.mdc](.cursor/rules/no-synthetic-mocks.mdc)):
+
+- **Unit tests** — pure inputs for merge, keymap, structconv, env flat-map helpers.
+- **`httptest`** — allowed only to test **our** HTTP client behaviour in `internal/source` (not third-party API emulation).
+- **Fixtures** — real files under `fixtures/`; `testfixtures` resolves paths from module root.
+
+## Before you open a pull request
+
+Run the same checks CI will run (adjust paths if your checkout layout differs):
+
+```sh
+go mod tidy
+go vet ./...
+go test -race -shuffle=on -count=1 ./...
+golangci-lint run --timeout 5m
+```
+
+## Commit messages
+
+Use [Conventional Commits](https://www.conventionalcommits.org/) (`feat:`, `fix:`, `perf:`,
+`feat!:` or `BREAKING CHANGE:` for breaking changes, etc.). Release automation reads these
+messages to choose the next SemVer.
+
+## Release and versioning
+
+Versions are **computed from git history**, not edited in Go source. Do **not** create
+release tags manually or bump version constants in code.
+
+### CI on every change
+
+1. Every push and pull request runs [`test.yml`](.github/workflows/test.yml) (matrix: Go
+   1.22, 1.23, stable × linux / macOS / windows, with `-race -shuffle=on`) and
+   [`lint.yml`](.github/workflows/lint.yml) (`go vet` + `golangci-lint`).
+
+### Release Please and GoReleaser
+
+2. On pushes to `main`, [`release-please.yml`](.github/workflows/release-please.yml) parses
+   commits since the last tag and opens (or updates) a **release pull request** that bumps
+   [`CHANGELOG.md`](CHANGELOG.md) and [`.release-please-manifest.json`](.release-please-manifest.json)
+   to the next SemVer.
+
+3. **Merging that release PR** creates the git tag `vX.Y.Z` and a GitHub Release.
+
+4. The tag triggers [`release.yml`](.github/workflows/release.yml), which runs
+   [GoReleaser](https://goreleaser.com) to cross-compile the `envc` binary (linux / darwin /
+   windows × amd64 / arm64), injects `-X main.version={{.Version}}` (and related ldflags) at
+   link time, and attaches archives plus `checksums.txt` to the release.
+
+Local `go install` builds of `envc` report `dev` for `envc version` unless you pass your own
+`-ldflags`; release binaries show the released version.
+
+## Architecture decisions
+
+Repo-local ASRs: [docs/asr/README.md](docs/asr/README.md). Broader eSlider Go module
+conventions: `inventar/docs/asr/ASR-0008.md` (see [AGENTS.md](AGENTS.md) — Related).