Reviewing a System's Code Using Git

3 min read
19K views
Git
GitHub
Development Management

Sometimes, you need to review the overall state of a repository’s code, such as when accepting code from other developers or joining a new project.

Code review workflows in platforms like GitHub are typically centered around incremental changes. However, in our case, the feedback is related to the state of the entire system at a specific moment.

Here’s how you can accomplish this using Git: capture the state in a branch for review, then leave comments via a merge request to that branch.

The essence of the method has been summarized. Let’s dive into some details.

The Problem

Imagine you’re handed a repository and asked to share your thoughts about its code. Typically, such feedback is compiled in a separate document, task tracker, or Confluence page, which has its drawbacks:

1. Outdated Feedback
   Comments can become obsolete during the review process as development continues.
2. Hard-to-Reference Code
   Referring to specific lines (e.g., doubtful/bar.js:4) becomes cumbersome when constantly switching between the document and the code.
3. Disconnected Context
   Documents separate from the code are prone to getting lost or overlooked.

System Review Method

To perform a system-level review, follow these steps:

1. Identify the state of the repository to review (e.g., the latest commit in dev):
   • Commit: https://github.com/oktend/system-review-example/commit/0514531a35edf19e7032eb49f45a98d019f83efe
2. Create a branch from the chosen state for review, e.g., system-review/1march2020-goodman:
   • Review Branch: https://github.com/oktend/system-review-example/tree/system-review/1march2020-goodman
3. Create another branch from the review branch for your comments, e.g., 1march2020-goodman-issues:
   • Comment Branch: https://github.com/oktend/system-review-example/tree/system-review/1march2020-goodman-issues
4. Add your feedback to this branch—either directly in the code or as separate documents.
5. Open a merge request (or pull request) from 1march2020-goodman-issues to system-review/1march2020-goodman:
   • Merge Request: https://github.com/oktend/system-review-example/pull/1/files

The Outcome

In the created merge request, all feedback gathered during the review is visible and open for discussion.

The state of the code being reviewed is preserved until the branch is explicitly deleted.

Comments can be:

• Separate from the code:
  • Document Example: https://github.com/oktend/system-review-example/blob/c80b03710059b235347ec781bf08dca9c0e68f7d/review-1march2020-goodman.md
• In-context with the code:
  • Code Example: https://github.com/oktend/system-review-example/blob/c80b03710059b235347ec781bf08dca9c0e68f7d/foo.js

You can view comments via:

• Web interfaces (e.g., GitHub, GitLab, Bitbucket).
• IDEs.
• Git CLI tools.

This approach ensures that the review context and comments remain accessible for future reference.

Notes

I acknowledge that this might reinvent the wheel and that better methods may exist for such cases. If you’re aware of superior approaches, I’d appreciate your guidance.

Credits:
This idea wasn’t mine; it was suggested by a developer. If Artem wishes, I’ll credit him as the author.

Tags

code review git github gitlab bitbucket