2 · Branch strategy

TL;DR

Objective — pick the branch model the rest of the playbook commits against (Option A, one setup branch with one commit per phase, or Option B, a branch per phase merged via PR) and record the choice so every later phase follows it.

Steps at a glance:

1. Choose a branch model — Compare the two shapes, run the decision matrix rather than guessing, then record what you picked and why.
2. Understand the branch model — Option A: the import lands on develop, the immutable author/vX.X.X anchors the vendor, and a long-lived Setup/Initial-Launch carries one commit per phase.
3. Know when the branches are created — Branch creation happens after the repo exists — don’t run anything yet:.
4. Confirm the wider project strategy — The branch model is one of five setup decisions later playbook sections assume you’ve already made.

User part + done-when

👤 User part — this page is a decision, not a command run: choose Option A or B for how you (and any teammates) want history to look, and record it in Zaj-PROJECT.md. No branches are created here.

Done when a model is chosen, recorded with its reason, and you understand that develop is created at init and the working branch right after the first commit.  ·  ⏱ ~10 min  ·  👤 a user/team decision.

Background

The branch model you pick here is the spine of every later phase — each phase commits against it. Pick once, deliberately. This page is the decision; the branches themselves get created during Initialize the repository and Commit & freeze.

Steps

1. Choose a branch model

Compare the two shapes, run the decision matrix rather than guessing, then record what you picked and why.

Who does this

👤 User (or the team) makes and records this call — it’s a workflow preference, not something an agent should decide for you.

1. Compare the two models.

   	Option A — one branch for all phases	Option B — one branch per phase
   Shape	A single Setup/Initial-Launch branch off develop, one commit per phase	A Setup/Phase-N-* branch per phase, merged via PR
   Pro	Simple, linear, maps 1:1 onto the playbook; clear history	Reviewable, granular, easy to revert a single phase
   Con	Harder to revert one phase; a large PR at the end	More branches + merge overhead; overkill solo

   • ✅ You can state the trade-off in one sentence (simplicity vs per-phase reviewability).

2. Apply the decision matrix.

   Scenario	Recommended
   Solo developer / small team (2–3)	Option A
   Quick MVP launch	Option A
   First time running this playbook	Option A
   Large team (4+) with strict PR review	Option B
   Enterprise / compliance needs PRs	Option B

   • ✅ Your scenario maps to a recommended option. For most CodeCanyon work, Option A wins — the playbook is already a phase-by-phase sequence.

3. Record the choice (and reason) in Zaj-PROJECT.md so later phases — and teammates — follow the same model.

   • ✅ Zaj-PROJECT.md names the chosen option and why.

2. Understand the branch model

Option A: the import lands on develop, the immutable author/vX.X.X anchors the vendor, and a long-lived Setup/Initial-Launch carries one commit per phase.

%%{init: {'gitGraph': {'mainBranchName': 'develop'}}}%%
gitGraph
  commit id: "import vendor"
  branch "author/vX.X.X"
  checkout develop
  checkout "author/vX.X.X"
  commit id: "frozen (never built on)" type: HIGHLIGHT
  checkout develop
  branch "Setup/Initial-Launch"
  checkout "Setup/Initial-Launch"
  commit id: "Code & repo"
  commit id: "Local dev"
  commit id: "Deploy pipeline …"

One commit per playbook section keeps history self-documenting — Code & repo complete, Local development complete, and so on. When every section is done, merge the working branch back: git checkout develop && git merge Setup/Initial-Launch && git push origin develop.

3. Know when the branches are created

Branch creation happens after the repo exists — don’t run anything yet:

• develop is wired at git init / rename time (git branch -M develop) — see Initialize the repository (or the bootstrap path on Create the project if you started there).
• author/vX.X.X + the author-vX.X.X tag are created from the pristine import commit — see Create the project · pristine baseline. They are diff anchors only — never checked out or built on.
• Setup/Initial-Launch (Option A) or a Setup/Phase-N-* branch (Option B) is cut off develop at Commit & freeze — the branch Code & repository setup and later sections commit on.

For Option B, only this last point differs: you create a fresh Setup/Phase-N-Name branch per phase, complete the work, then merge it to develop via PR before starting the next. The author freeze and the gate are identical.

Option B — CLI appendix

Run this only when you chose Option B in §1. Phase 1 may already have created develop — these commands are idempotent checks, not blind re-init.

git branch -a | grep develop || { git checkout main && git checkout -b develop; }
git checkout develop
git pull origin develop 2>/dev/null || true
git checkout -b "Setup/Phase-2-Code-Repo"
# Expected: git branch --show-current → Setup/Phase-2-Code-Repo

Branch naming for later phases: Setup/Phase-3-Local-Dev, Setup/Phase-4-Deploy-Pipeline, etc. After each phase: open a PR to develop, merge, then cut the next branch from updated develop.

• ✅ Option B teams know the per-phase branch name pattern and merge-before-next-phase rule.

4. Confirm the wider project strategy

The branch model is one of five setup decisions later playbook sections assume you’ve already made. Settle the other four now and record all five in Zaj-PROJECT.md (with legacy read-back from Admin-Local/1-Project/1-Info/ProjectStrategy.md if an older project already has it) so Local development and Deploy pipeline aren’t guessing:

Decision	Pick (recommended in bold)	Why it matters later
Build strategy	Build locally vs build on the server	Drives the .gitignore (is /vendor, /public/build tracked?) and what the deploy step builds — see Initialize the repository §4 for the /public/build grep check. Local development and Deploy pipeline assume this choice.
Repository architecture	Single repo vs two-repo (vendor + app)	Whether vendor + your code share history; affects vendor-update merges (Workflow 4).
Deployment pipeline	develop → <non-production env key(s)> → production → main (staging-primary is the simple example)	The promotion path every deploy follows, including projects with qa, uat, client-demo, or more than one non-production target.
Deployment tool	Deployer vs GitHub Actions vs manual SSH	What Deploy pipeline configures — pick before you build the pipeline.
Branch model	Option A or B (above)	How history is shaped.

• ✅ Zaj-PROJECT.md records all five choices with a one-line reason each, so Local development and Deploy pipeline read it instead of re-deciding.

Staging-first is non-negotiable

Whatever you pick, production is never deployed before a non-production target is verified. Deploy to the selected non-production target gates Production deploy — that ordering is a safety rule, not a preference.

Checklist

Do not mark this step done until every box below is checked.

• 👤 Model chosen — Option A or B picked, and any team agrees.
• 👤 Choice recorded — the option and its reason are in Zaj-PROJECT.md.
• 👤 Project strategy recorded — build strategy, repo architecture, deploy pipeline, deploy tool, and branch model all in Zaj-PROJECT.md.
• 🔀 Model understood — you know develop is created at init and the working branch after the first commit.

→Next step

Extract & snapshot the vendor