Version Control - Git
In modern software development, version control systems like Git have become an essential tool for managing projects and collaborating in teams. Git is a distributed version control system that allows teams to work on the same codebase without overwriting each other's changes. As a software developer working in a team, it's crucial to follow some best practices to ensure that the codebase stays organized, and the development process is efficient. This doc outlines some of the key rules, regulations, and standard practices that you should follow while working with Git in a team.
Here are some of the best practices that you should follow while working with Git in a team:
- Ticket-based branching:
- Commit messages:
- Rebasing:
- Raising pull requests:
- Fixing Code Conflicts:
- Fixing Code Review Comments:
- Merging:
- Taking Pulls:
I would recommend you to read this series of docs to learn everything about Git, and GitHub. I will try to keep this series of docs up-to-date.
Ticket-based Branching
When working on a project, every task or issue should be assigned to a ticket. The ticket is a way to track progress, and it should have a unique identifier. When creating a branch, it's essential to use the ticket identifier in the branch name. For example, if the ticket number is #1234, the branch name could be something like feature/1234 or bugfix/1234 This naming convention ensures that every branch is associated with a specific task, and it makes it easy to identify which branches are related to which tickets.
Read this doc to learn more about branch naming conventions.
All branches should be created from the main branch. This practice ensures that each branch contains the latest version of the codebase, and it minimizes conflicts when merging. Create only one branch per ticket. This practice helps to keep the changes isolated, and it makes it easy to track the progress of each ticket.
Commit Messages
Commit messages are an essential part of Git version control. A clear and concise commit message helps team members understand what changes have been made and why they were made. When writing a commit message, it's essential to keep it short, but descriptive. The message should start with a one-line summary of the changes made, followed by a more detailed explanation of the changes if necessary. It's also important to use present tense in commit messages and avoid using technical jargon. Good commit messages can save time and prevent confusion, especially when reviewing changes made by team members.
You can read this doc to learn more about writing good commit messages.
Rebasing and Merging
As a team member, you may be working on something in a feature branch meanwhile changes are being made to the main branch by merging other PRs into it or by pushing new commits. To ensure that your feature branch is up-to-date with the latest changes in the main branch, you have two options: rebasing and merging.
Rebasing involves taking the changes made in the main branch and applying them to your feature branch. This method creates a linear history of changes and can help reduce merge conflicts. To rebase, switch to the feature branch and run the command "git rebase main".
Merging, on the other hand, involves combining the changes made in the main branch with your feature branch. This method creates a merge commit and can be useful if the changes made in the main branch and your feature branch are significantly different. To merge, switch to the feature branch and run the command "git merge main".
It's important to note that rebasing and merging both have their advantages and disadvantages, and the best method to use depends on the specific situation.
I wrote a detailed doc on Rebase vs Merge, I would recommend you to read it
Raising Pull Requests
Once the code changes are complete, the next step is to raise a pull request (PR). A pull request is a way to notify other team members that you have made changes to the codebase and that you are ready to merge them into the main branch. When raising a PR, it's essential to add reviewers and assignees. The reviewers should be other team members who can review the code changes and provide feedback. Assignees are the people responsible for merging the changes into the main branch.
Mark your PR draft if it's still a work in progress. Do all code related discussions on PR. This will help other team members to understand the changes you have made and why you have made them. It's also essential to add a description to the PR. The description should include a summary of the changes made, a link to the ticket, and any other relevant information.
Get your PR review and merge as soon as possible. This practice helps you to avoid conflicts and ensures that the codebase stays up-to-date. The more time it would stay in the waiting queue, the chances of conflicts will increase. You can give soft reminders to your reviewers to review your PR so that reviewers can review your PR as soon as possible.
Read this doc
Fixing Code Conflicts
Code conflicts can occur when two or more team members make changes in the same file (or lines of code). When this happens, Git will prompt you to resolve the conflicts manually. To resolve conflicts, you need to compare the changes made by each team member and decide which changes to keep. Sometimes it's essential to communicate with the other team members when resolving conflicts to ensure that everyone is on the same page.
It's also essential to thoroughly test the changes before committing to ensure that they don't cause any unintended consequences.
Fixing Code Review Comments
While reviewing code changes, it's common for reviewers to leave comments, and suggestions. To effectively resolve code review comments, it's important to carefully read each comment and understand the reviewer's feedback. If you don't understand a comment, don't hesitate to ask for clarification from the reviewer. Once you have a clear understanding of the feedback, make the necessary changes to the code.
It's also essential to address all comments, even if you don't agree with them. If you don't agree with a comment, it's important to explain why and offer an alternative solution. This can help prevent misunderstandings and ensure that all team members are on the same page.
Once you've made the necessary changes, submit a new commit or amend the existing commit with the changes. It's important to ensure that the changes are thoroughly tested before submitting them to the PR.
Merging PR
Once the PR is approved, merge it into the main branch. Before merging, it's important to ensure that the PR is up-to-date with the latest changes in the main branch. This practice helps to avoid conflicts and ensures that the codebase stays up-to-date. If the PR is not up-to-date, rebase or merge the main branch into the PR branch to ensure that it is up-to-date.
After merging the PR, delete the branch. This practice helps to keep the codebase clean and organized.
Read this doc to learn more about merging a PR
Taking Pull
If multiple team members are working on the same project, it's important to keep taking a pull to ensure that you have the latest version of the codebase. This practice helps to avoid conflicts and ensures that you are working with the most up-to-date code. It's also essential to take a pull before raising a PR to ensure that the changes you are proposing are compatible with the latest version of the codebase.
And create a new branch from the main branch, and start working on it. Sometimes, you may have dependencies on other PRs as your ticket may depend on the code changes made in other PRs, and those PRs are pending for review and merge. In that case, ask the reviewers to review and merge the PRs as soon as possible. If you have any questions, ask them in the comments section of the PR. You can also create branches from other branches, but it's not recommended. I would recommend you to create branches from the main branch and do the work which you can do independently, and once other PRs are merged, rebase (or merge) your branch with the main branch, and then start working on it.
But normally, you won't have any dependencies on other PRs, and there would be PRs waiting in the queue for review while you are starting your work, and creating a new branch from the main branch, and the PRs merged while you were working on your ticket, whenever you are ready to raise a PR, rebase (or merge) your branch with the main branch, or merge the main branch into your branch, so that you code is not behind the main branch, and raise a PR.
Conclusion
Working with Git in a team can be challenging, but it doesn't have to be. By following the best practices outlined in this article, you can ensure that your team is working efficiently and effectively.