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.

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 the project log. 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 the project log so later phases — and teammates — follow the same model.

   • ✅ The project log 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.

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 Admin-Local/1-Project/1-ProjectInfo/ProjectStrategy.md (a one-screen file every later section reads) 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 — Local development and Deploy pipeline assume this.
Repository architecture	Single repo vs two-repo (vendor + app)	Whether vendor + your code share history; affects vendor-update merges (Workflow 4).
Deployment pipeline	develop → staging → production → main	The promotion path every deploy follows.
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.

• ✅ ProjectStrategy.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 staging is verified. Deploy to staging 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 the project log.
• 👤 Project strategy recorded — build strategy, repo architecture, deploy pipeline, deploy tool, and branch model all in ProjectStrategy.md.
• 🔀 Model understood — you know develop is created at init and the working branch after the first commit.

→Next step

Extract & snapshot the vendor