Levandor

Release workflow — design handover

8 min read

Handover for a separate session that will design a whole release workflow. This is the delta from a day spent shipping two tickets into Raiffeisen 1.9.11.100 and rebuilding the TjK flow — what I learned, what contradicts the current documentation, and the decisions the design session has to make.

Read devel-update-and-release-flow first

It already covers Phases 0–5 (preconditions → devel update → validation → ticket collection → gates → pre-push re-check) in 28K of detail, and it is good. Do not redesign from scratch — extend it. Everything below is either new, or corrects it.

1. The biggest gap: there are TWO release topologies, and only one is documented

devel-update-and-release-flow Phase 4 gate 1 states:

The chore/... branch is MERGED into customization/<partner> via PR. The tag is cut from the customization branch, not from your working branch.

Raiffeisen 1.9.11.100 does not work like that, and it is a live, in-flight release. Verified 2026-08-11:

Documented (devel-update flow)Observed (Raiffeisen .100)
Integration branchcustomization/<partner>chore/FKITDEV-9156-raiffeisen-release-1.9.11.100
What merges into itone chore/... devel-update branchindividual feature/fix PRs, retargeted onto it
Basecustomization/<partner> tiptag raiffeisen-1.9.11.99
Tag sourcethe customization branchunresolved — nothing tagged yet
Back-mergen/a, it is the customization branchowed and not done

Concretely: vuer_oss PR #7971 (FKITDEV-8827) and vuer_css PR #3064 (FKITDEV-8787) were both retargeted off the dead release/FKITDEV-8902-raiffeisen-1.9.11.95 branch and merged into the .100 release branch on 2026-08-10. Neither is on customization/raiffeisen or devel. raiffeisen-1.9.11.100 is not tagged in either repo.

The consequence nobody has hit yet

Any branch cut from customization/raiffeisen today silently loses both fixes. The release branch is tag .99 + the fixes; the customization branch is tag .99. There is no error, no conflict — the work is simply absent. vuer_css PR #3051 tried to land the 8787 fix on customization/raiffeisen and was closed unmerged in favour of the release-branch route, so the fix has no path home yet.

Design question 1: are these two genuinely different flows (a scheduled devel-update release vs. a hotfix/feature release cut from the last tag), or is one of them an accident that should be normalised? If both are legitimate, the workflow needs to say which one applies when, and the back-merge step needs to be an explicit gate, not an assumption.

2. Release trains are per partner, and numbers collide across teams

There is no global release number. On 2026-08-11 Raiffeisen was on 1.9.11.100 while NÚSZ was on 1.9.11.48 and Generali on 1.9.11.19. Any tooling or prompt that carries “the release” as a scalar is wrong.

Worse, numbers get renumbered after the fact: NÚSZ .47 → .48 because another team took .47 for a standalone CRNUSZ-102 release. So a version is not stable until the tag exists.

Rule for any tool: resolve the version from that partner’s own release ticket (project: <YTPROJECT> Assistance Type: Release, newest open), never from context, a sibling partner, or a human’s memory. This is baked into /fk-tjk already.

3. “PR merged” is not “code is in the release”

gh pr view --json state returning MERGED tells you nothing about whether the code is on the branch you are about to tag. Verify by content:

# explicit refspec - these clones have narrowed remote.origin.fetch
git fetch origin "+refs/heads/<release-branch>:refs/remotes/origin/<release-branch>"
git ls-remote origin refs/heads/<release-branch>     # cross-check the SHA matches
git grep -n "<a distinctive string from the change>" origin/<release-branch> -- <path>

Both today’s changes were confirmed this way — the 8787 self-heal at server/socket/events/selfservice-v2.js:303-322 and the abort clear at :575, and all three 8827 files present as blobs. narrowed-fetch-refspec-stale-devel-merge explains why the naive fetch lies.

Design question 2: should the workflow require a content-level assertion per changelog line before the tag is cut? It is cheap and it is the only check that actually proves the release contains what the changelog claims.

4. Ticket state is not maintained, so it cannot be a signal

Both dev tickets were still State: Pending, Blocker: Review Needed, Review: Ready to Review on 2026-08-11 — a full day after their PRs merged. Both partner-side parents (ASSRAFIPI-119, SLARAFIPI-60) were still Blocked / Release needed. Nobody moved anything.

Related: Bence Varga asked on SLARAFIPI-60 on 2026-07-30 “melyik release-be tud ez belekerülni?” — the answer has been unambiguous since 2026-08-10 (1.9.11.100 / ASSRAFIPI-135) and was never posted.

Design question 3: the workflow needs an explicit “close the loop” phase — move dev tickets, move partner tickets, answer outstanding partner questions on the SLA/ASS ticket. Today that work is invisible and therefore never done. Note /fk-tjk is deliberately read-only against YouTrack; if write-back is wanted, that is a decision, not an oversight.

5. Release tickets are created blank and stay blank

ASSNUSZ-126 (“NÚSZ Release 1.9.11.48”) has TODO in every field — Changelog, Jegyek, GitHub tagek, Telepítési utasítás. It is the template, unfilled, and it is the current release.

So the release ticket is not a reliable source of scope. Anything that needs the ticket list must fall back to the dev tickets and git history. release_tickets.py (Phase 3 — Collect the release tickets) is the right tool for this and should probably become the thing that populates the release ticket rather than a side report.

By contrast ASSRAFIPI-135 (.100) does have a real 9-line changelog. So it varies per partner/author, which means the workflow cannot assume either way.

6. Document production is now solved — reuse it, do not redesign it

/fk-tjk was rewritten today into a zero-context flow (historian → partner/base/release → gather → evidence regeneration → draft → render → tester runbook → hand-off). Full detail: tesztjegyzokonyv-generation-flow and tesztjegyzokonyv-partner-release-document-structure.

What the release workflow needs to know:

  • All partners are standardized on the release-doc shape (decision 2026-08-11), and the newest TjK in ~/Downloads is the authoritative format. Legacy shapes (sablon, .xlsx) survive only as priorShape in partners.json, to warn a customer their format changed.
  • Build is two mechanical steps, no hand-written code: append_release_sections.py newdoc rebases any partner’s TjK onto a new partner+release, then plain append adds sections from JSON.
  • Evidence is regenerated, never quoted from old reports — old dev boxes get decommissioned and old numbers rot. Today both suites and the 8827 .dev-e2e/ harness were re-run to produce dated output.

Rebasing one partner's TjK onto another leaks ticket ids

The TOC is a static Word field: it keeps the previous document’s heading text until refreshed. A Raiffeisen→NÚSZ rebase left ASSRAFIPI-124 / SLARAFIPI-59 in the TOC — another customer’s ticket ids inside this customer’s document, invisible in the body. The tool now clears the cache and refuses to write if any ASS…/SLA…/CR…/BUG… id from the source survives. Any document-templating step in the release workflow needs the same class of check.

Dependency: the flow reads its base from ~/Downloads. If that directory is tidied, the format source disappears and it falls back to ticket attachments — which for NÚSZ would find the legacy shape. If the release workflow is to be robust, the canonical base should move somewhere stable.

7. Delivery is the least-understood phase

Nobody has confirmed whether .100 ships via the modern vuer-release project or the legacy vuer_build/partner/raiffeisen path. It is recorded as delivery_target: unconfirmed on raiffeisen-1.9.11.100. The NÚSZ hub shows this materially changes the cut procedure.

Design question 4: this is the phase with the least written down and the most partner variance (see FKITDEV-8344-vuer-release-migration-batch — six partners were mid-migration between the two). It probably deserves the most attention in the design session.

8. Tooling inventory — what already exists

ThingPathStatus
Devel-update + release flowdevel-update-and-release-flowgood, extend it
Release ticket collector.claude/scripts/release_tickets.pyworks; two-bucket output
TjK flow.claude/commands/fk-tjk.mdrewritten 2026-08-11
TjK renderers.claude/scripts/tjk/{append_release_sections,render_tjk}.pyboth --selfcheck clean
Partner map.claude/scripts/tjk/partners.json14 partners; priorShape verified for 3
YouTrack read client.claude/scripts/fkticket/client.pyread-only; _get / fetch_issue / download

Note /fk-tjk and release_tickets.py both independently work out “what is in this release”. That overlap is a natural seam for the design session — one collector, two consumers.

9. Environment gotchas that cost time today

  • rtk mangles arguments. git show <rev>:<path> had :server/socket/ eaten, producing a bogus “unknown revision”. It also swallows jest --verbose per-test lines entirely. Workarounds: drive git from a python subprocess args list, and use jest --json --outputFile then parse. Extends rtk-mangles-curl-and-pipes.
  • Worktree node_modules drifts from the branch lock. A branch that changed yarn.lock left the tree unable to run jest (Cannot find module '@babel/plugin-proposal-class-properties'). Fix: yarn install --frozen-lockfile in that worktree before concluding anything about tests.
  • textutil cannot read PDF — it hands back the raw stream and exits 0. Use pdftotext -layout.
  • ~/Downloads has decoys — a 765K CV sits next to the 763K TjK. Match documents by name, never by size or list position.
  • Docker is OrbStack; the build host is fk-dev (100.91.108.61) and ssh is aliased, so command ssh. ssh Facekom is dead. See dev-build-host.

10. Suggested shape for the design session

The existing doc ends at “gates”. The missing half is everything after the code is right:

Phase 6  Cut        tag both repos; decide the source branch per topology (§1)
Phase 7  Back-merge release branch → customization/<partner> → devel; assert no orphans (§1)
Phase 8  Document   TjK + tester runbook; execute the runbook; PDF; attach (§6)
Phase 9  Deliver    image build / vuer-release vs vuer_build (§7)
Phase 10 Close      move dev + partner tickets, answer open partner questions (§4)

Phases 7 and 10 are the two that are currently done by nobody, and §1 is the ambiguity that has to be resolved before 6 and 7 can be written down at all.

Graph View

Backlinks