[ADD] contributing/development: add a guide to contribute to the codebase
In addition, this commit extracts the git guidelines from the coding guidelines. This helps link the git guidelines and unclutter the coding guidelines, which should focus on only the programming languages. task-2897123 Part-of: odoo/documentation#3265
This commit is contained in:
Antoine Vandevenne (anv)
parent
ca445c86c8
commit
f778ba89af
1
content/contributing/check_mergeability_status.rst
Normal file
1
content/contributing/check_mergeability_status.rst
Normal file
@ -0,0 +1 @@
|
||||
At the bottom of the page, check the mergeability status and address any issues.
|
||||
7
content/contributing/configure_git_authorship.rst
Normal file
7
content/contributing/configure_git_authorship.rst
Normal file
@ -0,0 +1,7 @@
|
||||
Configure Git to identify yourself as the author of your future contributions. Enter the same email
|
||||
address you used to register on GitHub.
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ git config --global user.name “Your Name”
|
||||
$ git config --global user.email “youremail@example.com”
|
||||
2
content/contributing/configure_github_account.rst
Normal file
2
content/contributing/configure_github_account.rst
Normal file
@ -0,0 +1,2 @@
|
||||
`Generate a new SSH key and register it on your GitHub account
|
||||
<https://docs.github.com/en/authentication/connecting-to-github-with-ssh>`_.
|
||||
3
content/contributing/create_github_account.rst
Normal file
3
content/contributing/create_github_account.rst
Normal file
@ -0,0 +1,3 @@
|
||||
First, you need to `create a GitHub account <https://github.com/join>`_. Odoo uses GitHub to manage
|
||||
the source code of its products, and this is where you will make your changes and submit them for
|
||||
review.
|
||||
@ -1,5 +1,4 @@
|
||||
:nosearch:
|
||||
:hide-page-toc:
|
||||
:show-content:
|
||||
|
||||
===========
|
||||
Development
|
||||
@ -9,3 +8,151 @@ Development
|
||||
:titlesonly:
|
||||
|
||||
development/coding_guidelines
|
||||
development/git_guidelines
|
||||
|
||||
If you are reading this, chances are that you are interested in learning how to contribute to the
|
||||
codebase of Odoo. Whether that's the case or you landed here by accident, we've got you covered!
|
||||
|
||||
.. seealso::
|
||||
:doc:`Discover other ways to contribute to Odoo <../contributing>`
|
||||
|
||||
When you feel ready, jump to the :ref:`contributing/development/setup` section to begin your journey
|
||||
in contributing to the development of Odoo.
|
||||
|
||||
.. _contributing/development/setup:
|
||||
|
||||
Environment setup
|
||||
=================
|
||||
|
||||
The instructions below help you prepare your environment for making local changes to the codebase
|
||||
and then push them to GitHub. Skip this section and go to
|
||||
:ref:`contributing/development/first-contribution` if you have already completed this step.
|
||||
|
||||
#. .. include:: create_github_account.rst
|
||||
#. .. include:: configure_github_account.rst
|
||||
#. Go to `github.com/odoo/odoo <https://github.com/odoo/odoo>`_ and click on the :guilabel:`Fork`
|
||||
button in the top right corner to create a fork (:dfn:`your own copy`) of the repository on your
|
||||
account. Do the same with `github.com/odoo/enterprise <https://github.com/odoo/enterprise>`_ if
|
||||
you have access to it. This creates a copy of the codebase to which you can make changes without
|
||||
affecting the main codebase. Skip this step if you work at Odoo.
|
||||
#. .. include:: install_git.rst
|
||||
#. .. include:: configure_git_authorship.rst
|
||||
#. :ref:`Install Odoo from the sources <setup/install/source>`. Make sure to fetch the sources
|
||||
through Git with SSH.
|
||||
#. Configure Git to push changes to your fork(s) rather than to the main codebase. If you work at
|
||||
Odoo, configure Git to push changes to the shared forks created on the account **odoo-dev**.
|
||||
|
||||
.. tabs::
|
||||
|
||||
.. tab:: Link Git with your fork(s)
|
||||
|
||||
In the command below, replace `<your_github_account>` with the name of the GitHub account
|
||||
on which you created the fork(s).
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ git remote add dev git@github.com:<your_github_account>/odoo.git
|
||||
|
||||
If you have access to `odoo/enterprise`, configure the related remote too.
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ git remote add dev git@github.com:<your_github_account>/enterprise.git
|
||||
|
||||
.. tab:: Link Git with odoo-dev
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ git remote add dev git@github.com:odoo-dev/odoo.git
|
||||
$ git remote set-url --push origin no_push
|
||||
|
||||
$ git remote add dev git@github.com:odoo-dev/enterprise.git
|
||||
$ git remote set-url --push origin no_push
|
||||
|
||||
#. That's it! You are ready to :ref:`make your first contribution
|
||||
<contributing/development/first-contribution>`.
|
||||
|
||||
|
||||
.. _contributing/development/first-contribution:
|
||||
|
||||
Make your first contribution
|
||||
============================
|
||||
|
||||
.. important::
|
||||
- Odoo development can be challenging for beginners. We recommend you to be knowledgeable enough
|
||||
to code a small module before contributing. If that is not the case, take some time to go
|
||||
through the :doc:`developer tutorials </developer/howtos>` to fill in the gaps.
|
||||
- Some steps of this guide require to be comfortable with Git. Here are some `tutorials
|
||||
<https://www.atlassian.com/git/tutorials>`_ and an `interactive training
|
||||
<https://learngitbranching.js.org/>`_ if you are stuck at some point.
|
||||
|
||||
Now that your environment is set up, you can start contributing to the codebase. In a terminal,
|
||||
navigate to the directory where you installed Odoo from sources and follow the guide below.
|
||||
|
||||
#. Choose the version of Odoo to which you want to make changes. Keep in mind that contributions
|
||||
targeting an :doc:`unsupported version of Odoo </administration/maintain/supported_versions>` are
|
||||
not accepted. This guide assumes that the changes target Odoo {CURRENT_VERSION}, which
|
||||
corresponds to branch `{CURRENT_BRANCH}`.
|
||||
#. Create a new branch starting from branch {CURRENT_BRANCH}. Prefix the branch name with the base
|
||||
branch: `{CURRENT_BRANCH}-...`. If you work at Odoo, suffix the branch name with your Odoo
|
||||
handle: `{CURRENT_BRANCH}-...-xyz`.
|
||||
|
||||
.. example::
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ git switch -c {CURRENT_BRANCH}-fix-invoices
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ git switch -c {CURRENT_BRANCH}-fix-invoices-xyz
|
||||
|
||||
#. `Sign the Odoo CLA <{GITHUB_PATH}/doc/cla/sign-cla.md>`_ if not already done. Skip this step if
|
||||
you work at Odoo.
|
||||
#. Make the desired changes to the codebase. When working on the codebase, follow these rules:
|
||||
|
||||
- Keep your changes focused and specific. It is best to work on one particular feature or bug fix
|
||||
at a time rather than tackle multiple unrelated changes simultaneously.
|
||||
- Respect the `stable policy
|
||||
<https://github.com/odoo/odoo/wiki/Contributing#what-does-stable-mean>`_ when working in
|
||||
another branch than `master`.
|
||||
- Follow the :doc:`coding guidelines <development/coding_guidelines>`.
|
||||
- Test your changes thoroughly and :doc:`write tests </developer/reference/backend/testing>` to
|
||||
ensure that everything is working as expected and that there are no regressions or unintended
|
||||
consequences.
|
||||
|
||||
#. Commit your changes. Write a clear commit message as instructed in the :doc:`Git guidelines
|
||||
<development/git_guidelines>`.
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ git add .
|
||||
$ git commit
|
||||
|
||||
#. Push your change to your fork, for which we added the remote alias `dev`.
|
||||
|
||||
.. example::
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ git push -u dev {CURRENT_BRANCH}-fix-invoices-xyz
|
||||
|
||||
#. Open a :abbr:`PR (Pull Request)` on GitHub to submit your changes for review.
|
||||
|
||||
#. Go to the `compare page of the odoo/odoo codebase <https://github.com/odoo/odoo/compare>`_, or
|
||||
the `compare page of the odoo/enterprise codebase
|
||||
<https://github.com/odoo/enterprise/compare>`_, depending on which codebase your changes
|
||||
target.
|
||||
#. Select **{CURRENT_BRANCH}** for the base.
|
||||
#. Click on :guilabel:`compare across forks`.
|
||||
#. Select **<your_github_account>/odoo** or **<your_github_account>/enterprise** for the head
|
||||
repository. Replace `<your_github_account>` with the name of the GitHub account on which you
|
||||
created the fork or by **odoo-dev** if you work at Odoo.
|
||||
#. Review your changes and click on the :guilabel:`Create pull request` button.
|
||||
#. Tick the :guilabel:`Allow edits from maintainer` checkbox. Skip this step if you work at Odoo.
|
||||
#. Complete the description and click on the :guilabel:`Create pull request` button again.
|
||||
|
||||
#. .. include:: check_mergeability_status.rst
|
||||
#. .. include:: handle_reviews.rst
|
||||
#. Once your changes are approved, the review merges them and they become available for all Odoo
|
||||
users after the next code update!
|
||||
|
||||
@ -1,8 +1,7 @@
|
||||
|
||||
.. highlight:: python
|
||||
|
||||
=================
|
||||
Coding Guidelines
|
||||
Coding guidelines
|
||||
=================
|
||||
|
||||
This page introduces the Odoo Coding Guidelines. Those aim to improve the
|
||||
@ -981,147 +980,3 @@ CSS coding guidelines
|
||||
- Avoid using *id* tag
|
||||
- Use Bootstrap native classes
|
||||
- Use underscore lowercase notation to name class
|
||||
|
||||
.. _contributing/development/git_guidelines:
|
||||
|
||||
Git
|
||||
===
|
||||
|
||||
Configure your git
|
||||
------------------
|
||||
|
||||
Based on ancestral experience and oral tradition, the following things go a long
|
||||
way towards making your commits more helpful:
|
||||
|
||||
- Be sure to define both the user.email and user.name in your local git config
|
||||
|
||||
.. code-block:: text
|
||||
|
||||
git config --global <var> <value>
|
||||
|
||||
- Be sure to add your full name to your Github profile here. Please feel fancy
|
||||
and add your team, avatar, your favorite quote, and whatnot ;-)
|
||||
|
||||
Commit message structure
|
||||
------------------------
|
||||
|
||||
Commit message has four parts: tag, module, short description and full
|
||||
description. Try to follow the preferred structure for your commit messages
|
||||
|
||||
.. code-block:: text
|
||||
|
||||
[TAG] module: describe your change in a short sentence (ideally < 50 chars)
|
||||
|
||||
Long version of the change description, including the rationale for the change,
|
||||
or a summary of the feature being introduced.
|
||||
|
||||
Please spend a lot more time describing WHY the change is being done rather
|
||||
than WHAT is being changed. This is usually easy to grasp by actually reading
|
||||
the diff. WHAT should be explained only if there are technical choices
|
||||
or decision involved. In that case explain WHY this decision was taken.
|
||||
|
||||
End the message with references, such as task or bug numbers, PR numbers, and
|
||||
OPW tickets, following the suggested format:
|
||||
task-123 (related to task)
|
||||
Fixes #123 (close related issue on Github)
|
||||
Closes #123 (close related PR on Github)
|
||||
opw-123 (related to ticket)
|
||||
|
||||
Tag and module name
|
||||
-------------------
|
||||
|
||||
Tags are used to prefix your commit. They should be one of the following
|
||||
|
||||
- **[FIX]** for bug fixes: mostly used in stable version but also valid if you
|
||||
are fixing a recent bug in development version;
|
||||
- **[REF]** for refactoring: when a feature is heavily rewritten;
|
||||
- **[ADD]** for adding new modules;
|
||||
- **[REM]** for removing resources: removing dead code, removing views,
|
||||
removing modules, ...;
|
||||
- **[REV]** for reverting commits: if a commit causes issues or is not wanted
|
||||
reverting it is done using this tag;
|
||||
- **[MOV]** for moving files: use git move and do not change content of moved file
|
||||
otherwise Git may loose track and history of the file; also used when moving
|
||||
code from one file to another;
|
||||
- **[REL]** for release commits: new major or minor stable versions;
|
||||
- **[IMP]** for improvements: most of the changes done in development version
|
||||
are incremental improvements not related to another tag;
|
||||
- **[MERGE]** for merge commits: used in forward port of bug fixes but also as
|
||||
main commit for feature involving several separated commits;
|
||||
- **[CLA]** for signing the Odoo Individual Contributor License;
|
||||
- **[I18N]** for changes in translation files;
|
||||
|
||||
After tag comes the modified module name. Use the technical name as functional
|
||||
name may change with time. If several modules are modified, list them or use
|
||||
various to tell it is cross-modules. Unless really required or easier avoid
|
||||
modifying code across several modules in the same commit. Understanding module
|
||||
history may become difficult.
|
||||
|
||||
Commit message header
|
||||
---------------------
|
||||
|
||||
After tag and module name comes a meaningful commit message header. It should be
|
||||
self explanatory and include the reason behind the change. Do not use single words
|
||||
like "bugfix" or "improvements". Try to limit the header length to about 50 characters
|
||||
for readability.
|
||||
|
||||
Commit message header should make a valid sentence once concatenated with
|
||||
``if applied, this commit will <header>``. For example ``[IMP] base: prevent to
|
||||
archive users linked to active partners`` is correct as it makes a valid sentence
|
||||
``if applied, this commit will prevent users to archive...``.
|
||||
|
||||
Commit message full description
|
||||
-------------------------------
|
||||
|
||||
In the message description specify the part of the code impacted by your changes
|
||||
(module name, lib, transversal object, ...) and a description of the changes.
|
||||
|
||||
First explain WHY you are modifying code. What is important if someone goes back
|
||||
to your commit in about 4 decades (or 3 days) is why you did it. It is the
|
||||
purpose of the change.
|
||||
|
||||
What you did can be found in the commit itself. If there was some technical choices
|
||||
involved it is a good idea to explain it also in the commit message after the why.
|
||||
For Odoo R&D developers "PO team asked me to do it" is not a valid why, by the way.
|
||||
|
||||
Please avoid commits which simultaneously impact multiple modules. Try to split
|
||||
into different commits where impacted modules are different. It will be helpful
|
||||
if we need to revert changes in a given module separately.
|
||||
|
||||
Don't hesitate to be a bit verbose. Most people will only see your commit message
|
||||
and judge everything you did in your life just based on those few sentences.
|
||||
No pressure at all.
|
||||
|
||||
**You spend several hours, days or weeks working on meaningful features. Take
|
||||
some time to calm down and write clear and understandable commit messages.**
|
||||
|
||||
If you are an Odoo R&D developer the WHY should be the purpose of the task you
|
||||
are working on. Full specifications make the core of the commit message.
|
||||
**If you are working on a task that lacks purpose and specifications please
|
||||
consider making them clear before continuing.**
|
||||
|
||||
Finally here are some examples of correct commit messages :
|
||||
|
||||
.. code-block:: text
|
||||
|
||||
[REF] models: use `parent_path` to implement parent_store
|
||||
|
||||
This replaces the former modified preorder tree traversal (MPTT) with the
|
||||
fields `parent_left`/`parent_right`[...]
|
||||
|
||||
[FIX] account: remove frenglish
|
||||
|
||||
[...]
|
||||
|
||||
Closes #22793
|
||||
Fixes #22769
|
||||
|
||||
[FIX] website: remove unused alert div, fixes look of input-group-btn
|
||||
|
||||
Bootstrap's CSS depends on the input-group-btn
|
||||
element being the first/last child of its parent.
|
||||
This was not the case because of the invisible
|
||||
and useless alert.
|
||||
|
||||
.. note:: Use the long description to explain the *why* not the
|
||||
*what*, the *what* can be seen in the diff
|
||||
|
||||
142
content/contributing/development/git_guidelines.rst
Normal file
142
content/contributing/development/git_guidelines.rst
Normal file
@ -0,0 +1,142 @@
|
||||
=================
|
||||
Git guidelines
|
||||
=================
|
||||
|
||||
Configure your git
|
||||
------------------
|
||||
|
||||
Based on ancestral experience and oral tradition, the following things go a long
|
||||
way towards making your commits more helpful:
|
||||
|
||||
- Be sure to define both the user.email and user.name in your local git config
|
||||
|
||||
.. code-block:: text
|
||||
|
||||
git config --global <var> <value>
|
||||
|
||||
- Be sure to add your full name to your Github profile here. Please feel fancy
|
||||
and add your team, avatar, your favorite quote, and whatnot ;-)
|
||||
|
||||
Commit message structure
|
||||
------------------------
|
||||
|
||||
Commit message has four parts: tag, module, short description and full
|
||||
description. Try to follow the preferred structure for your commit messages
|
||||
|
||||
.. code-block:: text
|
||||
|
||||
[TAG] module: describe your change in a short sentence (ideally < 50 chars)
|
||||
|
||||
Long version of the change description, including the rationale for the change,
|
||||
or a summary of the feature being introduced.
|
||||
|
||||
Please spend a lot more time describing WHY the change is being done rather
|
||||
than WHAT is being changed. This is usually easy to grasp by actually reading
|
||||
the diff. WHAT should be explained only if there are technical choices
|
||||
or decision involved. In that case explain WHY this decision was taken.
|
||||
|
||||
End the message with references, such as task or bug numbers, PR numbers, and
|
||||
OPW tickets, following the suggested format:
|
||||
task-123 (related to task)
|
||||
Fixes #123 (close related issue on Github)
|
||||
Closes #123 (close related PR on Github)
|
||||
opw-123 (related to ticket)
|
||||
|
||||
Tag and module name
|
||||
-------------------
|
||||
|
||||
Tags are used to prefix your commit. They should be one of the following
|
||||
|
||||
- **[FIX]** for bug fixes: mostly used in stable version but also valid if you
|
||||
are fixing a recent bug in development version;
|
||||
- **[REF]** for refactoring: when a feature is heavily rewritten;
|
||||
- **[ADD]** for adding new modules;
|
||||
- **[REM]** for removing resources: removing dead code, removing views,
|
||||
removing modules, ...;
|
||||
- **[REV]** for reverting commits: if a commit causes issues or is not wanted
|
||||
reverting it is done using this tag;
|
||||
- **[MOV]** for moving files: use git move and do not change content of moved file
|
||||
otherwise Git may loose track and history of the file; also used when moving
|
||||
code from one file to another;
|
||||
- **[REL]** for release commits: new major or minor stable versions;
|
||||
- **[IMP]** for improvements: most of the changes done in development version
|
||||
are incremental improvements not related to another tag;
|
||||
- **[MERGE]** for merge commits: used in forward port of bug fixes but also as
|
||||
main commit for feature involving several separated commits;
|
||||
- **[CLA]** for signing the Odoo Individual Contributor License;
|
||||
- **[I18N]** for changes in translation files;
|
||||
|
||||
After tag comes the modified module name. Use the technical name as functional
|
||||
name may change with time. If several modules are modified, list them or use
|
||||
various to tell it is cross-modules. Unless really required or easier avoid
|
||||
modifying code across several modules in the same commit. Understanding module
|
||||
history may become difficult.
|
||||
|
||||
Commit message header
|
||||
---------------------
|
||||
|
||||
After tag and module name comes a meaningful commit message header. It should be
|
||||
self explanatory and include the reason behind the change. Do not use single words
|
||||
like "bugfix" or "improvements". Try to limit the header length to about 50 characters
|
||||
for readability.
|
||||
|
||||
Commit message header should make a valid sentence once concatenated with
|
||||
``if applied, this commit will <header>``. For example ``[IMP] base: prevent to
|
||||
archive users linked to active partners`` is correct as it makes a valid sentence
|
||||
``if applied, this commit will prevent users to archive...``.
|
||||
|
||||
Commit message full description
|
||||
-------------------------------
|
||||
|
||||
In the message description specify the part of the code impacted by your changes
|
||||
(module name, lib, transversal object, ...) and a description of the changes.
|
||||
|
||||
First explain WHY you are modifying code. What is important if someone goes back
|
||||
to your commit in about 4 decades (or 3 days) is why you did it. It is the
|
||||
purpose of the change.
|
||||
|
||||
What you did can be found in the commit itself. If there was some technical choices
|
||||
involved it is a good idea to explain it also in the commit message after the why.
|
||||
For Odoo R&D developers "PO team asked me to do it" is not a valid why, by the way.
|
||||
|
||||
Please avoid commits which simultaneously impact multiple modules. Try to split
|
||||
into different commits where impacted modules are different. It will be helpful
|
||||
if we need to revert changes in a given module separately.
|
||||
|
||||
Don't hesitate to be a bit verbose. Most people will only see your commit message
|
||||
and judge everything you did in your life just based on those few sentences.
|
||||
No pressure at all.
|
||||
|
||||
**You spend several hours, days or weeks working on meaningful features. Take
|
||||
some time to calm down and write clear and understandable commit messages.**
|
||||
|
||||
If you are an Odoo R&D developer the WHY should be the purpose of the task you
|
||||
are working on. Full specifications make the core of the commit message.
|
||||
**If you are working on a task that lacks purpose and specifications please
|
||||
consider making them clear before continuing.**
|
||||
|
||||
Finally here are some examples of correct commit messages :
|
||||
|
||||
.. code-block:: text
|
||||
|
||||
[REF] models: use `parent_path` to implement parent_store
|
||||
|
||||
This replaces the former modified preorder tree traversal (MPTT) with the
|
||||
fields `parent_left`/`parent_right`[...]
|
||||
|
||||
[FIX] account: remove frenglish
|
||||
|
||||
[...]
|
||||
|
||||
Closes #22793
|
||||
Fixes #22769
|
||||
|
||||
[FIX] website: remove unused alert div, fixes look of input-group-btn
|
||||
|
||||
Bootstrap's CSS depends on the input-group-btn
|
||||
element being the first/last child of its parent.
|
||||
This was not the case because of the invisible
|
||||
and useless alert.
|
||||
|
||||
.. note:: Use the long description to explain the *why* not the
|
||||
*what*, the *what* can be seen in the diff
|
||||
4
content/contributing/handle_reviews.rst
Normal file
4
content/contributing/handle_reviews.rst
Normal file
@ -0,0 +1,4 @@
|
||||
As soon as your :abbr:`PR (Pull Request)` is ready for merging, a member of the Odoo team will be
|
||||
automatically assigned for review. If the reviewer has questions or remarks, they will post them as
|
||||
comments and you will be notified by email. Those comments must be resolved for the contribution to
|
||||
go forward.
|
||||
20
content/contributing/install_git.rst
Normal file
20
content/contributing/install_git.rst
Normal file
@ -0,0 +1,20 @@
|
||||
`Install Git <https://git-scm.com/book/en/v2/Getting-Started-Installing-Git>`_. It is a command-line
|
||||
(:dfn:`a text interface`) tool that allows tracking the history of changes made to a file and, more
|
||||
importantly, working on different versions of that file simultaneously. It means you do not need to
|
||||
worry about overwriting someone else’s pending work when making changes.
|
||||
|
||||
Verify that the installation directory of Git is included in your system's `PATH` variable.
|
||||
|
||||
.. tabs::
|
||||
|
||||
.. group-tab:: Linux and macOS
|
||||
|
||||
Follow the `guide to update the PATH variable on Linux and macOS
|
||||
<https://unix.stackexchange.com/a/26059>`_ with the installation path of Git (by default
|
||||
:file:`/usr/bin/git`).
|
||||
|
||||
.. group-tab:: Windows
|
||||
|
||||
Follow the `guide to update the PATH variable on Windows
|
||||
<https://www.howtogeek.com/118594/how-to-edit-your-system-path-for-easy-command-line-access/>`_
|
||||
with the installation path of Git (by default :file:`C:\\Program Files\\Git`).
|
||||
@ -89,8 +89,8 @@ Commit your code:
|
||||
|
||||
**Everyone reads your commit messages!**
|
||||
|
||||
The commit message is very important, follow the :ref:`Git guidelines
|
||||
<contributing/development/git_guidelines>`.
|
||||
The commit message is very important, follow the :doc:`Git guidelines
|
||||
</contributing/development/git_guidelines>`.
|
||||
|
||||
|
||||
Push your new branch to your development repository:
|
||||
|
||||
Loading…
Reference in New Issue
Block a user