Git: How To Write A History Book Of Your Project

By Lukas Varkalis, Engineering Manager at Kilo Health

Let’s say that you dream of releasing a history book. That it is not an easy job, and there are strict guidelines you must follow. For starters, you cannot change the chronological order of the events. You also must make it easy to read and to understand for others. 

The same principles apply when you develop a project using Git version control system. The other developers or maintainers should easily find the information about features released and bugs fixed. They have to understand the changes from commit messages and pull requests. Over time, those messages and information should tell you the history of your project, and how it got it’s current form.

I will try to share some tips and tricks from my personal experience on how you could manage project history while using Git. 

1. A naming convention is your friend

You will save yourself a lot of time if you define clear documentation and guidelines on how you are naming your branches, commits, or pull request titles. It will help you to know how to search for specific things in your repository or what kind of changes could be done on a specific branch. 

For that, we use the predefined scopes of conventional commits. Here are some examples which we use:

Branches:

scope / description-issueID

Example: feat/user-login-KH-10

Commits:

scope: description [issueID?]

Example: feat: implemented user login page

PR titles:

scope: description [issueID]

Example: feat: implemented user login page with password reset functionality [KH-10]

Take note that pull requests could contain a few commits with different scopes. Write them as clearly as possible, so that everyone can see your progress on a specific feature or issue. An example how it could look like:

Also, you could pick some ideas or examples from Angular convention and how they do it.

2. Provide useful resources

Use pull request description to give some context about the changes or the task. It will help other developers get the idea of what you have done. You will also help QA engineers understand what things could possibly break or what they should test.

As a result, writing a solid description will save you hours in the long run. If you don’t provide additional resources right away, you will probably have to explain your solution to every new teammate that works with the project.

“Pull requests should present what you are releasing and why.”

Also, if you are solving an already registered issue in your JIRA account, do not forget to link it. It could be useful in searching for more context and understanding why this task was created. Providing some screenshots or recordings would also be very helpful.

Those things you could usually find in open-source projects: they tend to explain very well how to reproduce an issue, why they are changing or removing some functionality, or why a new feature is necessary.

If you are not sure how to do it, here is a merge request template we developed:

# Description

[//]: # (Please include a summary of the change. Please also include relevant motivation and context. List any dependencies that are required for this change.)

## References

* [Design]()
* [Staging]()

# Checklist:

[//]: # (Optional)
[//]: # (Please replace [ ] with [x] in order to select)

- [ ] I have performed a self-review of my own code
- [ ] I have made corresponding changes to the documentation
- [ ] I have added tests that prove my fix is effective or that my feature works
- [ ] I have noted places that could be refactored or improved if it is necessary
- [ ] Any dependent changes have been merged and published in downstream modules

3. Comments on pull requests

We can’t be sure about some historical events, because there is not enough clear data about them. We can only use the sources available to us, but if the event happened a long time ago, we can only provide a hypothesis and seek to find evidence to support it. 

And sometimes, we just can’t agree on something by 100%. Choosing one approach or another implementing something in a project could be the same: there is no correct answer. 

For that reason, we decided to filter our comments into several main categories, some of which are more important than the others. We decided to do it because when you see a lot of comments on your pull request, it could demotivate you from solving them right away. 

Also, a lot of comments might mean that it could take a lot of time to do it. Since we introduced the comment categories, we don’t have the same issue – people can estimate the workload easier.

There are a few of them:

nitpick – typically a naming or syntax-related things

// Original code
const openSidebar = false;

// nitpick: the naming should indicate that this is a boolean variable, like
const isSidebarOpen = false;

Comment – a bit stronger than a nitpick, something worth considering, but not an icebreaker. The owner can still decide if they want to care about it.

// Original code
doSomething?.();

// comment: you might use if condition to call that function, like
if(doSomething) {
 doSomething();
}

Question – the reviewer needs some explanation about the implementation or approach.

// Original code
return (
 <>
  <Box className="flex flex-item">
   Hello World!
  </Box>
 </>
)

// question: why do you need the React Fragment as a wrapper for this component? Does it require a flexbox parent?

Change request – the icebreaker. It means that the reviewer would like to see a different implementation or approach for the specific part of the code.

// Original code
function displayProductName(product?: Product) {
 if(!product) {
  return null;
 }

 if(product) {
  return <Box>{product.name}</Box>
 }

 return null;
}

// change request: too much complexity because of those conditions, keep only the early return at the top, like
function displayProductName(product?: Product) {
 if(!product) {
  return null;
 }

 return <Box>{product.name}</Box>
}

Those types also let the owner decide which issues need to be fixed and which comments are just a suggestion or informative one. Also, you could add your own types if it is needed.

To sum up

Imagine that your pull requests are like a table of content in a book. Try to write them as clearly as possible because it helps you find specific historical events more easily when needed. With clear Git convention, you could easily find answers to specific questions, for example, when someone happened or was fixed.

Be patient because it takes some time to get used to, but it could significantly improve your team communication and processes.

Would you like to be a part of our history book? Check out the open positions here.

Lukas Varkalis

ex Front-End Guild Lead

A tech guy who is passionate about building high-performing engineering teams and always cares about people. Lukas has launched over 50 MVP projects and can easily build one over the weekend. Loves to study design, data, and human behavior.

See all posts