l-ui/docs/release.md

Release process (L-UI fork)

PLACEHOLDER REPO — rename batch: rogue/l-ui in this document, in internal/selfupdate/selfupdate.go, in panel.go, in scripts/release-build.sh and in the install scripts is a placeholder, NOT yet the real Gitea repo name. The Gitea repository has not been renamed in this batch. Do not publish any release from this branch until the user confirms the exact repo spelling and every placeholder is updated to it. See RENAMING.md (pending items).

Releases are published on the self-hosted Gitea (rogue/l-ui — placeholder, see above). Build with scripts/release-build.sh; this document is the rules that script encodes. Read it before cutting a release — several rules exist because violating them already caused a production incident once.

Two independent version lines

The panel and the agent are maintained as separate lines (policy set 2026-10-24). They never borrow each other's numbers.

line	form	source of truth	injection
panel (master)	V2.4.0	release tag	-X .../internal/config.displayVersion
agent	A2.3.0	the release's agent-version.txt marker	-X .../internal/config.agentDisplayVersion (agents only)

• The agent line moves only when agent code changes (anything under cmd/lui-agent*, internal/agent/, or code reachable from the agent binaries). A panel-only change ships a new panel release whose agent assets are the previous ones, untouched.
• An agent built without injection reports the source default (defaultAgentDisplayVersion in internal/config), which must always equal the current agent line. When the agent line bumps, bump that constant in the same commit.
• Masters resolve "latest agent version" from the newest release's agent-version.txt marker (selfupdate.ResolveLatestAgentTarget), never by rewriting the panel tag. Releases older than the marker convention (≤ V2.4.0) transparently fall back to the legacy tag-derived value, which is exact for them (their agent assets were still stamped from the tag).

Asset set

Every release ships exactly:

• l-ui-linux-amd64, l-ui-linux-arm64 (+ .sha256 sidecars) — panel
• lui-agent-linux-amd64, lui-agent-linux-arm64 (+ .sha256) — agent
• agent-version.txt — one line, the agent line's version (A2.3.0)
• geoip-country.mmdb lives in its own standing release, not here.

No Windows executable. See the freeze below.

The agent reuse rule

When agent code is unchanged since the previous release:

1. Download the previous release's agent binaries and their .sha256 sidecars.
2. Verify each binary against its sidecar.
3. Upload them to the new release byte-for-byte — do not rebuild, do not re-stamp. Rebuilding the same source with a new injection would mint a binary that claims a version its code does not earn and would churn every node's update state for nothing.
4. agent-version.txt still names the same agent version.

When agent code changed: build fresh agents, bump only the agent line (and defaultAgentDisplayVersion), generate fresh sidecars.

scripts/release-build.sh implements both paths (AGENT_CHANGED=0/1).

Windows freeze

The Windows agent is frozen at A2.2.1; V2.4.0 was the last release containing x-ui-agent-windows-amd64.exe. One machine (TYYUN, probe-only) runs it and it will not be updated.

Consequences that are part of the release contract:

• install-agent.ps1 stays pinned to the V2.4.0 release base. Do not bump it: newer releases contain no exe for it to download.
• The frozen agent cannot adapt to master changes, so the master side of its protocol is contract-locked by TestAgentLegacyWindows221Contract (register / heartbeat / probe-report request shapes; config payload keys; response envelopes). If that test goes red, the change breaks a node that can never be upgraded — stop and reconsider.

Pre-publish checks

• agent-version.txt content equals the agent assets' reported version (for reused assets: the version they already report).
• Sizes and sha256 of every asset read back through the API after upload match the local files.
• Binaries are static (readelf -d shows no NEEDED) and carry no CGO stub strings.
• Panel self-reports the new V version; agent self-reports the intended A version (unchanged line ⇒ unchanged report).
• Pilot: update ONE node first; after it converges, stat the on-disk agent binary and compare size + sha256 with the release asset. (V2.3.0 lesson: the version display can look right while the fleet still runs the previous asset generation — the update asset an agent fetches is decided by the agent's own build.)
• install-agent.sh's RELEASE_BASE points at the new tag.