Git is an essential part of day-to-day development for any developer, especially for those who work with multiple developers. The well-maintained Git history will help in debugging issues, understanding the changes made in the code, and maintaining the project. This blog provides the guidelines that should be followed while using Git. The configuration of a Git account, commit messages, documentation of reasons for changes made, and more are discussed in this blog. Following these guidelines will make it easy for a developer to maintain the repository and Git history.
Configure Your Git
Before getting into development, please ensure that you have Git installed and set up on your machine. More specifically, you should add your name and email for the commit identification process.
You can configure them globally using:
git config --global user.name "Your Full Name"
git config --global user.email "your-email@example.com"
It is always best to use the email address linked to your GitHub account. This will help make it easy for you to be identified via the commits that you make.
Ensure that your GitHub profile contains your full name. If there are additional details that need to be added, such as your team, a photo, and your brief description, do that.
Commit Message Structure
The commit message must clearly describe the relationship between the change and the reason behind it. For the Odoo codebase, follow the format below:
[TAG] module: short description
Detailed explanation of the reason for the change.
References such as task numbers, issue numbers, PRs, or OPW tickets.
For example:
[FIX] account: prevent duplicate reconciliation
Prevent duplicate reconciliation entries when processing
the same payment multiple times.
Fixes #123
A commit message generally contains four parts:
- Tag – identifies the type of change.
- Module – identifies the Odoo module affected.
- Short description – briefly explains the purpose of the change.
- Detailed description – explains why the change was necessary and provides any useful technical details.
The explanation is crucial, particularly in cases when the change itself is complex. The code already explains what has been changed, and therefore, the message should focus on the motivation for the change.
Commit Tags and Module Names
Add the proper tag to each commit message.
- [FIX] – Used to fix bugs or incorrect behaviour.
- [REF] – When existing functionality is substantially refactored.
- [ADD] – Used when you add a new module.
- [REM] – To be used when you are deleting unused or unnecessary code, views, modules, or other resources.
- [REV] – Reverse a previous commit.
- [MOV] – Used for moving files or code. Use git mv where possible; do not change file content on move.
- [REL] – Used for commits related to releases.
- [IMP] – For improvements or incremental changes.
- [MERGE] – For merge commits, especially when merging changes between branches.
- [CLA] – For Individual Contributor License Agreement commits.
- [I18N] – Used for changes related to translation.
- [PERF] – Performance fixes.
- [CLN] – Used for code cleanup.
- [LINT] – Used to perform linting
After the tag, use the technical name of the module rather than its functional name. Technical names are more stable and make it easier to understand the module history later.
For example:
[FIX] sale: prevent incorrect order confirmation
If multiple modules are changed, try to separate the changes into different commits whenever possible. If separating them is not practical, use an appropriate common name such as various.
Commit Message Header
The first line of the commit should be short, clear, and meaningful. Ideally, keep it around 50 characters.
Avoid vague messages such as:
[FIX] account: bugfix
[IMP] sale: improvements
Instead, describe the actual purpose:
[FIX] account: prevent duplicate payment entries
A useful way to check the header is to read it after:
"If applied, this commit will..."
For example:
[IMP] base: prevent archiving active users
Becomes: "If applied, this commit will prevent archiving active users."
If the sentence makes sense, the commit header is probably clear enough.
Commit Description
The longer description should explain why the change was needed. Describe the problem, the fix, and the reason for the fix, and any important technical decisions.
For example, instead of saying:
Change the condition and fix the payment validation.
The reason being:
- The same transaction could be processed again, which could trigger multiple validations of the payment. This created duplicate entries.
- The validation was modified to check if a transaction already exists before creating a new record, thus preventing duplicate records.
The exact code changes do not need to be repeated line by line because they can be seen in the Git diff.
If you can, try to put changes concerning one module together in one commit. If the modules differ, it would be advisable to use separate commits for this purpose. This will make it easier to trace history and revert changes to one particular module if needed.
References should be added at the end when available:
task-123
Fixes #123
Closes #123
opw-123
Use the appropriate reference depending on whether it is a task, GitHub issue, pull request, or OPW ticket.
A commit message needs to make sense even when the original author of the commit does not remember anything about the task anymore. It should provide enough information about the issue in question and its solution so that a person analyzing the history can easily grasp what was done and why without referring to all the parts of the code. Spend some time writing a commit message when your work is completed. A neat commit history is very helpful for debugging, reviewing, maintaining, and rolling back commits. When developing in Odoo, the emphasis should be placed on describing the purpose and reasons for making this particular commit. The client wants the following: The PO team wants the following:
Consistent Git practices are helpful in keeping the project neat and organized. Commit messages provide clarity on the reason for a particular change without going through the whole project. While these practices might appear insignificant, sticking to them consistently will go a long way towards ensuring that the project remains of high quality. A neat Git history ensures accountability when making changes to the project.
To read more about The Complete Guide to Odoo Coding Guidelines for Developers, refer to our blog, The Complete Guide to Odoo Coding Guidelines for Developers.