mr.zeroandClaude Opus 5
d1fdbfd92b
Publishing warp_engine hit it: a credentials key written as the host URL never matches --host, because RubyGems normalizes those keys. gem push then falls back to signing in against an endpoint Gitea does not have, and reports "404 page not found" — which points nowhere near the cause. Also notes that fixing a release pipeline means re-tagging: Woodpecker reads the config from the tagged commit, so a retry on the old tag would run the old, broken config. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
64 lines
5.5 KiB
Markdown
64 lines
5.5 KiB
Markdown
---
|
||
name: ttg-publish-module
|
||
description: Release a TTG library as a consumable package — a Go module tag or a RubyGems push to the forge registry. Checks the module path against the repo's org, tags the version, and verifies from a clean external project that the release is actually fetchable. Use when the user wants to publish, release, tag or version a library ("adjuk ki", "publikáld", "release", "tag a version").
|
||
allowed-tools: Bash, Read, Edit, Grep, Glob
|
||
---
|
||
|
||
# ttg-publish-module
|
||
|
||
Egy TTG könyvtár kiadása úgy, hogy utána **tényleg le lehessen hívni**. A skill nem ér véget a tagnél: külső projektből visszaellenőrzi.
|
||
|
||
## Amit tudni kell előre
|
||
|
||
- A forge `https://git.teletypegames.org`. A régi `git.teletype.hu` hosztot soha ne használd.
|
||
- A Gitea átirányítja a régi `owner/repo` utakat egy átnevezés vagy org-váltás után — **de ez nem terjed ki a Go modulnevekre és a csomag-névterekre.** Ez a leggyakoribb hiba: a repo elérhető, a `go get` mégis elszáll.
|
||
- A könyvtárak az `engines` orgban laknak. Az org-szabályok a workspace gyökér `REPO_REFACT.md`-jében vannak.
|
||
|
||
## Go modul
|
||
|
||
A Go-nál **nincs csomagtár**: a repo maga a terjesztés, a git tag a verzió.
|
||
|
||
1. **Modulnév ellenőrzése.** A `go.mod` első sora legyen `git.teletypegames.org/<org>/<repo>`, ahol az org és a repo a *mai* helye. Ha eltér, írd át, és vele együtt minden belső importot (`grep -rl '"<régi modulnév>' --include="*.go"`). Két valós eset volt: `module game` (semmilyen néven nem hivatkozható) és egy org-váltást nem követő útvonal.
|
||
2. **Fordul-e.** `go build ./...` és `go vet ./...`. Ha a repo ebiten-t használ, macOS-en cgo-figyelmeztetések jönnek az upstreamből — azok nem a mi hibánk, szűrd ki őket.
|
||
3. **Fogyasztók.** Keresd meg, ki hivatkozik rá (`grep -rn '<modulnév>' --include=go.mod` a workspace-ben). Ha van `replace ... => ../<repo>` direktíva, **az kiadás után elhagyható** — és el is kell hagyni, mert testvérkönyvtárat vár, ami CI-checkoutban nincs, tehát bukó pipeline-t okoz.
|
||
4. **Verzió.** Ha nincs korábbi tag, `v0.1.0` az őszinte kezdés. Egyébként semver a változás mértéke szerint. A tag legyen annotált: `git tag -a v0.1.0 -m "<repo> v0.1.0 — <mi ez>"`.
|
||
5. **Push.** `git push origin master && git push origin v0.1.0`.
|
||
6. **Ellenőrzés — ezt ne hagyd ki.** Üres könyvtárban:
|
||
```sh
|
||
go mod init tmp/probe
|
||
GOPRIVATE=git.teletypegames.org GOPROXY=direct GOSUMDB=off \
|
||
go get git.teletypegames.org/<org>/<repo>@v0.1.0
|
||
```
|
||
Ha ez lefut és a `go.mod`-ba bekerül a verzió, a kiadás valódi.
|
||
|
||
**`GOPRIVATE`.** A saját modulјaink nincsenek a proxy.golang.org-on és a publikus checksum adatbázisban, ezért minden fogyasztónak kell `GOPRIVATE=git.teletypegames.org`. Ha a fogyasztó egy TTG repo, tedd a Makefile-jába (`export GOPRIVATE = git.teletypegames.org`), ne csak a környezetbe — így CI-ben is működik.
|
||
|
||
## Ruby gem
|
||
|
||
1. **Hol fejlesztik.** Ha a gem egy monorepo alkönyvtárában él (a `warp_engine` a `services/teletypegames` `libs/ruby/warp_engine`-jében), a gemspecet **ott** módosítsd, ne a split mirrorban — a mirror csak publikálásra való, a CI felülírja.
|
||
2. **`allowed_push_host`.** Pontosan egyezzen a `gem push --host` értékével. A forge orgonként külön registryt szolgál ki:
|
||
`https://git.teletypegames.org/api/packages/<org>/rubygems`
|
||
Ha csak a hosztnév van benne, a push visszautasításra kerül.
|
||
3. **A credentials kulcs neve.** A RubyGems **normalizálja** a `~/.gem/credentials` kulcsait — a pontokból `__` lesz, és záró perjelet kap —, ezért egy hoszt-URL alakú kulcs **soha nem egyezik** a `--host` értékével. Ilyenkor a `gem push` bejelentkezni próbál a RubyGems `sign_in` végpontján, amit a Gitea nem ismer, és a hibaüzenet félrevezetően `404 page not found`. Használj **nevesített kulcsot**:
|
||
```
|
||
---
|
||
:gitea: Bearer <token>
|
||
```
|
||
```sh
|
||
gem push --key gitea --host https://git.teletypegames.org/api/packages/<org>/rubygems <név>-<ver>.gem
|
||
```
|
||
Kétség esetén ellenőrizd: `ruby -e 'require "rubygems/config_file"; p Gem::ConfigFile.new([]).api_keys.keys'`.
|
||
4. **Van-e már pipeline.** Nézd meg a repo `.woodpecker.yaml`-ját: lehet, hogy a publikálás már meg van írva és csak sosem futott. Ilyenkor **ne kézzel pusholj** — javítsd a pipeline-t (org-hivatkozások!) és tedd ki a tagot, amire figyel (a `warp_engine`-nél `warp_engine-v*`, nem `v*`).
|
||
**Ha a pipeline-t javítod, a tagot is újra kell húzni:** a Woodpecker a tag commitjából olvassa a konfigot, tehát a javítás előtti tagra futtatott újrapróba is a régi configot használná. Kiadatlan verziónál a tag törlése és újratűzése tiszta megoldás.
|
||
5. **Ellenőrzés.** `tea api --login ttg "/packages/<org>?limit=20"`, majd valódi fogyasztással:
|
||
```sh
|
||
bundle lock # Gemfile: source "<registry>" do gem "<név>" end
|
||
```
|
||
A Gitea a **compact indexet** szolgálja ki (`/versions`, `/info/<név>`); a RubyGems.org-féle `/api/v1/versions/<név>.json` nála 404, ez nem hiba.
|
||
|
||
**Korlát:** a `tea api` csak JSON törzset küld, bináris feltöltésre nem alkalmas — kézi `gem push`-hoz nyers token kell, amit a `tea` titkosítva tárol, tehát a felhasználónak kell megadnia.
|
||
|
||
## A végén
|
||
|
||
Foglald össze, mi hol jelent meg: a Go modulnál a **repo tagje** a kiadás helye (a csomag-registry üres marad, és ez így helyes), a gemnél az **org rubygems registryje**. Ha az `ECOSYSTEM_PLAN.md` említi a csomagot, frissítsd a státuszát.
|