Codex
87 lines
6.2 KiB
Markdown
87 lines
6.2 KiB
Markdown
# 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.
|