KuberCoin Docs

Mainnet Policy

Release gates, rollback rules, and staged rollout coverage for mainnet changes.

Overview

The mainnet policy describes how changes move from implementation to production on the public KuberCoin network. It exists so release decisions are reviewable before they affect users: what can ship, what must wait, how long staged rollout should take, and what evidence is required before an operator treats the build as safe for the public network. The goal is not bureaucracy for its own sake. The goal is to make release decisions predictable enough that contributors, node operators, exchanges, and wallet maintainers can plan around them.

This page applies to the reference node, the public RPC surface, the explorer, the wallet, the docs portal, and any other first-party service that can influence production behavior or user trust. It does not replace the governance process; it sits below governance and above day-to-day implementation work. Governance decides what is allowed. This policy describes when the change may be rolled out and what proof is needed before rollout starts.

Change classes

Not every change carries the same release risk. A typo fix in the docs portal does not need the same ceremony as a transaction-validation change in the reference node. For that reason, maintainers classify changes into a small set of buckets before they are promoted:

  • Documentation-only. Copy edits, link fixes, and clarifications that do not alter behavior.
  • Operational. Monitoring rules, deployment scripts, default configuration, and release metadata.
  • User-facing. Wallet, explorer, or SDK changes that affect user workflows but not consensus.
  • Protocol-sensitive. Consensus, mempool, wire-protocol, or validation changes that can affect chain behavior.
  • Emergency. Narrow hotfixes intended to stop active harm or restore service in an incident window.

The release manager may tighten these labels when a patch combines more than one class. For example, a release that bundles a node fix, a wallet UI update, and a docs-only cleanup should be reviewed at the highest risk level present in the batch rather than the lowest.

Release gates

Before a build can be tagged for mainnet, the maintainer responsible for the change must show that the patch passed the checks appropriate to its class. The exact command list lives in the repo, but the policy requires the evidence to be visible and reproducible. At minimum, a release candidate should include:

  1. A clean source tree with no unrelated generated files or local-only debug edits.
  2. A passing unit test run for the changed surface and any directly adjacent modules.
  3. A passing integration or smoke test when the change affects networking, persistence, or user-visible flows.
  4. A short release note that explains the user impact, the risk class, and the rollback plan.
  5. A reproducible build artifact whose hash is recorded in the release log before distribution.

Protocol-sensitive changes require an additional review step from at least one maintainer who did not author the patch. That reviewer is expected to validate the consensus impact, the upgrade path, and any compatibility notes that need to be shared with operators before the release is promoted.

Rollout and coverage

Mainnet releases should be promoted in stages unless the change is a documented emergency fix. The default rollout pattern is:

  1. Internal preflight. Build on a clean runner, verify hashes, and confirm the changelog matches the artifact.
  2. Canary. Publish to a small, monitored set of operators or hosted services first.
  3. Coverage check. Confirm that the targeted nodes, wallets, and docs surfaces still resolve every expected route and RPC method.
  4. Full promotion. Expand to the wider mainnet fleet after the canary window stays healthy for the agreed observation period.

Coverage means more than "the binary starts". Operators should be able to verify that the release still serves blocks, relays transactions, responds to authenticated RPC calls, and presents a coherent story on the public docs and transparency surfaces. When a release changes any of those promises, the release note must say so explicitly instead of assuming the operator will infer it from a version number alone.

If the rollout requires coordination with exchanges, custodians, or infrastructure providers, the release manager should publish the coordination window in advance. The intent is to avoid surprise maintenance windows and to give downstream operators enough notice to avoid automatic restarts during a sensitive upgrade period.

Rollback rules

Every mainnet change must have a rollback path before it is promoted. Rollback does not always mean "revert the code". Sometimes it means disabling a feature flag, restoring a previous config file, or withdrawing the release candidate from mirrors before most operators have fetched it. The policy requires the team to write down the rollback method before the first production operator installs the candidate build.

The release manager must also identify the rollback trigger. Typical triggers include a failed canary, a chain-divergence warning, a crash loop in the node process, a sustained rise in error rate, or a security report that makes the release unsafe to continue promoting. A trigger should be observable by the on-call team without needing to interpret intent or guess at the author’s original plan.

If the release is protocol-sensitive, the rollback notes must include whether the previous version can safely remain on the network during the rollback window. That detail matters because some changes are intentionally forward-only: operators need to know whether they may pause promotion, whether they must coordinate a full upgrade, or whether they are dealing with a hard fork that cannot be reversed by ordinary operational means.

Exceptions and emergency path

Emergency releases exist, but they do not waive accountability. They simply shorten the ceremony when the network is already under active threat or when a safety issue would become worse if the team waited for the normal review cadence. In an emergency, the author or incident lead may promote a narrowly scoped patch as long as the release note records why the normal process was bypassed, what risk was accepted, and who authorized the exception.

Emergency promotion should remain the exception. If the same kind of issue happens more than once in a quarter, maintainers should backfill the missing automation, add tests, or change the deployment process so the next release can follow the normal path. A recurring emergency path is a sign that the release discipline is too loose or the codebase is carrying preventable operational debt.

References