Guidelines for managing code with Git

For smooth operation

The entire team needs to work on three things:

1. Adopt a Git operation model
2. Make clean commits
3. Send in and obtain the proper pull requests

Adopt a Git operation model

First, learn A successful git branch model (git-flow).

Source: A successful Git branching model

• The git-flow standard branching method for Git is depicted in the above diagram.
• Complete the tasks on the feature branch and merge it into the develop branch.
• The main branch will be utilized for production operations following the release branch. In the event that a bug arises, the hotfix branch will fix it.

This allows you to take risks while working on feature branches, and sometimes even to throw away the branch altogether.

And to prevent human error, it is a good idea to set up the system to prohibit commits and pushes in master and develop.

Make clean commits

A clean commit, in my opinion, is one that makes it easy for a third party to comprehend the what and why of the modification right away.

Describe the "why" in the commit message and the "what" in the actual code change.

Use a template such as "I did XX for XX" to compose your commit messages until you are comfortable with it.

What: Explained by the code change itself

As long as each commit contains only one role, I believe it to be acceptable.

As long as you can utilize a template in your commit message, such as "I did XX for XX," it is acceptable.

Commitments with the format "I changed XX and YY" have a lot of detail.

You might be wondering how many lines of code you can alter. Well, if the task is to make a single commit, I believe it is acceptable to alter one line or even one hundred (albeit that is a bit drastic).

A clean commit is crucial because it allows "a third party to readily identify the what and why of the change."

Why: Explained in the commit message

The modifications are visible in the code, but only the person who made them is aware of their intended purpose.
To ensure that a third party can comprehend the modifications, you should explicitly state them in the commit message.

Use a template, such as "I did XX for XX," for your commit messages while you are still getting used to it.

It should be simple to express the "why" if there is only one change ("what"). It is probably advisable to question the necessity of the modification if you are unable to do so.

Do not forget to prefix your commit message.

feat: A new feature
fix: A bug fix
docs: Documentation only changes 
style: Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc)
refactor: A code change that neither fixes a bug nor adds a feature
perf: A code change that improves performance
test: Adding missing or correcting existing tests
chore: Changes to the build process or auxiliary tools and libraries, such as documentation generation

If you continue in this manner,

The modified category is clearly visible.

See instantly if any modifications impact the logic of the code.

Among the advantages are:

In my opinion, a commit will automatically turn into a clean commit if you can utilize the prefix + template "I did ____ for ____" in a fluid manner.

For reference, we will list the minimum git commands you should remember:

• git clone, pull, checkout, add, commit, push

• git log, diff

• git commit -m "message 1" -m "" -m "message 3" (this will create a three-line commit message)

• git commit --amend -m "amended message" (this allows you to amend the previous commit message)

  • If you amend after pushing, the hash value will change, causing the local and remote versions to become inconsistent.
  • If it is an ad-hoc analysis, I think it is okay to force push the feature branch before merging it into develop. It is a good idea to have the team agree on how to handle these risks.

Submit and receive appropriate pull requests

A pull request is appropriate, in my opinion, if it satisfies the following requirements:

• The commits are clean (by the (2) description).

• Pull requests only have one purpose; concurrent refactoring is not allowed.

• Recognize the reviews you want to receive (see below).

• Possibility of taking chances (see below)

Know what you want from reviewers

In the pull request description:

• to whom

• what

• How

Write down what you want to see:

• Do you want me to take a look at the overall structure and see if there are any problems?
• I'm not too worried, so is it okay to just skim through it?
• Is there anything you're unsure about?
• Is it just information sharing?
• Is it okay to just edit comments so I don't need to look at them?

Please state your stance.

If you simply say, "Please review," it will be unclear what you want from the reviewer, and they may end up reviewing more than necessary, which will increase the reviewer's burden and lead to unnecessary communication.

Write a description for your pull request that lets reviewers know what you're looking for.

Able to take risks

In the end, it comes down to how much risk you are willing to take to ensure quality.

I think merging from a feature branch to a develop branch is particularly risky.

I also think that self-merging and post-merging reviews are a good idea, with an emphasis on work efficiency.

First of all, you should be responsible for the code you write, and it's important to have a sense of responsibility and not rely too much on reviewers.

It is best for the team to agree on how to handle these risks based on each member's level of proficiency.

Next, I'll list the mindset I personally keep in mind when submitting pull requests.

• Clean pull requests make code reviews easier
• Pull requests left overnight will not be held
• Submit pull requests that are easy for both parties
• You don’t need to review everything
• Self-merging is also OK
  • Especially low-risk changes such as:
    • Editing comments etc.
    • Typo bug fixed
    • Light commitment from highly skilled members
• However, be careful to provide thorough reviews for junior reviewers and reviewers who have just started the project and have little understanding of the data.
  • However, if it is merged to develop, there is no problem with post-mortem review.

What is the benefit of managing your code well by satisfying 1, 2, and 3?

• Quality can be guaranteed by smoothly running code reviews.

  • Since it is assumed that other people will see it, try to write clean code.
  • Code reviews improve internal quality
  • Code reviews improve team and individual skills
    • If you don't have the skills, you'll never be able to write clean code, even if you have the time.

• Communicate your changes and intentions to others

• Other people include your "future self"

• You can look back and see what caused the bug and why you made the change.

  • For that reason, you need to write in the commit message why you made the change.

• By discussing the pull request, you can understand the process of decision-making.

• As a result, individual work efficiency increases.

• Understanding the "big picture of the work" and "what needs to be done now" makes it easier to make clean commits and pull requests.

• On the other hand, if your commits and pull requests are messy, there is a high possibility that you do not understand the "big picture of the work" and "what you need to do now".

Reference

• Manage Git