Git: How To Write A History Book Of Your Project

Aug 4
Engineering

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.

Latest articles

Deimante Butke and her 3 roles: Full-Time Job, Pursuing a PhD, and Motherhood
Feb 15
Kilo Heroes

I’m Deimante, currently Head of Marketing at Kilo Health, and a big lover of this company. My journey to being hired at Kilo has been quite the ride.  How it all started? I underwent interviews with 11 different people and…

Read more
Kilo Health Launches an Incubator Challenge: Ready to Test Yourself in a Startup?
Jan 12
Articles

Ever dreamt of taking the lead, even if the path isn’t crystal clear? Or to have someone believe in you and offer you a chance to figure out whether you would thrive in a startup environment? Speaking of which, Kilo…

Read more
Kilo Health Celebrates Its 10th Anniversary: Milestones and Lessons
Oct 25
News

A whole decade has raced by in the blink of an eye for us at Kilo Health, and what better way to celebrate than to reflect on the milestones and lessons over the years? Do you know where we started?…

Read more
Vitalijus Majorovas: Co-Founders Also Need Balance
Aug 23
Kilo Heroes

We, the co-founders, are just ordinary individuals with grand ambitions. There are times when we work twice as long and intensely as others, yet we’re equipped with the same amount of daytime, energy, and capacity. However, as leaders in the…

Read more
Following Your Gut: How to Avoid the Startup Graveyard
Aug 11
Kilo Heroes

There’s no enchanting tale behind how I became a part of Kilo Health. In truth, some of us regular folks simply have regular journeys, and that’s perfectly fine. What counts is that today, I hold a successful product in my…

Read more
Kilo Health Breaks Records: 84% Growth, 213M Euros in a Year
Aug 8
News

Reflecting on your achievements from the previous year is advantageous. That’s exactly what we did, proudly demonstrating our boundless aspirations through an impressive 84% growth and 213 million euros. So let’s put our hands in the air and celebrate together,…

Read more
I Don’t Need a New Job: Or How to Join Kilo Health Within 10 Minutes
Jul 14
Kilo Heroes

I joined Kilo Health back in 2019, and I can prove that when people’s values and mindsets align, great things can be accomplished, even if you don’t have a plan. BoomeranGO!, the first and only product for children provided by…

Read more
4 Ways Startups Can Draw Inspiration From Hollywood 
Jun 14
Kilo Heroes

Lighting, sound, set, and actors are essential components of a film studio, but they are not the sole factors that define its success.  Consistent creativity, appreciation of talent, and adaptability to market trends are a few of the things that…

Read more
NUTRITION AND WELLNESS TRENDS TO FOCUS ON IN 2024
Feb 22
News

By Kristina Zalnieraite As we enter the year 2024, the realm of nutrition trends is poised to undergo significant developments, placing particular attention on diverse subjects, with gut health emerging as a prominent focus. The spotlight on gut health has…

Read more
Predicting IT Trends: How Kilo Health Stays One Step Ahead
Jan 30
News

In such a fast-moving industry like digital health, keeping on top of the latest trends is essential for companies hoping to grow, succeed, and leave a lasting mark. As the leading Lithuanian company in the technology sector, Kilo Health certainly knows how…

Read more

Stay on top of health and wellness news

Kilo Outsider is a curated monthly newsletter for everyone who cares about health – from investors to policy makers, from entrepreneurs to healthy living enthusiasts.