diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 00000000..26c1f05e --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,37 @@ +# AGENTS.md + +This is the C4DT fork of [`toolshed/abra`](https://git.coopcloud.tech/toolshed/abra), the Co-op Cloud command-line tool. What differs from upstream is described in [README_C4DT.md](README_C4DT.md); keep that file up to date when adding a change. + +## Branches + +| Branch | Content | +| --- | --- | +| `main` | Mirror of upstream `toolshed/abra` `main`. No C4DT commits. | +| `c4dt` | The fork's release line: upstream plus all C4DT changes. Release tags are made here. | +| feature branches, e.g. `audit_v1` | Work in progress, merged into `c4dt` when ready. | + +- Start new work from `c4dt`, in a feature branch. +- To follow upstream, update `main` from `toolshed/abra`, then merge or rebase `c4dt` onto it. Update the base commit and date in `README.md` and `README_C4DT.md`. +- Changes taken from other forks are cherry-picked with `git cherry-pick -x`, so the original commit stays recorded. + +## Tags + +Releases are annotated tags on `c4dt`, named `-c4dt.`, e.g. `0.13.0-beta-c4dt.1`: + +- `` is the latest upstream tag the fork is based on. +- `` counts the C4DT releases on that base, starting at 1, and restarts at 1 when the upstream version changes. +- Tags are never moved or deleted: users pin them, so a tag must always build the same code. + +Build a release with the tag as version, so `abra --version` prints `-`: + +```bash +go build -ldflags "-X main.Version= -X main.Commit=$(git rev-parse HEAD)" -o abra ./cmd/abra +``` + +## Development + +- Toolchain: `devbox.json`. Use `devbox run build` and `devbox run test`; the test script sets a temporary `ABRA_DIR`, which the tests require. +- Dependencies are vendored: after changing `go.mod`, run `go mod vendor`. +- `abra audit` is designed in [`doc/DesignAudit.md`](doc/DesignAudit.md), which also lists what later versions will add. Keep the design and the code in sync. +- Advisories for `abra audit` live in a separate repository, [`c4dt/advisories`](https://git.coopcloud.tech/c4dt/advisories), under `advisories/`. +- User-facing strings are wrapped in `i18n.G`. diff --git a/README_C4DT.md b/README_C4DT.md index f23b6c9c..da769869 100644 --- a/README_C4DT.md +++ b/README_C4DT.md @@ -4,6 +4,8 @@ This fork of [`toolshed/abra`](https://git.coopcloud.tech/toolshed/abra) is main It is based on upstream `main` at commit `9023bb87` of 2026-11-18, which is 163 commits after the `0.13.0-beta` tag. +Releases are tags on the `c4dt` branch, named `-c4dt.`, e.g. `0.13.0-beta-c4dt.1`. Pin a tag rather than following a branch. See [AGENTS.md](AGENTS.md) for the branch and tag conventions. + ## Overview | Change | Summary |