Skip to content

scripts_engine_mandate_in_one_document.md

Latest commit

 

History

History
113 lines (88 loc) · 5.88 KB

scripts_engine_mandate_in_one_document.md

File metadata and controls

113 lines (88 loc) · 5.88 KB
Raw

Here’s a clear, logical map of how branches and the flow actually work, matched as closely as possible to the three-stage process you described.

Core idea of branches

A branch is just a movable pointer to a series of commits.

  • main (or master) is simply the conventional name for the primary branch. It is not special in the Git software itself — teams decide what it means.
  • You can create as many other branches as you like (dev, staging, prod, feature/xyz, hotfix/123, etc.).
  • Each branch can live on your local machine and on the remote (GitHub). They stay independent until someone deliberately merges them.

Your desired three-stage workflow (mapped to real Git practice)

You want this sequence:

  1. Local / team development work → changes stay isolated
  2. Integration / work branch → changes are reviewed, tested, and consolidated
  3. Production / release branch → only fully approved code goes here and triggers deployment

Here is the cleanest way to implement that:

Stage Typical branch name(s) What happens here Who can merge into it What “moves” the code
1. Development feature/*, dev, or personal branches You and teammates write code, commit, push freely Anyone with write access can push git push
2. Integration / Testing main (or develop / staging) Pull Requests are reviewed, tests run, conflicts fixed Only authorized people (or protected branch rules) Pull Request + merge
3. Production / Release prod / release / main (if you use a single main) Final verified code; deployment scripts watch this branch Very few people (or only CI) Pull Request or automated promotion

Recommended practical setup for your case

Option A – Simple & common (recommended for most teams)

feature branches  →  main  →  production (or release)
  • Developers create short-lived branches from main (or from dev).
  • They push their branch and open a Pull Request (PR) into main.
  • Authorized reviewers approve → merge into main.
  • After tests pass on main, another PR (or automated process) promotes the code into a prod / release branch.
  • Your server watches the prod branch and deploys when it changes.

Option B – Classic Git-Flow style

feature/*  →  develop  →  release/*  →  main (production)
  • develop = your “work / integration” branch
  • main = production
  • release/* branches are temporary stabilisation branches

How the important Git terms actually work in this flow

Term What it really does When you use it in your 3-stage flow
clone Downloads the entire remote repository to your machine for the first time Once, when you start working on a project
commit Saves a snapshot of your changes on your current branch (still only local until you push) Continuously while developing
push Uploads your local commits to the matching branch on the remote After you finish a piece of work on a feature branch
pull Fetches remote changes and merges them into your current local branch Before you start new work, or to stay up-to-date
fetch Downloads remote changes but does not merge them yet Safer alternative to pull when you want to inspect first
branch Creates a new pointer so you can work without touching other people’s code At the start of every feature or fix
merge Combines the history of one branch into another Usually done via a Pull Request (not by hand)
Pull Request (PR) A formal request on GitHub: “Please review and merge my branch into this other branch” The only way code should move from stage 1 → stage 2, and stage 2 → stage 3
protected branch GitHub setting that blocks direct pushes and requires PRs + reviews + tests Put this on main and especially on prod

Concrete day-to-day sequence that matches your description

  1. Start work (Stage 1)

    git checkout main
git pull                    # get latest
git checkout -b feature/my-change
# write code, commit, push
git push -u origin feature/my-change

  2. Move to integration (Stage 2)

    • Open a Pull Request on GitHub: feature/my-change → main
    • Reviewers approve, CI tests run
    • Authorized person clicks Merge
      → Code is now on the work/integration branch (main)

  3. Move to production (Stage 3)

    • Open another PR: main → prod (or use an automated promotion)
    • Extra checks / approvals
    • Merge
      → Server detects the change on prod and runs your deploy scripts

Key rules that make the “authorized merge” part work

  • Protect the important branches (main and prod) in GitHub settings:
    • Require Pull Request reviews
    • Require status checks (tests) to pass
    • Restrict who can push / merge
  • Never let people push directly to main or prod.
  • Feature branches can be pushed freely; only the merge into the protected branches needs authorization.

Visual summary of the flow you described

Local machine                  Remote GitHub
─────────────                  ─────────────
feature/xyz  ──push──►  feature/xyz
                            │
                            │  Pull Request + Review + Tests
                            ▼
                         main  (integration / work branch)
                            │
                            │  Pull Request (or auto-promote)
                            ▼
                         prod  (final release branch)
                            │
                            └──► Server watches this → builds & deploys