189 lines
7.7 KiB
Markdown
189 lines
7.7 KiB
Markdown
---
|
|
show-content: true
|
|
---
|
|
|
|
# Development
|
|
|
|
```{toctree}
|
|
:titlesonly: true
|
|
|
|
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.
|
|
|
|
1. 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.
|
|
|
|
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. 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.
|
|
|
|
4. ```{eval-rst}
|
|
.. include:: install_git.md
|
|
```
|
|
|
|
5. Configure Git to identify yourself as the author of your future contributions. Enter the same
|
|
email address you used to register on GitHub.
|
|
|
|
```console
|
|
$ git config --global user.name "Your Name"
|
|
$ git config --global user.email "youremail@example.com"
|
|
```
|
|
|
|
6. {doc}`Install Odoo from the sources <../administration/on_premise/source>`. Make sure to fetch
|
|
the sources through Git with SSH.
|
|
|
|
7. 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**.
|
|
|
|
```{eval-rst}
|
|
.. 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
|
|
|
|
$ cd /CommunityPath
|
|
$ 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
|
|
|
|
$ cd /EnterprisePath
|
|
$ git remote add dev git@github.com:<your_github_account>/enterprise.git
|
|
|
|
.. tab:: Link Git with odoo-dev
|
|
|
|
.. code-block:: console
|
|
|
|
$ cd /CommunityPath
|
|
$ git remote add dev git@github.com:odoo-dev/odoo.git
|
|
$ git remote set-url --push origin you_should_not_push_on_this_repository
|
|
|
|
$ cd /EnterprisePath
|
|
$ git remote add dev git@github.com:odoo-dev/enterprise.git
|
|
$ git remote set-url --push origin you_should_not_push_on_this_repository
|
|
```
|
|
|
|
8. 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/tutorials>` 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.
|
|
|
|
01. 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/supported_versions>` are not
|
|
accepted. This guide assumes that the changes target Odoo \{CURRENT_VERSION}, which corresponds to
|
|
branch `{CURRENT_BRANCH}`.
|
|
|
|
02. 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`.
|
|
|
|
```{eval-rst}
|
|
.. example::
|
|
|
|
.. code-block:: console
|
|
|
|
$ git switch -c {CURRENT_BRANCH}-fix-invoices
|
|
|
|
.. code-block:: console
|
|
|
|
$ git switch -c {CURRENT_BRANCH}-fix-invoices-xyz
|
|
```
|
|
|
|
03. [Sign the Odoo CLA]({GITHUB_PATH}/doc/cla/sign-cla.md) if not already done. Skip this step if
|
|
you work at Odoo.
|
|
|
|
04. 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.
|
|
|
|
05. Commit your changes. Write a clear commit message as instructed in the {doc}`Git guidelines
|
|
<development/git_guidelines>`.
|
|
|
|
```console
|
|
$ git add .
|
|
$ git commit
|
|
```
|
|
|
|
06. Push your change to your fork, for which we added the remote alias `dev`.
|
|
|
|
```{eval-rst}
|
|
.. example::
|
|
|
|
.. code-block:: console
|
|
|
|
$ git push -u dev {CURRENT_BRANCH}-fix-invoices-xyz
|
|
```
|
|
|
|
07. Open a {abbr}`PR (Pull Request)` on GitHub to submit your changes for review.
|
|
|
|
1. 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.
|
|
2. Select **\{CURRENT_BRANCH}** for the base.
|
|
3. Click on {guilabel}`compare across forks`.
|
|
4. 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.
|
|
5. Review your changes and click on the {guilabel}`Create pull request` button.
|
|
6. Tick the {guilabel}`Allow edits from maintainer` checkbox. Skip this step if you work at Odoo.
|
|
7. Complete the description and click on the {guilabel}`Create pull request` button again.
|
|
|
|
08. At the bottom of the page, check the mergeability status and address any issues.
|
|
|
|
09. As soon as your {abbr}`PR (Pull Request)` is ready for merging, a member of the Odoo team
|
|
is 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.
|
|
|
|
10. Once your changes are approved, the review merges them and they become available for all Odoo
|
|
users after the next code update!
|
|
|