27. Upgrade and version numbers
[!ref] Full details in the User Manual, "Upgrade, backup and sync".
27.0 Config directory brand migration (zcode → avlcode)
From v0.6.30-alpha the user-facing brand identifiers — the global config directory, in-workspace .zcode/ → .avlcode/, ZCODE_* → AVLCODE_* env vars, and so on — migrate to avlcode, completed automatically on startup / workspace open, with a toast, keeping old names for dual-read fallback; internal process names (zAgent / zMCP / zWorkspace) and internal env vars such as ZAGENT_* / ZMCP_* are not part of the migration:
| Old | New |
|---|---|
Global config dir ~/.config/zcode/ |
~/.config/avlcode/ |
In-workspace .zcode/ (incl. rag/, sbom.*, etc.) |
.avlcode/ |
Env vars ZCODE_… (e.g. ZCODE_DISABLE_VENV_AUTODETECT) |
AVLCODE_… |
Config YAML and frontmatter fields (x-zcode-…, etc.) |
corresponding avlcode / x-avlcode-… |
UA trailing token zCode/<ver> |
avlcode/<ver> |
SSH remote ~/.zcode, remote workspace .zcode |
~/.avlcode, .avlcode |
Any residual "zCode" in the UI or external output is unified to "AVL Code". If you've hard-coded the old paths / variables in scripts, switch to the new names.
27.1 Version format
MAJOR.MINOR.PATCH[-PRERELEASE][+BUILD]
| Segment | Meaning |
|---|---|
| MAJOR | Incompatible change (data migration / config break) |
| MINOR | New feature (backwards-compatible) |
| PATCH | Fix / optimisation (backwards-compatible) |
| PRERELEASE | alpha.<n> / beta.<n> / rc.<n> |
| BUILD | Build metadata; not part of version comparison |
27.2 Upgrade paths
| Path | Cadence | Description |
|---|---|---|
| In-app upgrade | Daily check by default | Recommended |
| Manual download (install-free) | As needed | Official download page www.avlcode.cn/#download; download, replace and run; config preserved |
| Internal marketplace | Per team config | Org admin controls versions |
Alpha builds are valid for 45 days: counted from the release time encoded in the version number (UTC+8), checked at launch and hourly thereafter; once expired a full-screen lock overlay appears — signed in with usage available: automatically check for updates → download → restart after a countdown ("Restart now" available); not signed in: "Sign in", "Re-check", "Visit website"; signed in without usage: "Buy vouchers", "Upgrade plan", "Re-check", "Visit website"; "Quit app" is always at the bottom.
The official download page provides per-platform builds (Windows x64 / macOS Universal · Apple Silicon / Linux x64 · AppImage · Snap · WebKit 4.1 / Kylin V10 SP1 / UOS V20 / Kylin ARM64) on the alpha channel — always the latest build.
27.2.1 The domestic ARM64 channel
Domestic ARM64 (aarch64) has its own release and update feed, fully isolated from domestic x86:
| Item | Value |
|---|---|
| Artifacts | An archive (linux-arm64-domestic.zip) and a Kylin V10 ARM64 DEB (avlcode_v10_<version>_arm64.deb) |
| WebKit | The DEB bundles a relocatable WebKit 4.1 runtime, so it runs on target machines without a suitable webkit2gtk-4.1 |
| Logical channels | Still dev / alpha / beta / rc / stable; architecture isolation is expressed by a separate feed namespace, not by inventing new channel names |
| Signing | The same SM2 signing key pair and trusted public key as the existing releases |
| Client | On a domestic ARM64 environment the client automatically checks this feed for updates |
This channel currently excludes ARM64 AppImage / Snap builds and multi-architecture manifests.
27.3 Upgrade signature
| Step | Description |
|---|---|
| Download | Pulled from internal upgrade source to local cache |
| Verify | GM signature + embedded public key |
| Replace | Atomic swap of the main binary on verify success |
| Rollback | Auto-rollback on verify or launch failure |