Issues, Reviews, and the Flow

Issues are the to do list of a repository. Each one is a piece of work or a bug, with a number. Referencing that number in a commit or pull request links them automatically, so the history explains itself: this commit exists because of issue 12, and issue 12 explains what the user reported.

What reviewers actually look for. Not style, mostly. They are asking: does this do what it claims, does it break anything else, is it understandable in six months, and is anything missing such as tests or documentation.

Knowing that changes how you write a pull request. You are making those four things easy to check.

✦ Small pull requests get reviewed. Large ones get approved.

This is one of the most useful pieces of engineering culture there is. A change touching forty files does not get read carefully, because nobody can hold it in their head. It gets a glance and a thumbs up. If you want real review, keep the change small enough that reading it is genuinely possible.

The collaboration loop in full.

Someone opens an issue. Someone takes it and makes a branch. They commit and push. They open a pull request referencing the issue. Others review. It gets merged, and the issue closes. Everyone pulls to catch up.

Every team you join will run some variation of that. The vocabulary might change, the shape will not.