(My) Guidelines to contribute to a repository Git

#dev, #git, #me

After working for 10 years and since the beginning using git, I’ve got many opinions. Yes, opinions. Things that I like or not or things that I believe are better for a repository and for the community (a company is also a community).

Protect master

Always protect master from git push directly. All the three more popular git hosting (Gitlab, Github, and Bitbucket) has some mechanism to protect the master branch.

master is unstable ALWAYS

Create a production or stable branch if you want to make sure that the stable code is in one branch.

You can even delete production as much as you can and cherry-pick (stable) commits into it. I saw this in one company, and it worked very well.

For real, let the developers play as much as they want with an unstable branch.

Oh, btw, don’t create branches that are subbranches of a more significant feature, that thing is more likely to get old, and many problems can happen 😐.

PR them all

I don’t have to explain this, but I’ve seen people not creating Pull Request while sharing code.

I don’t know why I can only guess: maybe someone is afraid of getting his or her code commented?

Also, don’t tell me that someone is not sending PR because he or she is afraid to push bad code into a branch. What can happen is the exact opposite because there is no review of one’s work.

Where the commit is from is not important

Branch name like 1234-something-logical-here is not relevant.

What if someone wants to work with a fork? Alternatively, the guy has his/her way of branching?

If you think that the name of a branch is important: open git log press space 7 times, find a commit that is not merge branch ‘xxx’ into ‘yyy’ or merge PR xxxx and show me where the first commit in yor screen came from 😉.

Seriously, what is important is the message of the commit.

Commit with the ID of the task

Commitar com a ID da tarefa é uma adição da anterior. Uma mensagem de commit deve ser complete por si mesma, porém muitas vezes uma tarefa não pode ser concluída num único commit.

git commit -m "Fix conflicts"? Zoeira? Se você usa rebase them all você nunca vai ter conflitos, mas se você não usa pelo menos informe os arquivos que estão envolvidos.

$ git commit -m "Fix conflicts in app/models/category and app/services/category_builder"

Mesmo se você commitar com o principal funcionalidade da sua tarefa, escreva também o que aquela funcionalidade é. Por exemplo, ao invés de commitar Add merge feature, escreva algum que faça sentido:

$ git commit -m "Add the ability to merge category and subcategory." -m "[#1234]"

Just merge feature is too generic and it is likely that a merge feature will repeat in the future in other part of the software.

Don’t mess up with someone else’s branch

You can loose code if you do so. While git push -f into master is the worst thing in git; other branches are not like that.

Always ship your code and ship it often

Even if your code is not “production-ready” you can send the code (and tests, of course) to master and disable it using feature flag or permission management.

For example:

unless Rails.env.production?
  # The super feature that I love here
end

Or, as I like:

if ENV.fetch("ENABLE_MERGE_FEATURE", false)
  # The super feature that I love here
end

All of those are my opnions and the best I extracted from working in a team.

To sum up:

  1. Code review increases code quality, if you merge your own PR, maybe no one is checking your code quality
  2. Protecting master makes master a safe place for developers
  3. Don’t let your code get old; Ideally a code/PR should not be older than 2-3 days