Your Junior Dev Survival Guide to Managing Branches, Commits and PR

                                                     *We will survive, believe me!*

Something that all junior developers share, regardless of the stack they are working on, whether it's backend, frontend, mobile, JavaScript, C#, Angular, PHP, or whatever the focus of their work is: managing branches, making commits, and creating Pull Requests.

One of the key factors to transform your career is to refine your communication with your team more and more. The clearer you are in presenting your ideas, doubts, and opinions, the more value you will have.

So, as the idea of this text is to be practical, let's go to our main topics: Managing Branches; Commits; and Pull Requests.

Managing Branches

Gitflow is a model for managing branches. The idea is to create, from the main branch, specific branches for the development of your project, complete the development of what you are creating, and merge it back into the main branch.

In Practice:

Your task for the week will be to include a social login with Facebook in your project. What's the first step? Start your project from the main branch (main), switch to the branch where the project is being developed (develop), and from there, create a new branch for this task and work on it (feat/social-login-facebook). Only then do you start your work. When you finish your work, this branch will be merged into the “develop” branch.

What are the most common types of branches?

• Main: It is the main branch, reflecting the most "stable" version of the product you are working on.
• Develop: Developers use this branch to start their projects, and it serves as the base code.
• Feature: This branch is created from the development branch for specific tasks. It is considered a temporary branch that, upon completing its task, should be merged back into Develop.
• Hotfix: Similar to the Feature branch in that it's temporary, but it is used for immediate fixes. It can be created from the developed or main branches.
• Release: This branch is considered a "pre-main." When various tasks are completed and a significant stage of development is finished, a release branch is created from the development branch. It serves more as a milestone for the type of update the main branch will receive.

Ok, now that you have a better understanding of how branches work, how can you apply this in your daily routine? Free extensions are available in the Visual Studio library, such as Git Graph, which makes all these branch changes visible and distinct. Let's see:

Through Git Graph, you have access to the graph itself, showing the progression of branches, the branch description, the creation date, the author, and the commit ID. Git Graph is not only designed for a graphical view of the branching order but also for understanding the commits, where they are made, and how they come together.

There is also a specific way to name your branches to adhere to this flow, typically using a prefix like feature/, hotfix/, or release/. You can read more about the topic here.

In addition to Gitflow, there are other branch management strategies, such as GitHub Flow, GitLab Flow, OneFlow, and Trunk-Based Development. If you want to delve deeper into the subject, you can read it here.

Commits

Commit is the tool that allows you to explain the intent behind the changes you made in the code. They should be concise and descriptive, with a clear and specific purpose. Commits act like checkpoints. In addition to explaining the purpose of your changes, they also serve as a way to roll back in case your code is not approved, allowing you to revert to the previous commit.

But just like GitFlow, there are also commit standards. The one I've been using is Conventional Commits.

Using Conventional Commits makes its purpose very clear since every commit starts with either chore, feat, fix, refactor, docs, perf, style, test, build, ci, or env:

• chore: Updating tasks that do not cause changes in the production code but involve tool changes, configuration changes, and libraries.

• feat: New features or any other new implementations to the code.

• fix: Bug fixes.

• refactor: Used for any changes that are made in the code but do not alter the final functionality of the impacted task.

• docs: Inclusion or modification of documentation files.

• perf: Changes to improve performance.

• style: Formatting changes in the code presentation that do not affect the code's meaning.

• test: Adding missing tests or fixing existing tests.

• build: Changes that affect the build system or external dependencies.

• ci: Changes in CI configuration files and scripts.

• env: Modifications or additions to configuration files in continuous integration (CI) processes and methods.

  
  

Since the commit is a way to create a checkpoint, it should contain a fragment of your task. In our case, you could divide the task of adding login through Facebook into the following commits:

• Creating a relationship with Facebook to receive a token

  feat: Add integration with Facebook to receive the token

• Creating necessary permissions on Facebook

feat: Configure permissions on Facebook for integration

• Creating a component to perform the request

  feat: Implement component for the request to Facebook

• Creating verification of the Facebook token with the user in the project

  feat: Add verification of Facebook token with the user in the project

• Testing integration with Facebook

  test: Perform integration tests with Facebook

• Creating documentation for the integration with Facebook

  docs: Add documentation for integration with Facebook

By making commits in this way, when you create your PR, it will make your life easier, as it becomes clearer what should be included in the PR since you have already described everything you did in the code through the commits.

Now, what tools can help you maintain standardized commits? Commitlint and Husky.

With Commitlint, you can create a commit verification filter that needs to follow a specific format (conventional commits) to be effective.

And how do you apply to Commitlint? By using Commitizen and Husky, which compare the established rules and what you wrote. If the pattern is not followed, it prevents the creation of the commit, asking you to correct it. It is essentially an automation of the commit verification process, limiting their size and allowing them to be divided into a short message, scope, and commit description (if necessary).

For the application of these tools, I recommend these two texts:

1 - Why Should you use Commitizen + Husky for conventional commit and have organised lint

2 - Como adicionar hooks de commit ao Git com Husky para automatizar tarefas

Pull Request (PR)

And now what? You created your branch, completed the defined task, created checkpoints with commits, and now you need to make the PR to add your branch to the developed branch. How to do it?

A Pull Request is the way you ask to merge your branch into the develop branch. It is the method we use to present your work to be reviewed by other developers and approved.

The main purpose of the PR is to present what has been done, validate the work, or point out changes that need to be made and include your code in the development branch.

As a communication tool, although it does not have a convention like the previous ones, there are some ideas to keep in mind when making your PR.

Your PR should be based on WHY, WHAT, and HOW.

• WHY: Why your PR is necessary, and what problem caused your need.

• WHAT: Describe what your PR does, not in a technical way, but what the practical effect of your code change is.

• HOW: This is the space you should use to make it clear, in a technical way, what changes you made. You should use your commits as a guide for what will be explained, which files were altered/created/deleted, how it happened, and why it happened this way. That would be the basic necessity.

  
  

Now, two points to pay attention to:

The number of code changes: PRs should contain between 200 and 400 lines of code change; more than that, there's a possibility that an error may go unnoticed.

Conciseness: Your PR is the moment to explain what you did, but it doesn’t mean writing a book. Just like with commits, you have to focus on being concise and clear.

Finally, there is other information you can add to facilitate the interpretation of your PR, such as the type of changes made, screenshots or videos of the effects of your change on the project, adding the link to the Task you resolved, some form of checklist, and a section for additional information you may want to add.

You can find a screenshot and the link to the example PR template I usually use.

I also recommend Kara's article on the subject, which is much more comprehensive than this.

PS: Some teams may have their template; if yours doesn't, you can check if it's possible to add one. GitHub itself provides a detailed description of how to do this.

Conclusion

Knowing how to use and create branches, commits, and pull requests are basic concepts, but not everyone gives them the importance they deserve. Although this is not directly related to code, understanding how to use branches, commits, and pull requests is fundamental and highly valuable because it's the way developers can communicate, explain their work, and receive feedback for improvement.

This is the first text in a series of guides that I intend to create. As I continue learning in my day-to-day, I'll keep publishing these ideas.