In the Distributed Systems Design Fundamentals course by Particular Software, which costs a few kilobucks, the company’s founder tells people with over 15 years of experience in development that it’s very important to name commits properly. No, this is not a joke. This issue is not often brought up in general, but it is very critical in development. Why bother writing something thoughtful when you can just push a commit with the text “fixes”? Let’s take a closer look at this.

First of all, branch naming. Programmers often work with a large number of code revisions simultaneously, and it’s important to precisely understand which version of the code you are currently looking at. Searching for the correct branch, then choosing one from several with similar names, or even, if you have a large organization, searching for the required type can be frustrating and time-consuming. If the team has an agreement on a certain type of structure, it simplifies everything. In this case, naming conventions like cicd/sonar-cube-check-implementation, bugfix/superuser-right-are-not-properly-assigned, or feature/property-detail-screen facilitate logical understanding of what is in each branch.

It’s also worth discussing the powerful integration of issue tracking systems with version control systems, whether it’s GitHub, JIRA, or any other tool. If you name your branch cicd/123-sonar-cube-check-implementation, where 123 is the issue or ticket number, the system will automatically link them, helping you/your colleagues see which changes were made within the scope of that issue and the current status of the branch. It doesn’t always prevent confusion, like one time when an EM told the client that everything was merged because he saw in the ticket that the branch was merged (but he didn’t see that it was merged into the wrong place because the project had a shoot-your-leg-driven git strategy), but it does help to quickly understand the situation.

Regarding commit messages — it’s the same story. Quite often, only one or two words are written there, while 50 files are changed. Now imagine that you have 10 commits in your branch, and you need to find the answer to a question, but all 10 commits say “fixes” 🙂

From a purely practical point of view and through empirical testing on teammates, the following type of integration has been found to work quite well:

Branch name: BranchType/TicketID-Brief-Ticket-Purpose

Commit Message: #TicketID: TicketID-Brief-Ticket-Purpose

  • change #1
  • change #2
  • …
  • change #n

What works well in this case:

  1. Branch visibility: The branch representing task X is not lost; manager can always see whether the work is ongoing or completed, even if the developer forgot to update the task status.
  2. Task history: In task X, you can find all the files that were changed to complete it even after six months. If the business comes and says, “Remember this task? We need to redo everything there,” you won’t have to spend time searching for the logic that was changed. Even if different people work on this task later, they have access to the history, making it easier to track the development of this feature.
  3. Well-described commits: Each commit is well-described and linked to the task. There might be a scenario where the task was completed with one commit, but later the developer realized something needed to be changed or added, and this is also part of task X. Then, we have two commits related to task X in the history.
  4. Easier navigation among commits: Imagine you have a large feature with 10 commits, and you need to find something important or check where the functionality broke down. This is especially relevant for large features or over a long period when you want to find something, and it’s much easier to orient yourself in structured messages than in one-word messages.

Certainly, this approach may not work for you and your team, but its presence in any variation significantly simplifies the team’s work.

Source link