From ece869162f9b03c3e9c86f3d94f6cb592218a2a7 Mon Sep 17 00:00:00 2001 From: Ali Zein Yousuf Date: Fri, 19 Jun 2026 20:21:58 -0500 Subject: [PATCH] docs: add CLAUDE.md project guidance Co-Authored-By: Claude Opus 4.8 (1M context) Claude-Session: https://claude.ai/code/session_018MsAYv5RhNLE54fPrviVgS --- CLAUDE.md | 75 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 75 insertions(+) create mode 100644 CLAUDE.md diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..81debd4 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,75 @@ +# CLAUDE.md + +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. + +## What this is + +A personal **Gentoo ebuild repository (overlay)**, repo name `azy5030`, EAPI 8, +`masters = gentoo`, thin + unsigned Manifests (`metadata/layout.conf`). It packages +software not in the main `::gentoo` tree. Currently one package: +`dev-util/gitea-runner`. Hosted on a self-hosted Gitea at `git.azy.dev` whose repos +use SHA-256 object format. + +## The vendored-build model (the core design) + +`dev-util/gitea-runner` is a `go-module` ebuild built **offline** from upstream +`gitea/runner` source. Gentoo's build sandbox has no network, so Go modules cannot be +fetched at build time. Instead they are vendored ahead of time: + +1. The upstream source archive is `SRC_URI`'d from gitea.com's `/api/v1/.../archive` + endpoint (a plain `git clone`/`go get` is never used). +2. A **vendor tarball** (`${P}-vendor.tar.xz`, the result of `go mod vendor`, packed + deterministically) is uploaded as a **release asset on this repo** and is the second + `SRC_URI`. `S="${WORKDIR}/runner"`. +3. `dev-util/gitea-runner/Manifest` pins BLAKE2B/SHA512 of both tarballs. `emerge` + verifies against the Manifest, then compiles offline from `vendor/`. + +Consequences when editing the ebuild: +- `LICENSE` must cover **every vendored module's** license, not just upstream's MIT. + The bump PR checklist suggests `go-licenses report ./...` to confirm. +- `BDEPEND` Go version tracks upstream's `go.mod` `go` directive. +- The version string is injected via ldflags into + `gitea.com/gitea/runner/internal/pkg/ver.version`; CI asserts `gitea-runner --version` + echoes `v${PV}`. If upstream moves that symbol path, the build "succeeds" but reports + the wrong version. + +## Bumping to a new upstream version + +This is **automated** by `scripts/bump-version.sh` (run daily by `bump.yaml`, or +`workflow_dispatch`). To do it manually you must reproduce its steps, because a version +bump is never just renaming the ebuild — the vendor tarball must be regenerated and +re-uploaded as a release asset, or the build will fail Manifest verification. The script: + +1. Reads the latest `vX.Y.Z` from upstream `releases.rss`; compares to the newest + committed ebuild. Exits early if up to date or if a `bump/gitea-runner-` branch + already exists. +2. Downloads the source archive, runs `go mod vendor`, packs a reproducible + `*-vendor.tar.xz` (`--sort=name --mtime='UTC 1970-01-01' --owner=0 --group=0`). +3. Creates/reuses a release tagged `${PN}-${ver}-vendor` and uploads the tarball asset. +4. `git mv`s the ebuild to the new version, rewrites `BDEPEND`'s Go version from + upstream `go.mod`, and regenerates the Manifest with `pkgdev manifest` (after copying + both distfiles into `/var/cache/distfiles` and wiring a temporary `repos.conf`). +5. Validates: `pkgcheck scan`, then `emerge` + `gitea-runner --version | grep v${ver}`. +6. Commits, pushes the branch, opens a PR against `master`. + +Requires a `BUMP_TOKEN` repo secret (scopes: repository read/write, write release) plus +a Gentoo env with `go pkgdev git curl xz jq`. + +## CI (`.gitea/workflows/ci.yaml`) + +Runs on every push inside a `gentoo/stage3:amd64-openrc` container (the `runs-on` label +only schedules onto the Docker-backend runner). Steps: `emerge-webrsync` to sync +`::gentoo` → configure portage (disables binpkg signature verification so prebuilt deps +like `dev-lang/go` are pulled, not compiled) → **check out via `curl + tar`, not +`actions/checkout`** (it breaks on SHA-256 Gitea repos) into `/var/db/repos/azy5030` → +`pkgcheck scan` → `emerge` → assert `gitea-runner --version` matches the ebuild version. + +## Conventions / gotchas + +- **YAML** is linted by `.yamllint.yaml` (relaxed: line-length and document-start + disabled; `truthy.check-keys: false` so `on:` is allowed unquoted). +- `metadata/md5-cache/` is **gitignored** — portage regenerates it on sync, so never + commit it (a stale `gitea-runner-1.0.4` file may linger on disk untracked). +- The bump script and CI deliberately preserve the scheme of `GITHUB_SERVER_URL`: on the + self-hosted runner it is an internal `http://` endpoint. Don't hardcode `https`. +- New packages must be added to `profiles/categories` (currently just `dev-util`).