Branching & release regime · for sign-off

Git branching strategy & release regime

One promotion-only model. Three active shared repos adopt it now; the Rust server is approved but deferred; the repo-product line follows as it matures. Approve this before we cut branches and wire CI/CD. It unblocks the UI re-skin (PR #6) and every future change.

TL;DR

We are consolidating the team onto shared repos. Here is the branch & release regime to approve before we cut branches and wire CI/CD. One model (promotion-only, environment-mapped), adopted now by the three active shared repos (Rust deferred), with the repo-product line following as it matures. It unblocks the UI re-skin and every future change.

The branch model

Three long-lived branches, promotion-only. No direct commits to any. Every move up is a PR plus review.

Long-lived (promotion-only) Promotion (PR + review) Short-lived → dev Hotfix path

Long-lived: promotion-only

dev: shared integration. Everyone's work lands here first.
staging: release-candidate quality, externally demoable, pre-production. Promoted from dev.
main: production / golden source, always in sync with prod. Promoted from staging. Manny/CPO-owned.

Short-lived

feat/ · fix/ · chore/

Cut off dev, PR back into dev.

release/

Cut from dev, stabilized, promoted dev → staging → main.

hotfix/

Cut from main; PR into main; immediate back-merge PR to dev; staging receives it via the next dev → staging promotion.

Branches map to environments

Each long-lived branch auto-deploys to one environment. We do not create extra branches per person or per environment.

Branch	Environment	URL / target	Owner
dev	Dev / preview	preview	Team
staging	External demo	demo-deploy	Dennis
main	Production	stable.ascend.gl (pre-release)	Manny/CPO

On "demo-dev"

Dennis proposed demo-dev and owns CI/CD. demo-dev maps precisely to the dev branch on the preview environment; demo-deploy stays as the staging / external-demo target. Both terms are preserved, resolved to environments.

Scope: which repos

Three active shared repos adopt the structure now; the Rust server is approved but deferred; the repo-product line follows as it matures.

Repo	Adopts	Notes
Active shared repos: branches cut now
ascend-react-ui	Now	Hosts the blocked UI re-skin (PR #6).
ascend-nodejs-server	Now	Shared backend.
ascend-protocol	Now	Contract source of truth.
Approved, deferred
ascend-rust-server	Deferred	Experiment, not in production. No branches/tags cut now; adopts when it ships.
Repo-product line: adopts as it matures
ascend-repo-ui	As it matures	Repo-product line; same regime.
ascend-nodejs-repo-server	As it matures	Repo-product line; same regime.

Forward note: the UI repo may later decouple client and admin into separate repos, both consuming the shared design system via a package in the product/ spoke. To be decided. Not now.

CI/CD & hosting

Recommendation · confirm with Dennis

Consolidate everything on Google Cloud. Drop Vercel and Railway. One platform across the apps, the server, and the chain infra: one IAM, secrets, billing, DNS, logging, and deploy surface. That is the right footprint for a two-person team, and it aligns with Dennis's preference for the gcloud monolith.

The Google Cloud monolith

App Engine serves the apps (client + admin).
Cloud Run / GCE runs the Node server.
Chain infra consolidates onto gcloud too.
Manny/CPO holds admin plus full programmatic gcloud-CLI control, the condition for going gcloud-only.

Per-branch environments map cleanly

App Engine version-URLs and Cloud Run tagged revisions (--no-traffic --tag): all gcloud-CLI-scriptable.
One honest tradeoff: ephemeral per-PR preview deploys (Vercel's one real edge) need a small Cloud Build PR-trigger to script on gcloud. Acceptable, because external demos run off staging, not ephemeral PR branches.

Interim, not the destination

Cloudflare (current prod host at stable.ascend.gl) and the local/test chain are interim. As we approach GA, the app, the server, and the chain consolidate onto Google Cloud, and the chain moves to a real blockchain (mainnet).

Versioning & changelogs

SemVer. Cut v1.0.0-rc.1 across the active shared repos now (Rust deferred). The current feature set is rich enough to stand as a release candidate.
Tag convention. Tags are a leading v plus SemVer: v1.0.0-rc.1 for a release candidate, advancing to v1.0.0 at release. Increment the rc number per candidate (-rc.1, -rc.2, …). This is the format release tooling parses and sorts (GitHub Releases, semantic-release, npm, changelog generators), so we use it identically across every repo: a plain v + SemVer with no extra prefixes or suffixes, which keeps every tool resolving and ordering releases consistently.
At GA, drop the -rc: v1.0.0-rc.N is the release candidate; at launch it becomes v1.0.0. Per SemVer, 1.0.0-rc.N is a pre-release of 1.0.0 and sorts below the release.
Keep a Changelog per repo going forward: CHANGELOG.md with an [Unreleased] section plus dated version sections.

Guardrails: how it is enforced

Branch protections enforce promotion-only: no direct pushes to dev, staging, or main; merges and promotions require a PR + review + green CI. Manny/CPO owns the main (production) gate.
Commit-guards reject unapproved directories and formats: anything introduced outside the agreed structure fails before it lands. (Complementary to branch protections, not a substitute.)
Shared tooling and the ascend-os hub carry the structure, so every contributor inherits it by default.

What this unblocks

Sign-off on this regime.
Cut the branches across the active shared repos (Rust deferred).
Dennis wires CI/CD per deploy branch.
Pull and resubmit the UI re-skin PR (#6) under the regime. It is conflict-prone without it.
A fresh ascend-os checkout from main pulls fresh from each repo's main.

The ask

Approve the model, or request changes: branch model, promotion flow, CI/CD ownership, v1.0.0-rc.1, changelogs, and guardrails. Once approved, the same model goes for final sign-off before any branches are cut. One approval unblocks the whole pipeline.