torbenandClaude Code
71170bc1e8
Files changed: - .gitattributes - .gitea/workflows/converters.yml - .gitea/workflows/release.yml - .gitignore - CHANGES.md - VERSION - docs/dev/development.md - instructions/dev/dev-setup.md - instructions/dev/publish-and-ci.md - instructions/dev/testing-conventions.md - testfiles/README.md - testfiles/mail/github-outlook.msg - testfiles/mail/github-roundcube.eml - testfiles/mail/gog-outlook.msg - testfiles/mail/gog-roundcube.eml - testfiles/mail/gog-roundcube.eml.expect - testfiles/mail/tldr-outlook.msg - testfiles/mail/tldr-roundcube.eml - testfiles/office/excel-artificial.xlsx - testfiles/office/excel-business.xlsx - testfiles/office/excel-business.xlsx.expect - testfiles/office/excel-science.xlsx - testfiles/office/pptx-baseline.pptx - testfiles/office/pptx-master.pptx - testfiles/office/pptx-objects.pptx - testfiles/office/word-complex.docx - testfiles/office/word-simple.docx - testfiles/pdf/einstein-dissertation.pdf - testfiles/pdf/ifg.pdf - testfiles/pdf/nist-ai-rmf.pdf - testfiles/pdf/nist-ssdf-genai.pdf - testfiles/zip/archive.zip - tools/chemenu/tests/test_raw_derive_testfiles.py Co-Authored-By: Claude Code <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01SnAJ7Z3CpVD3PRbN73QtU2
72 lines
4.3 KiB
Markdown
72 lines
4.3 KiB
Markdown
---
|
|
type: types/instruction.md
|
|
name: publish-and-ci
|
|
description: How a stack change is published and how its CI run is waited for - the local checks first, tools/wikitool publish, reading the runs through the authenticated Gitea connection rather than curl, how long to wait, when to give up, and why a red run means the build phase is not over.
|
|
---
|
|
# Publish a stack change and wait for its CI run
|
|
|
|
The local checks cover what they cover on this machine; CI covers the same checks plus a full
|
|
`setup-instance.md` replay against a fresh `dist export` (`.gitea/workflows/ci.yml`). A green run
|
|
on the published commit - and, for a converter change, a green `Converters` run (step 3) - is
|
|
therefore the end of the checked stretch of a work package, not a
|
|
formality after it - which is why waiting for it belongs to the phase that wrote the code
|
|
(`stack-build`), and a red run sends the work back there rather than into the closing phase.
|
|
|
|
## When to run
|
|
|
|
- `stack-build`, every time it publishes - its last step.
|
|
- `stack-close`, when its own pull-through of a stale document publishes something of its own
|
|
(that skill's step 3 says when).
|
|
|
|
## Steps
|
|
|
|
1. **Run the local checks, explicitly rather than assumed:**
|
|
|
|
```bash
|
|
tools/wikitool docs verify
|
|
tools/wikitool instructions verify
|
|
```
|
|
|
|
plus the relevant `pytest` run in `tools/` ([testing-conventions.md](testing-conventions.md)).
|
|
A red check here is fixed before anything is published.
|
|
|
|
2. **Publish with `tools/wikitool publish`.** The gates apply as everywhere (AGENTS.md § Gates);
|
|
an exit 42 is shown to the user verbatim and waited on. When the changeset touches `tools/`,
|
|
`types/`, `instructions/`, `AGENTS.md` or a `<stage>/CONTRACT.md`, `publish` prints a
|
|
one-line note that CI is the last mechanical check still to come and that what follows it is
|
|
covered by none. A push to `main` that moves `VERSION` additionally triggers a tagged release.
|
|
**CI does the tagging** - a session never creates a tag, which is what keeps AGENTS.md
|
|
invariant 5 intact.
|
|
|
|
3. **Wait for CI on the published commit, this way.** The push-triggered runs take about
|
|
**4 minutes**; a push that moved `VERSION` to a suffix-free release adds about **1 minute**
|
|
for the release job.
|
|
|
|
- Read the runs for the published commit's SHA through the authenticated Gitea connection
|
|
`ENVIRONMENT.md` lists (the Gitea MCP's `actions_run_read`, `list_runs`), right after
|
|
`publish`, to get their ids. **Never anonymously via `curl`:** Gitea answers the Actions
|
|
API with `401 token is required` even for this public repo.
|
|
- Check again after about 4 minutes (5 with a release job), then once a minute.
|
|
- **Give up after 15 minutes** and hand the open runs to the user by id and link, rather than
|
|
waiting on.
|
|
- Any shell loop that polls instead must **end on the first non-2xx status or missing field**
|
|
and print the raw response. A loop that treats an error as "not finished yet" never ends;
|
|
that happened in the #139 close-out.
|
|
- Keep the polling out of the main context where the harness allows it - a background
|
|
command or a fork - so a long wait does not fill the session with run listings.
|
|
|
|
**Converter changes have a second run.** When the published commit touches the converter
|
|
surface - `tools/chemenu/filters/`, `tools/chemenu/commands/raw/derive.py` or `accept.py`,
|
|
`tools/chemenu/tests/test_raw_derive*.py`, `tools/chemenu/tests/binary_formats.py`,
|
|
`tools/requirements.txt` or `.gitea/workflows/converters.yml` - the `Converters` workflow
|
|
(`converters.yml`) starts by itself beside CI and derives the real documents of the private
|
|
test corpus. It takes longer than CI (allow **10 minutes**); wait for it the same way, with
|
|
the same give-up time, and count a red run like a red CI run (step 4). Start it by hand
|
|
(`actions_run_write`, `dispatch_workflow` on `main`) when only the private repository changed
|
|
or when the commit reaches the converters only indirectly. A release without suffix runs the
|
|
same steps as the first job of `release.yml`, which the release waits for.
|
|
|
|
4. **A red run is not waited past.** Read the failing job's log, fix the cause, and go back to
|
|
step 1: this is still build work, whichever skill published. The phase that published ends
|
|
only on a green run, and the issue stays open until there is one.
|