The Good Git Culture

Git is a free and open source distributed version control system designed to handle everything from small to very large projects with speed and efficiency.

Contributing

One of the keys to have a good repository using git, regardless of its structure, flows and rules, is that all contributing members must know how it is organized and how git works.

It doesn't matter if it is a public or private, open-source or small group, there should always be a Readme.md or Contributing.md file that tells the user how all is organized in the repository (branch structure, working flow, Merge/Pull Requests, templates, etc.).

Normally, this document is dividing in multiple sections that handle each basic topic:

1. How to provide feedback or ask questions.
2. How to report issues.
3. Repository structure.
4. Code/Style conventions.

There's no need to write an extended biography about your project, just a simple document about the essentials and basics of how it is all organized. There are many contributing guidelines to use as an example:

• https://github.com/opengovernment/opengovernment/blob/master/CONTRIBUTING.md
• https://github.com/atom/atom/blob/master/CONTRIBUTING.md
• https://github.com/microsoft/vscode/blob/main/CONTRIBUTING.md

So next time you join a new project, check if exists one and make sure to understand it, will save you time in the future. Many of the initial questions we all have, are normally already answered in those documents.

The only way of keeping something organized is by all knowing how it is organized.

Branching

The way and the meaning we give to our branch varies a lot depending on the project we have. Before creating a new repository, we must know what is going to be our pipeline or workflow for managing our versions and product content.

There are many ways of doing this (Git Flow, Trunk Based, GitHub Flow, GitLab Flow, etc...). Most of them work the same basic way as Git Flow, but changing who the interaction between branches is done. There's no better solution than the other, the best one is the one that fits your project and way of working.

For small projects/teams or starting a new project, maybe it is more efficient and clean to use a simpler solution like Trunk suggests. Use just one central branch called trunk or master, with new features or changes being done on outgoing branches that merge to master.

For bigger teams and projects with many releases and features being in work at the same time, probably any Flow with more branches helps to keep a better track of the status of the product. But also require more work and control for managing it properly.

Always stay as simple as possible 90% of the time you won't need more than a Git Flow structure (master, develop, feature, hotfix) with more than 2 of Branch Depth. And 99% of the time more than 3 of depth. So stay as simple as possible.

You are not restricted to use Git Flow, you can create any variation that fits you the best. Just make sure that all the team knows how it works.

But the most important thing, is that the Team/Company as a whole works with the same workflow. Not only developers/contributing members must follow this, also the Marketing, Managers, CEOs, etc. must follow the same idea. As much as a developer tries to keep the repository clean and working, if the manager doesn't organize the releases and handles the issues the same way, the system won't survive.

All the team must follow the same road to reach the same destination. There no: "All roads lead to Rome".

Merge/Pull Requesting

This is a critical part of the software development process. On this stage, we select what is ready for release and what doesn't make the cut. Therefore, we must ensure that the quality is up to the standards and all works as intended.

Unless we are on a personal project, a merge request should always include a minimum of two people reviewing it. The best fit would be to review two members that are not the ones involved in the development process of that branch. This way, we ensure other teammates get to know what's new on the project and are able to check for errors. Definitely, six eyes do see more than two!

This is a collective effort and requires the time of other people to help you review the Merge Request. It is important that prior to letting them review the changes, we ensure that all is ready, and you won't be wasting someone's time for something that is not ready yet, or just because we forgot something.

Committing

Creating commits seems to be one of the most simple things in our work. Stage the changes we want, write a message, commit and push! But sometimes we don't take the time to view what we really are doing on this.

Every commit in a branch should have a meaningful existence. 99% of the time there's no need to commit something that is not working/doesn't compile or does simply not give a meaningful addition to our previous commit. This doesn't mean that we must create a branch and only commit once. We must ensure that each commit has the quality and meaning it should.

Committing should be our first Code Review.  We must ensure that what we are adding to our branch is a something like a working "section" of our product. We must be sure that after committing, we won't notice that we forgot something to add.

With this we ensure we have a clean working tree, something that in big repositories with many branches and contributors working at the same time, helps to simplify the overall view of the project status.

We should condier pushing as sending our product to our first customer.