# Release Governance This document owns UniDesk release-line, runtime-version, CI/CD control-plane and feature-flag governance. The decision record is [GitHub issue #6](https://github.com/pikasTech/unidesk/issues/6). ## Decision Scope The governance decision covers four boundaries: - stable maintenance work for the current usable UniDesk architecture; - high-risk integration work on `master`, including the Rust backend-core rewrite and next-generation infrastructure changes; - CI/CD server runtime pinning versus CLI compatibility; - short-lived feature flags versus long-lived release or service boundaries. This document records the target policy. It does not by itself create a `release/v1` branch, change `deploy.json` schema, or authorize production deployment. ## Release Lines `master` remains the normal integration branch for UniDesk source changes. New architecture work, backend-core Rust migration, provider-gateway reshaping, Code Agent sandbox work, and other high-risk development can continue there, but `master` must not be treated as the implicit production or stable-dev runtime truth. `release/v1` is the planned stable maintenance line for the existing usable architecture. Its baseline should be the last known-good TypeScript backend-core version or an equivalent verified stable commit. After it is enabled, it may accept only: - bug fixes for existing behavior; - high-availability, recoverability and observability fixes; - CI/CD reliability fixes; - security and compatibility fixes; - narrowly scoped deployment fixes that preserve the existing architecture. `release/v1` must not carry new product features, large architecture changes, the default Rust backend-core switch, or speculative Code Agent sandbox behavior. Any exception requires an explicit issue and a deployment rollback plan. Until the release-line implementation is completed in CLI, CI, CD and documentation, the current repository rule still applies: UniDesk agent changes are developed on `master` and pushed to `origin master`. Creating or updating `release/v1` is an explicit release operation, not a replacement for arbitrary feature or fix branches. ## Stabilization Mode UniDesk enters stabilization mode when core availability is threatened by control-plane, deployment, backend-core, provider-gateway, Code Queue, or CI/CD instability. During stabilization: - high availability, trace visibility, deploy reproducibility and rollback safety take priority over new features; - production and stable dev should run only from commit-pinned desired state; - live manual repairs are temporary and must be converted into pushed Git changes; - high-risk architecture work may continue only on the integration lane and must not be promoted into stable runtime by default. Exit from stabilization requires CI/CD, deploy verification, Code Queue recoverability and dev/prod isolation to be demonstrably healthy. ## CI/CD Runtime Versioning CI/CD server and control-plane services are production-like infrastructure. Their runtime version must be pinned by `deploy.json` to the production desired commit, not implicitly follow the operator's local worktree or the latest `master`. The CI/CD CLI may run from `master` because it is the command vocabulary and should evolve quickly. That compatibility is acceptable only when all of the following hold: - CLI changes are backward compatible with the pinned server version or fail with a clear unsupported-version error; - server-side policy remains authoritative for deploy boundaries, allowed environments and dangerous operations; - the CLI uses server capability data instead of guessing support from local code; - an unsupported server capability must not be bypassed through raw SSH, direct `kubectl`, direct SQL, or hidden fallback commands. CI/CD services should expose their commit, API/schema capability, supported environments, supported services and supported operations through health or capability endpoints. The CLI must include the observed capability or server commit in diagnostics for failed operations. ## Dev Environment Lanes The target model is to separate a stable maintenance dev lane from a master integration dev lane, for example with explicit names such as `dev-v1` and `dev-master` or an equivalent schema. The stable lane validates `release/v1` fixes without disrupting production. The master lane validates high-risk work and may be less stable. This split must be implemented explicitly in `deploy.json`, deploy planning, deploy apply, CI, frontend labels and diagnostics. Until that work is done, existing commands continue to read the currently documented manifest ref such as `origin/master:deploy.json#environments.dev`; operators must not simulate split lanes through dirty local manifests, hidden branches, or undocumented runtime edits. ## Feature Flags Feature flags are short-lived risk controls, not a long-term architecture partitioning mechanism. Prefer release lines, service boundaries and deployment boundaries for durable divergence. Allowed feature flags: - release toggles with a named owner and removal condition; - kill switches for availability protection; - migration toggles that are observable in health output and removed after rollout; - compatibility toggles needed for a bounded transition. Disallowed feature-flag patterns: - permanent flags with no owner or removal issue; - nested flag combinations that create untested behavior matrices; - flags that hide a second data, control, event, or deployment path; - flags that let production bypass the documented desired-state or server-side deploy policy. Every feature flag must have a default, an owner, an observability signal, a removal condition and tests for both active states when both states can run in production. ## Promotion And Backport Rules Stable-line fixes must remain traceable. A fix may land first on `master` and then be cherry-picked to `release/v1`, or land on `release/v1` and be forward-ported to `master`, but the chosen direction must be recorded in the related issue or pull request. Deployment truth remains commit-pinned. Neither `release/v1` nor `master` may be represented by mutable local runtime files, dirty worktrees, copied source trees, copied images, or manual hotfixes that are not committed and pushed.