l-ui/docs/release.md

Release process (L-UI fork)

Releases are published on the self-hosted Gitea (rogue/3x-ui-agent). 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/xui-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:

• x-ui-linux-amd64, x-ui-linux-arm64 (+ .sha256 sidecars) — panel
• x-ui-agent-linux-amd64, x-ui-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.