eSliderandCursor
2d7b97f5ae
README CLI: comment-first bash examples, convert/merge/get order, real-world flows. Move architecture decisions pointers into CONTRIBUTING; trim AGENTS and README. Co-authored-by: Cursor <cursoragent@cursor.com>
69 lines
2.9 KiB
Markdown
69 lines
2.9 KiB
Markdown
# 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
|
||
|
||
Significant design choices for this repository are captured as **Architecture Significant
|
||
Requirements** (ASRs):
|
||
|
||
- **Repo-local ASRs:** [docs/asr/README.md](docs/asr/README.md)
|
||
- **eSlider Go library conventions (inventar):** `inventar/docs/asr/ASR-0008.md` — also linked
|
||
from [AGENTS.md](AGENTS.md) under Related.
|