Immutable. This exact content is served forever at /api/v1/blob/75443a092173746a.
--- name: project-development-standard description: Repository-wide branching, PR, release, tagging, and secret-incident rules for this repo. Use whenever creating a branch, opening or reviewing a pull request, choosing a PR target (main vs release/*), backporting or cherry-picking a fix, cutting a release, creating a version tag, or responding to a committed secret. Also use to validate that an existing branch name and its PR target match the allowed directions. --- # Project Development Standard Authoritative source: [docs/project-development-standard.md](../../../docs/project-development-standard.md). This skill is the operational digest; when in doubt, read the full document. ## Golden rules 1. Never push directly to `main` or any `release/*` branch — every change lands through a PR, including docs-only changes and locally stranded commits. 2. Branch kind determines the PR target. Never mix directions. 3. Published tags are immutable. Never force-update, delete, or reuse one. 4. If a secret was committed: revoke it FIRST, rewrite history second (see below). ## Branch kinds and PR targets | Branch | Purpose | PR target | |---|---|---| | `feature/*` | New feature work | `main` | | `bugfix/*` | Normal bug fix for trunk | `main` | | `hotfix/*` | Urgent fix for a published release line | `release/*` | | `backport/*` | Fix moving from `main` to a release line | `release/*` | | `cherry-pick/*` | Fix moving from a release line back to `main` | `main` | Disallowed: `release/*`→`main`, `main`→`release/*` wholesale merges, `feature/*`→`release/*`, `hotfix/*`→`main`, `backport/*`→`main`, `cherry-pick/*`→`release/*`. Before opening a PR, verify: source branch prefix matches the target branch per the table above. The `Validate Release PR` workflow enforces this; do not fight it. ## Opening a PR — required content Every PR body must include: - what user or engineering outcome the change delivers (one concise paragraph); - links to the issue / task / original PR when one exists; - the verification performed — name the exact test commands and results, and call out any intentionally unrun checks with the reason; - migration, configuration, security, or rollback notes when the change can affect existing users or deployments. Additionally for maintenance PRs: - `hotfix/*` / `backport/*`: name the target `release/*` branch explicitly. - `backport/*` / `cherry-pick/*`: link the original change, preserve the original commit SHA in the description, and state why the cross-branch transfer is required. Public-repo hygiene: this repository is public. PR bodies, commit messages, and committed docs must not contain credentials, tokens, internal hostnames, deploy targets, secret-store paths, or other internal infrastructure details. ## Merge policy - Squash-merge `feature/*` and `bugfix/*` PRs — one reviewable commit per logical change on `main`. - Keep `hotfix/*`, `backport/*`, `cherry-pick/*` small and traceable. - Update a PR by rebasing its source branch; do not merge the base branch into a release-maintenance branch just to make it mergeable. - Merge only after required reviews and required checks pass. Revert regressions with a new PR, never by force-pushing shared history. ## Releases and tags - Cut `release/vMAJOR.MINOR` from a reviewed, stable `main` commit; after the cut it accepts only `hotfix/*` and intentional `backport/*`. - Tags are SemVer `vMAJOR.MINOR.PATCH` (pre-releases: `-alpha.N` / `-beta.N` / `-rc.N`), annotated, created deliberately at a release point — never as a side effect of branch synchronization. - Every published artifact must trace to exactly one release tag; each release records version, date, changelog, and any breaking/migration/security notes. ## Backport vs cherry-pick (direction cheat) - Fix born on `main`, needed on a release line → `backport/*` → PR into `release/*`. - Fix born on `release/*`, needed on trunk → `cherry-pick/*` → PR into `main`. - One fix (or one tightly related fix set) per branch. ## Committed secret — emergency flow 1. Revoke the leaked credential immediately (before anything else). 2. Generate/rotate the replacement. 3. Review access logs for suspicious use. 4. Only after the credential is dead: rewrite history (`git filter-repo --path <file> --invert-paths`), then force-push branches and tags. 5. Tell collaborators to `git fetch --all` and re-align local branches. A secret-scanning CI gate prevents new leaks but never replaces this flow for an already-exposed secret. ## CI gates to expect on PRs | Gate | Workflow | |---|---| | Branch direction | `Validate Release PR` | | Analyze + unit/widget/golden tests | `PR Layered Tests` (PRs into `main`) | | Build verification | `Build and Release XWorkmate Packages` | | Release E2E | `Release E2E Gates` (scheduled/dispatched; Patrol non-blocking) | Changes touching native packaging, permissions, authentication, secrets, or release scripts need the targeted tests from `docs/security/secure-development-rules.md` in addition to normal PR checks.