Niraj Zade | Website is a work in progress.

Git based development - Standards and Etiquette

2024 Aug 28  |  9 min read  |  tags: git 1 conventions 1 software-engineering 3 

Work in progress
Work in progress
Work in progress
Work in progress

Branches

First decide what kind of development you will be following:

Branch naming rules is simple: You can only use numbers, lowercase letters, and hyphen (-). Use hyphens to separate words (-) in the branch name. The validation regex looks like this: ^[a-z0-9\-\/]+$.

Git flow based development

A project of this type will always have 2 core branches:

  1. main - Contains production-ready code. Used to deploy to production (though CI-CD)
  2. dev - Used to develop new features

Optionally, codebase might also have a release branch. This stores milestones in the project. Release branches are well tested, rock solid, and dependable.

All other branches that you'll create will follow a specific nomenclature. Every branch's name tells the purpose of the branch. This way, you can look at a branch and immediately tell why it exists and what it does.

In Git-flow based workflow,the code flow between branches looks like this:

Trunk based development

Trunk based development flow looks like this:

Commit messages

Just think - when do you actually look at commit messages? Most of the time, the answer is - When something has gone wrong and I'm trying to find out when it went wrong, by reading through the history of changes. - When you want to create a new branch, and are looking for a particular commit.

For this, you need commit messages that actually tell what was done to the codebase in each commit. More specifically, you need commit messages that tell the module/files affected, and what was change was done in them.

You're telling what changes you did. So the template of a commit message is simple: 

<area you affected>:<work you did>

Examples:

As you can see, the area you affected could be a single file, or a module, or something else. But it usually is a single thing that you can put into words.

If you think to yourself "I can't do this. I've worked on too many things. It doesn't fit into a single area affected.", then my friend, your commit is too large. You need to break it down into smaller commits.

Some more points:

Writing paragraphs in description is fine. This happens often in open source projects.

But always make sure you start with a summary line. It can look like this:

<area you affected>:<work you did>
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Morbi lectus turpis, commodo ut odio a, pretium volutpat justo. Curabitur eros nisl, consequat id consequat et, bibendum at elit. Aliquam fermentum urna in tellus egestas, at faucibus orci tincidunt. Duis et nibh leo. Curabitur varius bibendum ex, ac tincidunt neque suscipit a. Praesent ullamcorper sollicitudin tristique. Praesent in ante turpis.

Pull requests

Use pull requests when you are committing to branches that have other contributors (shared branches). Don't directly commit code to these shared branches.

This serves 4 purposes:

  1. The person whose code you've affected gets to know the changes you made. This person can then decide if the change is acceptable to them or not. If not, they will give comments on what needs to be fixed before they will accept the code.
  2. You can get feedback from more experienced programmers in your team. In PR review, they can comment things like better ways of implementing the logic, coding standards you didn't follow etc. It is great for learning, and helps to maintain code quality and standards.
  3. Having someone else go through your code during a PR review is great for finding mistakes you might have missed or bugs you might have mistakenly created. While working with code, it is easy to develop tunnel vision and lose sight of mistakes. Having someone else go through your code helps solve this problem.
  4. If you're new to the codebase, this protects you from causing mistakes. Typically when working with large codebases, you generally don't know the ins and outs of a module and its interactions with the rest of the system. In this case, you get help from an existing developer who knows these things.

So, it is fine if you directly commit to branches that only you work on. Eg - feature/, bugfix/ etc. But when you are merging this branch back into a parent branch (eg - dev), create a pull request and add relevant people to review the code.

Example scenarios:

© Niraj Zade 2024 - Website, Linkedin

Website was autogenerated on 2024-12-21

~ whoever owns storage, owns computing ~

Table Of Contents:

All Articles

Blog

Resources