یک تغییر را چطور به همکارت نشان می‌دهی؟How do you present a change to a teammate?

در فصل ۱۳ دربارهٔ سیاست شاخه‌ها تصمیم گرفتیم؛ حالا یک شاخه آمادهٔ ادغام است و باید انسانی دیگر آن را بفهمد. دشواری PR اول اینجاست: بازبین باید حدس بزند کدام فایل مهم است، چرا قالب‌بندی عوض شده، تست‌ها کجا هستند و آیا فایل تولیدشده عمدی است یا تصادفی.

Chapter 13 helped us choose a branching policy. Now a branch is ready to integrate, and another person needs to understand it. The cost of the first PR becomes clear: the reviewer must guess which file matters, why formatting changed, where the tests are, and whether a generated file is intentional.

PR کوچک‌تر الزاماً درست‌تر نیست، اما معمولاً پرسش روشن‌تری می‌سازد: «این تغییر مشخص، مشکل مشخص را حل می‌کند؟» اگر refactor مکانیکی را از تغییر رفتار جدا کنی، بازبین می‌تواند اول شکل کد را بفهمد و بعد منطق تازه را بررسی کند. اگر جداسازی خودش معنای تغییر را پنهان می‌کند، آن را به قانون خشک تبدیل نکن؛ دلیل هر بخش را توضیح بده.

A smaller PR is not automatically more correct, but it usually asks a clearer question: “Does this specific change solve this specific problem?” Separating mechanical refactoring from behavior can let a reviewer understand the code shape first and then inspect the new logic. If separation would hide the meaning of the change, do not turn it into a rigid rule; explain why the pieces belong together.

یک مرز مهم: Git شاخه، commit و مخزن راه دور را می‌شناسد؛ PR یا MR چیزی نیست که به‌عنوان شیء داخل .git ذخیره شده باشد. میزبان گفتگو، بازبینی، بررسیهای CI، تأییدها و دکمه‌های merge را به آن تغییرها وصل می‌کند. Git می‌تواند شاخهها را جابه‌جا و ادغام کند حتی اگر هیچ PRای نداشته باشی؛ اما تاریخچهٔ گفت‌وگوی PR را Git محلی نگه نمی‌دارد.

An important boundary: Git knows branches, commits, and remotes; a PR or MR is not an object stored inside .git. The hosting platform attaches discussion, reviews, CI checks, approvals, and merge controls to those changes. Git can move and merge branches without any PR, but it does not store the PR conversation in your local repository.

commit خوب، بررسی را به قدم‌های قابل‌فهم تقسیم می‌کندGood commits break review into understandable steps

بازبین diff را می‌بیند، اما commitهای شاخه می‌توانند مسیر رسیدن به diff را هم روشن کنند. commit اتمی یک تغییر کوچک و منسجم را ثبت می‌کند؛ یعنی بعداً می‌توانی همان بخش را بفهمی یا جداگانه برگردانی. اتمی یعنی یک دلیل روشن برای تغییر، نه الزاماً یک خط کد.

A reviewer sees the diff, but the branch's commits can also explain how it got there. An atomic commit records one small, coherent change, so later you can understand or revert that part separately. Atomic means one clear reason for the change, not necessarily one line of code.

پیام commit لازم نیست از یک الگوی جهانی پیروی کند. یک summary کوتاه بگوید چه تغییر معناداری رخ داده؛ اگر دلیل در diff معلوم نیست، بدنه توضیح دهد چرا تصمیم گرفته شد، چه گزینه‌ای کنار گذاشته شد و چه محدودیتی باقی است. Conventional Commits مثل feat: و fix: یک قرارداد اختیاری برای تیم یا ابزارهاست، نه قانونی که Git enforce کند.

Commit messages do not need a universal format. A short summary should name the meaningful change; if the reason is not obvious from the diff, the body can explain why the decision was made, which alternative was rejected, and what limitation remains. Conventional Commits labels such as feat: and fix: are an optional convention, not a rule enforced by Git.

اگر شاخه چند commit آزمایشی دارد، می‌توانی قبل از بازبینی نهایی آن‌ها را با fixup و interactive rebase مرتب کنی؛ فصل ۷ این ابزار را باز کرد. اما اگر همکار شاخه را گرفته یا سیاست تیم تاریخچهٔ بازبینی را حفظ می‌کند، بازنویسی commitهای منتشرشده شناسه‌ها و نظرهای inline را جابه‌جا می‌کند. قبل از squash یا rebase بپرس چه چیزی باید در تاریخچه بماند.

If a branch contains experimental commits, you may organize them with fixup and interactive rebase before final review; Chapter 7 covered that tool. But if a teammate already has the branch or team policy preserves review history, rewriting published commits changes IDs and can displace inline comments. Before squashing or rebasing, ask what the history should preserve.

توضیح PR، سؤال بازبین را قبل از حدس‌زدن جواب می‌دهدA PR description answers the reviewer's first questions

عنوان خوب شروع است، اما بازبین هنوز باید بداند چرا این تغییر لازم شد. توضیح PR نقشهٔ خواندن diff است، نه جای تکرار همهٔ commitها. اگر از او می‌خواهی دربارهٔ رفتار، خطر انتشار یا تصمیم معماری نظر بدهد، همان‌جا مشخصش کن.

A good title is a start, but the reviewer still needs to know why the change exists. A PR description is a map for reading the diff, not a repetition of every commit. If you want feedback on behavior, rollout risk, or an architectural decision, say so directly.

Issue را فقط اگر تیم از آن برای پیوند کار استفاده می‌کند وصل کن. تصویر یا log وقتی مفید است که رفتار دیداری یا خروجی را روشن کند؛ دادهٔ شخصی، token، رمز یا log حساس را در PR نگذار. برای migration یا انتشار پرخطر، یک بند کوتاه دربارهٔ برگشت یا پایش بعد از انتشار اضافه کن.

Link an issue if the team uses it to connect work. Add a screenshot or log only when it clarifies visual behavior or output; never include personal data, tokens, passwords, or sensitive logs. For risky migrations or rollouts, add a short note about rollback or post-release monitoring.

بازبینی، پیدا کردن عیب است؛ مسابقهٔ سلیقه نیستReview is about finding risk, not winning a style contest

بازبین از عنوان و توضیح شروع می‌کند، بعد diff را می‌خواند و می‌پرسد: «آیا این کد مسئلهٔ تعریف‌شده را درست حل می‌کند؟» اگر نیت معلوم نباشد، بازبینی خط‌به‌خط هم ممکن است به نکته‌های کم‌اهمیت بچسبد و خطر اصلی را جا بیندازد.

A reviewer starts with the title and description, then reads the diff and asks: “Does this code correctly solve the stated problem?” Without clear intent, even a line-by-line review can focus on minor details and miss the actual risk.

بازبینی را از منظور، correctness، آزمون، نگه‌داری و در جای لازم امنیت شروع کن. سؤال، درخواست تغییر و پیشنهاد سلیقه‌ای را از هم جدا کن. در GitHub می‌توانی نظر کلی یا inline بگذاری، پیشنهاد تغییر بسازی و در پایان Comment، Approve یا Request changes ثبت کنی. اینکه Request changes merge را مسدود کند به ruleهای مخزن بستگی دارد.

Start review with intent, correctness, tests, maintainability, and security where relevant. Distinguish a question, a required change, and a stylistic suggestion. On GitHub, you can leave general or inline comments, suggest an edit, and submit Comment, Approve, or Request changes. Whether Request changes blocks merging depends on repository rules.

درخواست تغییر را بی‌توضیح رها نکن: بگو چه رفتاری نگران‌کننده است و چه مدرکی آن را برطرف می‌کند. نویسنده لازم نیست هر پیشنهاد سلیقه‌ای را بپذیرد؛ کافی است منظور را بفهمد، دلیل تصمیمش را محترمانه بنویسد و اگر لازم شد آن را با آزمون یا قرارداد پروژه مقایسه کند. بازبینی خوب می‌تواند با توافق بر «فعلاً همین، بعداً issue جدا» تمام شود.

Do not leave a change request unexplained: say what behavior worries you and what evidence would resolve it. An author need not accept every stylistic suggestion; they should understand it, explain their decision respectfully, and compare it with tests or project conventions where useful. A good review can end with agreement to handle a follow-up in a separate issue.

بعد از بازخورد، پاسخ را به commit و توضیح تبدیل کنTurn review feedback into a commit and an explanation

دو نظر روی PR رسید: «برای رشتهٔ فقط‌فاصله تست داریم؟» و «اگر ورودی None باشد قرارداد تابع چیست؟» قبل از ویرایش، منظور سؤال دوم را روشن کن. آیا رفتار تازه لازم است یا بازبین می‌خواهد قرارداد موجود را واضح ببیند؟ هر نظر را با تغییر کد، آزمون یا پاسخ مستدل ببند.

Two comments arrive: “Do we test whitespace-only input?” and “What is the function contract if the input is None?” Before editing, clarify the second comment's intent. Is new behavior required, or does the reviewer want the existing contract made explicit? Resolve each comment with a code change, a test, or a reasoned answer.

برای نظر اول، تستی اضافه کن که " " را بررسی کند و مطمئن شو خروجی Guest است. برای دومی، اگر API فقط str می‌پذیرد، نوع hint و توضیح را روشن کن؛ اگر None از مسیر واقعی می‌رسد، آن را به قرارداد اضافه کن و آزمونش را بنویس. یکی را با «باید کار کند» جواب نده؛ قرارداد باید از کد و تست خوانده شود.

For the first comment, add a test for " " and verify that the result is Guest. For the second, clarify the type hint and docs if the API accepts only str; if None can arrive in the real path, add it to the contract and test it. Do not answer with “it should work”; make the contract visible in code and tests.

اگر شاخه فقط دست خودت است، یک follow-up commit معمولاً امن‌ترین پاسخ است: تاریخچهٔ بازبینی و مقایسهٔ قبل/بعد روشن می‌ماند. اگر سیاست تیم می‌گوید قبل از merge commitهای fixup را squash کن، هماهنگ شو. بعد از push همکار ممکن است شاخه را داشته باشد یا comment را روی commit مشخص گذاشته باشد؛ rebase شناسه‌ها را عوض می‌کند و نظرهای قدیمی را نیازمند بازبینی دوباره می‌سازد.

If the branch is yours alone, a follow-up commit is often the safest response: review history and before/after remain visible. If team policy says to squash fixups before merge, coordinate that. After a push, a teammate may have the branch or comments may refer to specific commits; rebasing changes IDs and can require old comments to be revisited.

سه روش merge، سه شکل تاریخچهThree merge methods, three history shapes

PR تأیید شده و بررسیها سبزند؛ هنوز باید بپرسیم کدام تاریخچه را می‌خواهیم. هیچ روش mergeای «بهترین» نیست: یکی رابطهٔ شاخه را ثبت می‌کند، یکی تغییرها را یک‌جا جمع می‌کند، دیگری commitها را جدا نگه می‌دارد اما روی خط پایه بازنویسی می‌کند.

The PR is approved and checks are green; we still need to ask what history we want. No merge method is universally best: one records the branch relationship, one combines its changes, and another keeps commits separate but replays them onto the base line.

در GitHub، روش‌های merge را مدیر مخزن می‌تواند روشن یا خاموش کند. طبق مستند فعلی، squash یک commit روی مقصد می‌سازد؛ Rebase and merge commitهای شاخه را جداگانه بدون merge commit اضافه می‌کند و SHA تازه می‌سازد. این گزینهٔ میزبان را عیناً با اجرای محلی git rebase یکی نگیر. اگر merge queue فعال باشد، خود queue هم می‌تواند روش ادغام را کنترل کند.

On GitHub, repository administrators can enable or disable merge methods. Its current documentation says squash creates one commit on the target, while Rebase and merge adds branch commits individually without a merge commit and creates new SHAs. Do not assume this host option is identical to running local git rebase. When a merge queue is active, the queue may also control the merge method.

CI و حفاظت شاخه، دروازه‌ای با شرط‌های مشخص‌اندCI and branch protection form a gate with explicit conditions

بازبین می‌گوید کد قابل‌فهم است، اما هنوز ممکن است تست، lint یا ساخت شکست بخورد. CI نتیجهٔ بررسیهای خودکار را کنار PR می‌آورد؛ حفاظت شاخه می‌تواند بعضی نتیجه‌ها و تعداد تأییدهای لازم را شرط merge کند. سبز بودن بررسی فقط همان بررسی تعریف‌شده را ثابت می‌کند.

A reviewer may find the code understandable while a test, lint, or build still fails. CI attaches automated check results to the PR; branch protection can make selected results and approvals merge conditions. A green check proves only what that configured check actually tests.

در GitHub، نتیجهٔ بازبینی و بررسیها در PR دیده می‌شود و حفاظت شاخه می‌تواند آن‌ها را الزام کند. تنظیم‌ها ممکن است به سطح دسترسی و قواعد همان مخزن وابسته باشند. یک PR سبز ثابت نمی‌کند منظور درست فهمیده شده، تست‌ها کافی‌اند یا انتشار موفق خواهد شد؛ بازبین و نویسنده باید این مرز را حفظ کنند.

On GitHub, review decisions and check results appear in the PR, and branch protection can require them. Settings may depend on repository permissions and rules. A green PR does not prove intent was understood, tests are sufficient, or deployment will succeed; authors and reviewers must keep that boundary clear.

وقتی PR گیر می‌کند، دنبال شاهد بگرد نه دکمهٔ سریعWhen a PR stalls, look for evidence—not a quick button

وقتی یک درخواست ادغام گیر می‌کند، سریع دنبال دکمهٔ merge یا push اجباری نرو. اول معلوم کن مشکل از چیست: شاخه عقب افتاده؟ تست شکست خورده؟ بازبین سؤال بی‌جواب دارد؟ یا تغییرها آن‌قدر قاطی‌اند که اصلاً نمی‌شود با اطمینان بررسی‌شان کرد؟

On GitHub, a new review may still be pending until submitted. If new commits are pushed to an approved PR and the repository dismisses stale approvals, the previous approval may become stale. Before requesting review again, inspect the review state and commit it covered; confirm exact behavior from repository settings and current host documentation.

پروژهٔ کوچک: یک PR آمادهٔ بازبینی کنMini-project: prepare a reviewable PR

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

We will build a small feature from two people's perspectives. If you have GitHub or GitLab access, use a disposable repository. Otherwise, create a bare remote and two clones, and simulate the PR and two comments in Markdown. This is not a real PR object or API; it lets you practice the diff, review exchange, and merge before using a host.

سناریو: تابع display_name نام را trim می‌کند و برای رشتهٔ خالی Guest برمی‌گرداند. سه commit جدا و قابل‌فهم بساز: پیاده‌سازی، تست‌ها و توضیح رفتار. قبل از push، خودت diff را مرور کن، test را اجرا کن و هر فایل خارج از محدوده را توضیح بده.

Scenario: a display_name function trims a name and returns Guest for a blank string. Create three separate, understandable commits: implementation, tests, and behavior documentation. Before pushing, self-review the diff, run the tests, and account for every file outside the intended scope.

در Git Bash، macOS یا Linux، این محیط ایزوله را بساز. پوشهٔ review-lab تازه است و فقط مخزن راه دور آزمایشی را در خودش دارد:

In Git Bash, macOS, or Linux, create this isolated environment. The new review-lab directory contains only the disposable test remote:

mkdir review-lab && cd review-lab
git init --bare --initial-branch=main team.git
git clone team.git author
cd author
git config user.name "Roya Author"
git config user.email roya@example.test

یک README.md ساده بساز، commit و push کن تا مبنای مشترک داشته باشیم. بعد clone بازبین را کنار clone نویسنده بساز؛ این دو پوشه working copy مستقل‌اند و شاخه نویسنده تا قبل از push به بازبین نمی‌رسد.

Create a simple README.md, commit and push it to establish a shared base. Then clone the reviewer copy beside the author's; these are independent working copies, and the author's branch will not reach the reviewer before it is pushed.

printf '# Display-name review lab\n' > README.md
git add README.md
git commit -m "docs: start display-name review lab"
git push -u origin main
cd ..
git clone team.git reviewer
cd author
git switch -c feature/trim-display-name

فایل app.py را با این رفتار کوچک بساز. فعلاً قرارداد ورودی str است؛ اگر محصول باید None را هم بپذیرد، آن نیاز را جدا به مسئله اضافه کن، نه اینکه بی‌صدا فرضش بگیری:

Create app.py with this small behavior. The input contract is str for now; if the product must accept None, add that requirement explicitly rather than silently assuming it:

def display_name(value: str) -> str:
    cleaned = value.strip()
    return cleaned or "Guest"

برای تست از کتابخانهٔ استاندارد Python استفاده کن تا وابستگی تازه‌ای لازم نباشد. هر commit یک علت روشن دارد:

Use Python's standard library for tests so no new dependency is needed. Each commit should have one clear reason:

import unittest
from app import display_name

class DisplayNameTests(unittest.TestCase):
    def test_trims_surrounding_spaces(self):
        self.assertEqual(display_name("  Mina  "), "Mina")

    def test_preserves_regular_name(self):
        self.assertEqual(display_name("Roya"), "Roya")

if __name__ == "__main__":
    unittest.main()

در README رفتار blank را هم توضیح بده. سپس سه commit بساز و هر بار فقط فایل همان مرحله را ناحیه‌ آماده‌سازی کن. دستورها را یکی‌یکی اجرا کن و قبل از commit سوم وضعیت و diff را بخوان:

Document blank-input behavior in the README. Then create three commits, staging only the file for each step. Run the commands one at a time and inspect status and diff before the third commit:

git add app.py
git commit -m "feat: trim display names and add blank fallback"
git add test_app.py
git commit -m "test: cover display-name behavior"
git add README.md
git commit -m "docs: explain display-name fallback"
python3 -m unittest
git diff --check main...HEAD
git diff --stat main...HEAD
git log --oneline --reverse main..HEAD

خروجی تست باید دو تست موفق را نشان دهد؛ git diff --check در موفقیت چیزی چاپ نمی‌کند؛ و log باید سه commit شاخه را نشان دهد. این شاهدها می‌گویند تست‌های موجود پاس شدند، whitespace مشکل‌دار در diff نیست و تاریخچه سه قدم دارد؛ ثابت نمی‌کنند PR در میزبان باز شده یا همهٔ نیازهای محصول پوشش دارند.

The test output should show two passing tests; git diff --check prints nothing on success; and the log should show three branch commits. This evidence says the existing tests passed, the diff has no whitespace errors, and the history has three steps. It does not prove a hosted PR exists or that every product requirement is covered.

شاخه را push کن تا بازبین بتواند آن را ببیند. اگر حساب میزبان داری، PR را با عنوان روشن و توضیح «مشکل، راه‌حل، محدودهٔ خارج از تغییر، تست و خطر» بساز و دو نظر پایین را ثبت کن. در مسیر محلی، فایل review.md را بیرون cloneها بساز تا وانمود نکنیم PR یک فایل Git است.

Push the branch so the reviewer can see it. If you use a host, open a PR with a clear title and a description covering problem, approach, out-of-scope behavior, tests, and risk; add the two comments below. For the local path, create review.md outside the clones so we do not pretend a PR is a Git file.

git push -u origin feature/trim-display-name
cd ..
git -C reviewer fetch origin
git -C reviewer diff --stat origin/main...origin/feature/trim-display-name
git -C reviewer diff origin/main...origin/feature/trim-display-name

بازبین دو نظر بدهد: «برای رشتهٔ فقط‌فاصله آزمون مستقلی داریم؟» و «ورودی None جزو قرارداد هست یا باید خطای نوع بگیریم؟» نظر اول باید به تغییر قابل‌آزمایش برسد؛ نظر دوم شاید با روشن‌کردن قرارداد جواب بگیرد و الزاماً تغییر رفتار نمی‌خواهد. نویسنده پاسخ را بیرون repo در review.md ثبت کند.

Have the reviewer leave two comments: “Do we have a dedicated test for whitespace-only input?” and “Is None part of the contract, or should this be a type error?” The first should lead to a testable change; the second may be resolved by clarifying the contract without changing behavior. Record the response outside the repository in review.md.

نظر اول را با تستی تازه پاسخ بده؛ پیش از تغییر، نتیجهٔ تست را ببین و بعد همان دستور را دوباره اجرا کن. برای نظر دوم، اگر قرارداد str است توضیح بده؛ اگر None از مسیر واقعی می‌رسد، قرارداد و آزمونش را تغییر بده. commit جدید را عادی push کن؛ اینجا شاخه خودت است و تاریخچه را بازنویسی نکرده‌ای.

Answer the first comment with a new test; observe the current test result before editing, then rerun the same command. For the second, explain the str contract; if None arrives in the real path, change and test the contract. Push a normal follow-up commit; this is your branch and you have not rewritten history.

cd author
# add a whitespace-only test to test_app.py, then:
python3 -m unittest
git add test_app.py
git commit -m "test: cover whitespace-only display names"
git push
git -C reviewer fetch origin
git -C reviewer log --oneline origin/main..origin/feature/trim-display-name
git -C reviewer diff origin/main...origin/feature/trim-display-name

بعد از دیدن بررسی سبز و بازبینی diff تازه، merge را طبق سیاست انتخاب کن. در مسیر محلی، این فقط merge شاخه در bare مخزن راه دور است؛ protection و تأیید واقعی میزبان وجود ندارند. برای merge commit، نویسنده در clone خودش main را به‌روز می‌کند، ادغام می‌کند و push می‌کند:

After reviewing the new diff and seeing checks pass, merge under team policy. In the local path this is only a branch merge against a bare remote; real host protection and approval rules are absent. For a merge commit, the author updates main in their clone, integrates, and pushes:

git switch main
git pull --ff-only origin main
git merge --no-ff feature/trim-display-name -m "merge: review display-name behavior"
python3 -m unittest
git log --graph --oneline --decorate --all
git push origin main
git -C ../reviewer fetch origin
git -C ../reviewer log --graph --oneline --decorate origin/main

تمرین‌ها: PR را از دید هر دو نفر ببینExercises: see the PR from both sides

تمرین‌ها را از هر دو طرف میز ببین. یک بار نویسنده‌ای که می‌خواهد تغییرش فهمیده شود و یک بار بازبینی که باید با زمان محدود مطمئن شود تغییر درست و قابل نگهداری است. خیلی از جواب‌های خوب این فصل دربارهٔ کم‌کردن ابهام‌اند، نه حفظ یک قالب ثابت.

For each case, give a decision and its reason; “this is good” is not enough. State what should change, what evidence would establish the result, and which risk remains.

تغییر بررسی‌پذیر آماده است؛ مخزن چه ابزارهای بیشتری می‌خواهد؟The change is reviewable; what more does the repository need?

حالا تغییرها نه فقط از نظر Git، بلکه برای آدم‌ها هم قابل بررسی شده‌اند. فصل بعد سراغ ابزارهایی می‌رود که برای شکل‌های خاص‌تر مخزن لازم می‌شوند؛ ابزارهایی که باید فقط وقتی مسئله‌شان را داری سراغشان بروی.

You can now distinguish a branch, PR, review, check, and merge. Some repositories outgrow one folder and one simple remote: concurrent working trees, dependencies on another repository, partial checkouts, or large files. The next chapter explores specialized Git tools for those cases without losing the underlying model.

مرور سریع این فصلQuick reference

رفتارهای GitHub در این فصل بر پایهٔ مستندات فعلی GitHub هستند؛ گزینه‌های موجود و الزام‌های merge را برای همان مخزن بررسی کن. آماده‌کردن تغییر برای بازبینی · نوع بازبینیها · روش‌های merge · حفاظت شاخه.

GitHub behavior here follows its current documentation; check available options and merge requirements for your repository. Making changes easier to review · Review types · Merge methods · Branch protection.