diff --git a/content/contributing/check_mergeability_status.rst b/content/contributing/check_mergeability_status.rst new file mode 100644 index 000000000..1b01b336b --- /dev/null +++ b/content/contributing/check_mergeability_status.rst @@ -0,0 +1 @@ +At the bottom of the page, check the mergeability status and address any issues. diff --git a/content/contributing/configure_git_authorship.rst b/content/contributing/configure_git_authorship.rst new file mode 100644 index 000000000..558ee1dab --- /dev/null +++ b/content/contributing/configure_git_authorship.rst @@ -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” diff --git a/content/contributing/configure_github_account.rst b/content/contributing/configure_github_account.rst new file mode 100644 index 000000000..965b28cae --- /dev/null +++ b/content/contributing/configure_github_account.rst @@ -0,0 +1,2 @@ +`Generate a new SSH key and register it on your GitHub account +`_. diff --git a/content/contributing/create_github_account.rst b/content/contributing/create_github_account.rst new file mode 100644 index 000000000..ad8352474 --- /dev/null +++ b/content/contributing/create_github_account.rst @@ -0,0 +1,3 @@ +First, you need to `create a GitHub account `_. 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. diff --git a/content/contributing/development.rst b/content/contributing/development.rst index 6016fa59c..b874398c6 100644 --- a/content/contributing/development.rst +++ b/content/contributing/development.rst @@ -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 `_ 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 `_ 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 `. 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 `` with the name of the GitHub account + on which you created the fork(s). + + .. code-block:: console + + $ git remote add dev git@github.com:/odoo.git + + If you have access to `odoo/enterprise`, configure the related remote too. + + .. code-block:: console + + $ git remote add dev git@github.com:/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: + +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 ` to fill in the gaps. + - Some steps of this guide require to be comfortable with Git. Here are some `tutorials + `_ and an `interactive training + `_ 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 ` 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 + `_ when working in + another branch than `master`. + - Follow the :doc:`coding guidelines `. + - Test your changes thoroughly and :doc:`write tests ` 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 + `. + + .. 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 `_, or + the `compare page of the odoo/enterprise codebase + `_, depending on which codebase your changes + target. + #. Select **{CURRENT_BRANCH}** for the base. + #. Click on :guilabel:`compare across forks`. + #. Select **/odoo** or **/enterprise** for the head + repository. Replace `` 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! diff --git a/content/contributing/development/coding_guidelines.rst b/content/contributing/development/coding_guidelines.rst index f97e5b818..3227548de 100644 --- a/content/contributing/development/coding_guidelines.rst +++ b/content/contributing/development/coding_guidelines.rst @@ -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 - -- 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
``. 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 diff --git a/content/contributing/development/git_guidelines.rst b/content/contributing/development/git_guidelines.rst new file mode 100644 index 000000000..7ac4202a2 --- /dev/null +++ b/content/contributing/development/git_guidelines.rst @@ -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 + +- 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
``. 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 diff --git a/content/contributing/handle_reviews.rst b/content/contributing/handle_reviews.rst new file mode 100644 index 000000000..7a13f017b --- /dev/null +++ b/content/contributing/handle_reviews.rst @@ -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. diff --git a/content/contributing/install_git.rst b/content/contributing/install_git.rst new file mode 100644 index 000000000..c54658d43 --- /dev/null +++ b/content/contributing/install_git.rst @@ -0,0 +1,20 @@ +`Install 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 + `_ 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 + `_ + with the installation path of Git (by default :file:`C:\\Program Files\\Git`). diff --git a/content/developer/howtos/rdtraining/16_guidelines_pr.rst b/content/developer/howtos/rdtraining/16_guidelines_pr.rst index 2e78c5867..0468370d9 100644 --- a/content/developer/howtos/rdtraining/16_guidelines_pr.rst +++ b/content/developer/howtos/rdtraining/16_guidelines_pr.rst @@ -89,8 +89,8 @@ Commit your code: **Everyone reads your commit messages!** -The commit message is very important, follow the :ref:`Git guidelines -`. +The commit message is very important, follow the :doc:`Git guidelines +`. Push your new branch to your development repository: