مأموریت: دو تغییر، یک شاخهٔ اصلیMission: two changes, one main branch

آلیس و باب دو قابلیت جدا می‌سازند، اما هر دو به یک تنظیم مشترک دست می‌زنند. یکی زودتر وارد main می‌شود و دیگری عقب می‌افتد. مأموریت این نیست که هر طور شده merge سبز شود؛ باید نشان بدهی هیچ کار هم‌تیمی گم نشده و تصمیم ادغام قابل‌ردگیری است.

In the previous project, you prepared local history for review. Now a small team asks you to make its collaboration work: main should stay dependable, Alice adds CSV, Bob adds JSON, and both edit the same configuration file to enable their new format.

آلیس زودتر شاخه خودش را push می‌کند و یک PR باز می‌کند. باب هم تغییرش را push می‌کند. بعد از بازبینی، تغییر باب زودتر وارد main می‌شود. وقتی آلیس می‌خواهد کارش را به‌روز کند، شاخه او از main عقب است و هر دو تغییر روی یک خط تنظیمات دست گذاشته‌اند.

Alice pushes her branch and opens a PR first. Bob pushes his work too. After review, Bob’s change reaches main first. When Alice updates her work, her branch is behind main, and both changes touched the same configuration line.

کار تو این نیست که هر طور شده merge سبز بگیری. باید ببینی چه کسی چه چیزی دارد، از کجا عقب افتاده‌ایم، تعارض را با حفظ هر دو قابلیت حل کنیم، آزمون بگیریم و تاریخچه را مطابق سیاستی که خود تیم انتخاب کرده تحویل بدهیم.

Your job is not to make the merge button turn green at any cost. Find out who has what, identify where the branches diverged, resolve the conflict while preserving both features, test, and hand off a graph that matches the team’s chosen policy.

شروع کوچک: برنامه‌ای که قالب‌هایش زیاد می‌شودA small starter: an app that gains export formats

نیازی به نصب package نداریم؛ Node.js و آزمون داخلی node:test کافی است. کار برنامه هم محدود است: فهرست قالب‌های فعال را از تنظیمات می‌خواند و برای هر قالب یک تابع خروجی دارد. این سادگی کمک می‌کند توجه‌مان روی کار تیمی بماند.

No package installation is needed; Node.js and its built-in node:test runner are enough. The application has a narrow job: read enabled formats from configuration and provide an exporter for each one. Keeping it small lets us focus on collaboration.

// package.json
{
  "name": "team-export",
  "private": true,
  "scripts": { "test": "node --test" }
}

// config/formats.json
{
  "enabled": ["text"]
}

// src/registry.js
const { enabled } = require("../config/formats.json");

function assertEnabled(format) {
  if (!enabled.includes(format)) {
    throw new Error(`Format is not enabled: ${format}`);
  }
}

module.exports = { enabled, assertEnabled };

// src/formats/text.js
const { assertEnabled } = require("../registry");

function text(rows) {
  assertEnabled("text");
  return rows.map((row) => `${row.name}: ${row.count}`).join("\n");
}

module.exports = { text };

// test/baseline.test.js
const test = require("node:test");
const assert = require("node:assert/strict");
const { enabled } = require("../src/registry");
const { text } = require("../src/formats/text");

test("the baseline keeps text export enabled", () => {
  assert.ok(enabled.includes("text"));
  assert.equal(text([{ name: "tea", count: 2 }]), "tea: 2");
});

فایل‌ها را در seed/ بساز و از همان‌جا node --test را اجرا کن. باید یک آزمون موفق ببینی. فقط بعد از این خط مبنا، مخزن را بساز؛ اگر آزمون از ابتدا قرمز باشد، نمی‌فهمیم تعارض بعدی علتش بوده یا برنامهٔ پایه.

Create these files in seed/ and run node --test there. You should see one passing test. Create the repository only after this baseline is green; otherwise a later conflict could be blamed for a problem that was already present.

محیط تیم: یک مخزن راه دور، دو cloneTeam environment: one remote, two clones

برای بخش اصلی لازم نیست حساب GitHub یا GitLab داشته باشی. یک bare مخزن روی دیسک نقش مخزن راه دور را دارد و دو clone جدا نقش آلیس و باب را. این محیط برای دیدن اشاره‌گرها، push، fetch، تعارض و merge واقعی است؛ اما خودش PR، بازبینی تأیید، CI یا قانون محافظت از main ایجاد نمی‌کند.

The core project does not require a GitHub or GitLab account. A bare repository on disk acts as the remote, and two separate clones act as Alice and Bob. This is enough to observe refs, pushes, fetches, conflicts, and real merges—but it does not create PRs, review approvals, CI, or branch-protection rules for main.

همهٔ دستورهای مسیر محلی در یک ترمینال Bash مانند Git Bash یا WSL نوشته شده‌اند؛ مسیرهای ساخت پوشه را از workspace موقت خودت آغاز کن. فایل‌های starter را با ویرایشگر بساز. پوشه‌های seed، team.git، alice، bob و handoff کنار هم خواهند بود.

Local-route commands use a Bash-compatible terminal such as Git Bash or WSL; start from a disposable workspace. Create starter files with your editor. The seed, team.git, alice, bob, and handoff directories will sit side by side.

cd /path/to/disposable/team-project
cd seed
git init -b main
git config user.name "Seed Maintainer"
git config user.email "seed@example.invalid"
git add package.json config src test
git commit -m "feat: add text export baseline"
node --test
cd ..
git clone --bare seed team.git
git clone team.git alice
git clone team.git bob
git -C alice config user.name "Alice"
git -C alice config user.email "alice@example.invalid"
git -C bob config user.name "Bob"
git -C bob config user.email "bob@example.invalid"

اگر Git قدیمی‌تر از نسخه‌ای است که git init -b را می‌شناسد، git init بزن و بعد git branch -M main. حالا از هر دو clone آزمون خط مبنا را اجرا و git remote -v را ببین: هر دو باید مخزن راه دور محلی team.git را نشان دهند. ایمیل‌های .invalid نمونه‌اند و ایمیل واقعی کسی نیستند.

If your Git predates git init -b, run git init and then git branch -M main. Run the baseline test from both clones and inspect git remote -v; each should point to the local team.git. The .invalid email addresses are examples, not real people’s addresses.

قیدها و سیاست تیمConstraints and team policy

این انتخاب قانون همیشگی نیست. merge commit در این مأموریت کمک می‌کند مسیر هر قابلیت را بعد از ادغام ببینی. تیمی دیگر ممکن است squash را برای یک commit نهایی به‌ازای هر PR بخواهد یا rebase را برای تاریخچهٔ خطی انتخاب کند. روش‌های قابل انتخاب در GitHub هم تابع تنظیمات همان مخزن‌اند؛ merge محلی به‌تنهایی سیاست میزبان را فعال نمی‌کند.

This is not a universal rule. A merge commit helps this mission retain each feature’s path after integration. Another team might prefer squash for one final commit per PR, or rebase for a linear history. GitHub’s available methods depend on repository settings; a local merge does not enable host policy.

مسیر کار: از دو شاخه تا یک تحویلWork plan: from two branches to one handoff

۱ — خط پایه را در هر دو clone ثابت کن1 — Establish the baseline in both clones

هر مرحله باید یک وضعیت قابل‌اثبات داشته باشد: دو clone از یک پایه، دو شاخه مستقل، یک push جلوتر، یک بازبینی، یک ادغام آگاهانه و در پایان یک main مشترک که هر دو نفر به همان شناسه می‌رسند.

Tests should pass in both alice/ and bob/, with no working changes in status. Record the baseline commit ID. git rev-parse main should match in both clones.

۲ — آلیس قابلیت را push و PR را آماده می‌کند2 — Alice pushes a feature and prepares its PR

آلیس شاخه کوتاه‌عمر feature/alice-csv می‌سازد، CSV و آزمون ساده‌اش را اضافه می‌کند و مقدار csv را به آرایهٔ مشترک config/formats.json می‌افزاید. commit روشن feat: add CSV export بسازد، آزمون بگیرد و شاخه را با upstream push کند.

Alice creates short-lived feature/alice-csv, adds CSV support and a simple test, and appends csv to shared config/formats.json. She makes a clear feat: add CSV export commit, tests, and pushes with an upstream.

پروندهٔ PR را با پنج بخش بنویس: مشکل، راه‌حل، محدوده، آزمون‌های اجراشده و محدودیت شناخته‌شده. عمداً در نسخهٔ اول، comma و quote داخل مقدار CSV را escape نکن؛ آزمون ساده فعلاً سبز است. بازبین باید این نقص را پیدا کند.

Write the PR brief with five parts: problem, approach, scope, tests run, and known limitation. Deliberately leave commas and quotes inside CSV values unescaped in version one; the simple test still passes. The reviewer should catch the gap.

۳ — باب هم‌زمان JSON را جلو می‌برد3 — Bob independently advances JSON

باب از همان خط پایه شاخه feature/bob-json می‌سازد، خروجی JSON و آزمونش را اضافه می‌کند و همان config/formats.json را تغییر می‌دهد تا json هم فعال باشد. شاخه را push کند؛ هنوز کار آلیس را در clone خودش ندارد. دو clone یعنی دو واقعیت محلی متفاوت.

Bob branches from the same baseline as feature/bob-json, adds JSON output and its test, and edits the same config to enable json. He pushes; Alice’s work is not in his clone yet. Two clones mean two different local realities.

۴ — تغییر باب وارد main می‌شود؛ آلیس عقب می‌افتد4 — Bob’s change reaches main; Alice falls behind

در مسیر bare، پروندهٔ بازبینی باب را با آزمون و نظر قابل پاسخ کامل کن؛ سپس نقش maintainer را بازی کن و تغییر باب را با merge commit به main وارد و push کن. این نقش میزبان را شبیه‌سازی می‌کند؛ bare مخزن خودش PR یا مجوز push را enforce نمی‌کند.

On the bare route, complete Bob’s review record with a test and actionable comment, then act as maintainer: merge Bob into main with a merge commit and push. This simulates the host’s decision; bare Git does not enforce PRs or push permissions.

حالا از شاخه آلیس fetch کن و قبل از ادغام، گراف همهٔ اشاره‌گرها را بخوان. origin/main جلوتر است و شاخه آلیس هنوز آن commit را ندارد. در تنظیمات تعارض خواهی دید؛ هر دو قابلیت را نگه دار و آزمون CSV و JSON را اجرا کن. قبل از حل، حدس بزن کدام خط تعارض می‌کند.

Fetch from Alice’s branch and inspect the all-refs graph before integrating. origin/main is ahead, and Alice’s branch lacks that commit. Config will conflict; preserve both features and test CSV and JSON. Predict which line conflicts before resolving.

۵ — بازبینی را به اصلاح قابل آزمون تبدیل کن5 — Turn review feedback into a tested fix

بازبین یک نظر correctness می‌گذارد: مقدار دارای comma، quote یا newline باید طبق قرارداد CSV encode شود. نظر دوم می‌پرسد اگر قالب فعال نباشد یا ورودی خالی باشد رفتار چیست، و چرا تنظیم فعال‌بودن بیرون از exporter است. این فقط سلیقه نیست؛ قرارداد را در README و آزمون روشن کن.

The reviewer leaves a correctness comment: CSV values containing commas, quotes, or newlines must be encoded correctly. A second asks what happens when the format is disabled or input is empty, and why enablement lives outside the exporter. This is more than taste; clarify the contract in docs and tests.

آلیس quoteهای داخلی را دوبرابر و سلول‌های دارای comma، quote یا newline را quote می‌کند؛ آزمون می‌نویسد و رفتار ورودی خالی را مشخص می‌کند. نظر دوم را با توضیح یا تغییر مستند پاسخ می‌دهد. بازخورد را در commit جدا مثل fix: escape CSV fields ثبت و شاخه را عادی push می‌کند. اگر سیاست میزبان تأیید قبلی را stale کند، بازبین نسخهٔ تازه را دوباره می‌بیند.

Alice doubles embedded quotes, quotes cells containing commas, quotes, or newlines, adds tests, and defines empty-input behavior. She answers the second comment with a documentation change or explanation. She records the follow-up in a separate commit such as fix: escape CSV fields and pushes normally. If host policy marks approval stale, the reviewer checks the new version.

۶ — ادغام، پاک‌سازی و همگام‌سازی باب6 — Merge, clean up, and synchronize Bob

بعد از حل تعارض و بازبینی، push را عادی انجام بده؛ اگر رد شد fetch و گراف را دوباره ببین. maintainer تغییر آلیس را با merge commit وارد main می‌کند. شاخه‌ها را فقط بعد از اثبات ادغام پاک کن؛ Bob fetch می‌کند، main خودش را fast-forward می‌کند و همان آزمون را اجرا می‌کند.

After conflict resolution and review, push normally; if rejected, fetch and inspect the graph again. The maintainer integrates Alice with a merge commit. Delete branches only after proving they were merged; Bob fetches, fast-forwards his main, and runs the same tests.

PR باید سؤال روشنی برای بازبین بسازدA PR should give reviewers a clear question

در مسیر local-bare، خود Git چیزی به اسم PR ندارد؛ برای اینکه بازبینی را فقط در ذهن اجرا نکنی، دو پرونده در handoff/ بیرون از cloneها نگه دار: alice-pr.md و review-log.md. این یادداشت‌ها جای مخزن راه دور یا commit نیستند؛ تصمیم‌های میزبان را در محیطی ثبت می‌کنند که میزبان واقعی ندارد.

In the local bare route, Git has no PR object. To make review observable rather than imaginary, keep alice-pr.md and review-log.md in handoff/, outside the clones. These notes are not a remote or commits; they record host decisions in an environment without a host.

در GitHub، نظر inline، وضعیت بازبینی و بررسی کنار PR ثبت می‌شوند؛ در bare route آن‌ها را در بازبینی-log با نام بازبین، commit بررسی‌شده، نظرها، پاسخ آلیس و آزمون یادداشت کن. “Request changes” به‌تنهایی همیشه قفل فنی نیست؛ اگر حفاظت شاخه/ruleset آن را الزام نکرده باشد، ممکن است maintainer بتواند merge کند. ظاهر بازبینی را با سیاست enforceشده یکی نگیر.

On GitHub, inline comments, review state, and checks attach to the PR; in the bare route, record reviewer, reviewed commit, comments, Alice’s response, and test result. “Request changes” is not always a technical lock: without an enforcing branch protection rule or ruleset, a maintainer may still merge. Do not confuse review status with enforced policy.

گیرهای تمرین: قبل از واکنش، شاهد جمع کنProject snags: collect evidence before reacting

معیار تحویل: هر دو نفر به یک نتیجه برسندAcceptance: both people reach the same result

پروژه وقتی تمام نیست که «push موفق شد». باید هر دو clone به یک main برسند، هر دو قابلیت باقی مانده باشند، تست رد نشود و گراف نهایی با سیاست ادغامی که اول انتخاب کردی جور باشد. نتیجه و داستان تاریخچه هر دو بخشی از تحویل‌اند.

Run these checks in both clones. The important criterion is the same final commit ID on main, not merely matching branch names.

node --test
git status --short --branch
git fetch --prune origin
git log --oneline --graph --decorate --all
git rev-parse main
git rev-parse origin/main
git diff --check origin/main
git grep -n -E '^(<<<<<<<|=======|>>>>>>>)' main --
git branch -vv
git branch -r

قبولی یعنی هر دو exporter آزمون را می‌گذرانند؛ تنظیمات هر سه فرمت را فعال می‌کند؛ فرمان جست‌وجوی نشانگر در main خروجی ندارد (کد خروجی ۱ اینجا یعنی موردی پیدا نشده)؛ وضعیت ردیابی‌شده تمیز است؛ شناسهٔ main و origin/main در هر clone برابرند و مقدار main در clone آلیس و باب هم یکی است؛ شاخه‌های قابلیت حذف شده‌اند؛ و گراف merge commitهای سیاست را نشان می‌دهد. node --test را اینجا خودت اجرا می‌کنی؛ این کار به‌تنهایی CI نیست. در مسیر میزبانی‌شده، بررسی فقط وقتی جلوی merge را می‌گیرد که تنظیمات مخزن آن را لازم کرده باشد.

Pass means both exporters pass; config enables all three formats; the marker search on main prints nothing (exit code 1 means no match here); tracked status is clean; local main equals origin/main in each clone and both clones agree; feature branches are deleted; and the graph shows the policy’s merge commits. You run node --test locally; that alone is not CI. On a hosted route, a check blocks merging only if repository rules require it.

در bare route، گراف و شناسه‌ها را ثابت می‌کنی؛ handoff فقط بازبینی را شبیه‌سازی می‌کند. در GitHub واقعی، وضعیت PR، بازبینی ثبت‌شده و بررسیهای میزبان را هم نگه دار. هیچ‌کدام تضمین نمی‌کند تیم در آینده همیشه سیاست را رعایت کند.

With bare Git, you prove graph and commit IDs; handoff only simulates review. In GitHub, retain PR state, submitted reviews, and host checks too. None of this guarantees the team will always follow policy later.

اگر گیر کردی، پله‌پله جلو بروIf you get stuck, take hints one at a time

راه‌حل مرجع، بعد از انجام مأموریتReference solution, after attempting the mission

راه‌حل دو لایه دارد: A) Git خالص با bare مخزن راه دور و دو clone؛ B) مسیر PR میزبانی‌شده. لازم نیست فرمان‌ها را از حفظ بگویی؛ باید گراف، آزمون و تصمیم بازبینی را توضیح بدهی.

The reference has two layers: A) pure Git with a bare remote and two clones; B) a hosted PR path. You do not need to memorize commands; explain the graph, tests, and review decisions.

# Alice clone
cd ../alice
git switch -c feature/alice-csv
# create src/formats/csv.js and test/csv.test.js; append csv to config
node --test
git diff --check
git add config/formats.json src/formats/csv.js test/csv.test.js
git diff --cached
git commit -m "feat: add CSV export"
git push -u origin feature/alice-csv

# Bob clone, independently from baseline main
cd ../bob
git switch -c feature/bob-json
# create src/formats/json.js and test/json.test.js; append json to config
node --test
git diff --check
git add config/formats.json src/formats/json.js test/json.test.js
git diff --cached
git commit -m "feat: add JSON export"
git push -u origin feature/bob-json

// src/formats/csv.js
const { assertEnabled } = require("../registry");

function cell(value) {
  const raw = String(value);
  if (/[",\r\n]/.test(raw)) {
    return `"${raw.replaceAll('"', '""')}"`;
  }
  return raw;
}

function csv(rows) {
  assertEnabled("csv");
  const records = rows.map((row) => `${cell(row.name)},${cell(row.count)}`);
  return ["name,count", ...records].join("\n");
}

module.exports = { csv };

// src/formats/json.js
const { assertEnabled } = require("../registry");

function json(rows) {
  assertEnabled("json");
  return JSON.stringify(rows, null, 2);
}

module.exports = { json };

<<<<<<< HEAD
  "enabled": ["text", "csv"]
=======
  "enabled": ["text", "json"]
>>>>>>> origin/main

# Alice clone: integrate Bob's approved branch as maintainer
git switch main
git fetch origin
git merge --ff-only origin/main
git merge --no-ff origin/feature/bob-json -m "merge: integrate Bob JSON export"
node --test
git push origin main

# Alice: return to her feature and inspect the new remote tip
git switch feature/alice-csv
git fetch origin
git log --oneline --graph --decorate --all
git merge origin/main
# resolve config/formats.json, test, then complete the merge
node --test
git diff --check
git add config/formats.json
git commit -m "merge: sync CSV branch with main"

# after review fixes and tests
node --test
git push

git fetch --prune origin
git switch main
git merge --ff-only origin/main
node --test
git rev-parse main
git rev-parse origin/main

# after both PRs have been integrated
git push origin --delete feature/alice-csv feature/bob-json
git fetch --prune origin
git branch -d feature/bob-json

بازنگری و تحویل به تیمReflection and team handoff

قبل از بستن پروژه، یک بار از دید هم‌تیمی‌ات نگاه کن: کدام اطلاعات را Git به تو داد و کدام را سرویس میزبانی؟ کجا ممکن بود کار نفر دیگر را بازنویسی کنی؟ و چه شاهدی ثابت کرد هر دو تغییر سالم به main رسیده‌اند؟

Answer these by pointing to your graph or artifacts; “everything synced” alone is not evidence.

• کدام بخش را Git ذخیره کرد و کدام فقط در میزبان PR ثبت شد؟Which parts did Git store, and which existed only in the PR host?
• اگر push باب اول رد می‌شد، قبل از ادغام چه چیزی را fetch و بررسی می‌کردی؟If Bob’s push were rejected first, what would you fetch and inspect before integrating?
• چه مدرکی نشان می‌دهد هر دو قابلیت مانده و هر دو clone به یک main رسیده‌اند؟What proves both features survived and both clones reached the same main?
• کدام عمل می‌توانست کار منتشرشدهٔ هم‌تیمی را بازنویسی کند و چرا لازم نبود؟Which action could rewrite a teammate’s published work, and why was it unnecessary?

گزارش handoff شامل گراف نهایی، شناسهٔ یکسان main، خروجی آزمون در هر دو clone، تنظیمات نهایی، پاسخ بازبینیها و اشاره‌گرهای پاک‌شده است. فقط از مدرکی حرف بزن که واقعاً جمع کرده‌ای؛ bare مخزن راه دور ثابت نمی‌کند PR یا CI واقعی اجرا شده است.

The handoff includes the final graph, matching main IDs, test output from both clones, final config, review responses, and deleted refs. Report only evidence you collected; a bare remote cannot prove a real PR or CI run.

پروژهٔ آخر: این بار مخزن از قبل خراب استFinal project: this time, the repository is already broken

پروژهٔ آخر دیگر از یک مخزن مرتب شروع نمی‌شود. وقتی آن را تحویل می‌گیری، چند چیز از قبل خراب شده و اولین مهارتت این است که قبل از تعمیر، چیزی را بدتر نکنی.

Here the baseline was stable and we resolved conflict before work disappeared. Sometimes you join after a bad push, deleted branch, or missing working-tree file. Project 3 removes the rails: the repository is already broken, and you must rescue it with evidence rather than guesses.

مراجع رسمی برای مسیر میزبانOfficial references for the hosted route

این پیوندها رفتار GitHub را توضیح می‌دهند؛ برای میزبان دیگر، راهنمای رسمی همان سرویس را بخوان.

These links describe GitHub behavior; consult the relevant host’s official docs for another service.

• Reviewing proposed changes in a pull request
• About protected branches
• Keeping a pull request in sync with the base branch
• Pull request merge methods