mirror of https://github.com/vernonkeenan/lib
73 lines
3.8 KiB
Markdown
73 lines
3.8 KiB
Markdown
# lib
|
|
|
|
vernonkeenan Shared Libraries (go)
|
|
|
|
## Dependent Systems
|
|
|
|
The Gitea server <https://code.tnxs.net> must be up and running with admin access. It hosts world-readable
|
|
pull-mirrors of this repo at `vernonkeenan/lib` and `work/lib`.
|
|
|
|
## Release Procedure
|
|
|
|
As of 2026-07-12 (ADR-KV-014, DT-KV-004) this repo is `main` + `v*` tags — branch-per-version is retired, and
|
|
so is the old three-web-UI-plus-CLI manual ritual. Releasing is one command: `make release VERSION=vX.Y.Z`.
|
|
|
|
### Prerequisites
|
|
|
|
* All the sibling service repos (`auth`, `crm`, `stash`, `sf-gate`, `research`, `members`, `plex`) are cloned
|
|
locally in adjacent directories — `regen` reads each one's `swagger/<service>-vernonkeenan.yaml`.
|
|
* [`gh`](https://cli.github.com/) installed and authenticated (`gh auth login`) with push access to
|
|
`vernonkeenan/lib` — the release step calls `gh release create`.
|
|
* `GITEA_TOKEN` exported, set to a Gitea API token (Settings -> Applications on <https://code.tnxs.net>) with
|
|
rights to trigger a mirror-sync on `vernonkeenan/lib` and `work/lib`. If unset, `make release` still tags,
|
|
pushes, and publishes the GitHub release — it just skips the Gitea mirror-sync step with a loud warning, so
|
|
the mirrors will lag until someone clicks Synchronize Now manually or reruns with the token set. (There is
|
|
no existing Gitea/tnxs token variable defined anywhere in this workstation's env files today — `GITEA_TOKEN`
|
|
is a new name, not a rename of something already in use.)
|
|
|
|
### 1. Regenerate the API clients (its own PR)
|
|
|
|
```bash
|
|
make regen
|
|
```
|
|
|
|
This installs the pinned go-swagger CLI (`SWAGGER_VERSION` in the `Makefile`, currently `v0.35.0` — bump
|
|
deliberately and update both places when you do), copies each sibling repo's `swagger/<service>-vernonkeenan.yaml`
|
|
into `./swagger` and `./swagger/external`, regenerates every client under `api/`, and rewrites the external
|
|
specs' scheme/host/path exactly as the old `make swagger` ritual did. It fails fast, before touching anything,
|
|
if any sibling spec is missing.
|
|
|
|
Review `git status`/`git diff`, commit, open a PR, and merge it to `main` like any other change — client regen
|
|
is not bundled into the release step itself. `make regen` runs a non-fatal `go build ./...` at the end as an
|
|
early warning; the real gate is CI on that PR.
|
|
|
|
**Known gap:** if any sibling spec has an operation with no top-level `tags:`, go-swagger routes it into a
|
|
fallback `operations` package whose import path in `<name>_client/<name>_client.go` doesn't respect
|
|
`--client-package` — reproduced across go-swagger v0.33.2 through v0.35.0 while building this tooling. As of
|
|
this writing that's `sf-gate-vernonkeenan.yaml`'s `PUT /researchprojectservices` (no `tags:`). Fix it at the
|
|
source (add a `tags:` entry in the `sf-gate` repo's spec) rather than hand-patching generated code, since the
|
|
next regen would just reintroduce it.
|
|
|
|
### 2. Cut the release (from a clean `main` checkout)
|
|
|
|
```bash
|
|
make release VERSION=v0.7.5
|
|
```
|
|
|
|
`scripts/release.sh` (invoked by the `release` target):
|
|
|
|
1. Validates `VERSION` is `vMAJOR.MINOR.PATCH` and strictly greater than the latest existing tag.
|
|
2. Requires you're on `main`, the tree is clean, and local `main` matches `origin/main` (no local-only commits).
|
|
3. Runs `go build ./...` and `go vet ./...` as a last sanity check.
|
|
4. Creates an annotated tag at HEAD, pushes it, and runs `gh release create` with generated notes.
|
|
5. POSTs to the Gitea mirror-sync API for `vernonkeenan/lib` and `work/lib` (skipped with a warning if
|
|
`GITEA_TOKEN` is unset).
|
|
|
|
Use `make release-dry-run VERSION=v0.7.5` to run steps 1-3 and print what steps 4-5 would do, without tagging,
|
|
pushing, publishing, or syncing anything.
|
|
|
|
### 3. Downstream consumers
|
|
|
|
Update the `go.mod` line for `code.tnxs.net/vernonkeenan/lib` in each dependent project to the new tag, same
|
|
as before — that part of the old ritual is unchanged.
|