[IMP] tutorials/getting_started: rework the environment setup guide

This commit replaces a big chunk of the instructions relative to the
environment setup with a reference to the equivalent steps listed in the
contribution guide. It also moves the content of the "Create your first
PR" section from chapter 16 to chapter 2, as readers were struggling
with the Git configuration required to push their work to GitHub as they
progressed through the tutorial.

closes odoo/documentation#4413

X-original-commit: 26e12696c1
Signed-off-by: Antoine Vandevenne (anv) <anv@odoo.com>
This commit is contained in:
Antoine Vandevenne (anv) 2023-05-09 16:01:35 +00:00
parent bf294f37cc
commit fd933208d3
12 changed files with 105 additions and 325 deletions

View File

@ -67,16 +67,15 @@ and then push them to GitHub. Skip this section and go to
$ cd /CommunityPath
$ git remote add dev git@github.com:odoo-dev/odoo.git
$ git remote set-url --push origin no_push
$ 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 no_push
$ git remote set-url --push origin you_should_not_push_on_this_repository
#. That's it! You are ready to :ref:`make your first contribution
<contributing/development/first-contribution>`.
.. _contributing/development/first-contribution:
Make your first contribution

View File

@ -44,4 +44,4 @@ Ready? Let's get started!
* :doc:`getting_started/13_inheritance`
* :doc:`getting_started/14_other_module`
* :doc:`getting_started/15_qwebintro`
* :doc:`getting_started/16_guidelines_pr`
* :doc:`getting_started/16_final_word`

View File

@ -2,155 +2,65 @@
Chapter 2: Development environment setup
========================================
Depending on the intended use case, there are multiple ways to install Odoo. This tutorial will
stick to the :ref:`source install <setup/install/source>` (:dfn:`running Odoo from the source
code`), which is best suited for Odoo developers.
Depending on the intended use case, there are multiple ways to install Odoo. For developers of the
Odoo community and Odoo employees alike, the preferred way is to perform a source install
(:dfn:`running Odoo from the source code`).
Throughout this document, we assume that you are installing your development environment on a
laptop provided by Odoo with Linux Mint installed and up-to-date. If that is not the case, select
the :guilabel:`Windows` or :guilabel:`Mac OS` tab in any section of the installation guide,
depending on which OS you are on. The steps remain essentially the same.
Prepare the environment
=======================
Set up Git
==========
First, follow the :ref:`contributing/development/setup` section of the contributing guide to prepare
your environment.
Install and configure Git
-------------------------
.. important::
The following steps are intended only for Odoo employees. The mentioned repositories are not
accessible to third parties.
The very first step of the installation process is to install the `Git version control system
<https://git-scm.com/>`_ because the Odoo source code is managed on `GitHub <https://github.com/>`_.
By now, you should have downloaded the source code into two local repositories, one for `odoo/odoo`
and one for `odoo/enterprise`. These repositories are set up to push changes to pre-defined shared
forks on GitHub. This will prove to be convenient when you start contributing to the codebase, but
for the scope of this tutorial, we want to avoid polluting the shared repositories with training
material. Let's then develop your own module in a third repository `technical-training-sandbox`.
Like the first two repositories, it will be part of the `addons-path` that references all
directories containing Odoo modules.
.. code-block:: console
$ sudo apt install git
.. tip::
Check if Git is installed by trying to print Git's version with the following command:
#. Following the same process as with the `odoo/odoo` and `odoo/enterprise` repositories, visit
`github.com/odoo/technical-training-sandbox
<https://github.com/odoo/technical-training-sandbox>`_ and click the :guilabel:`Fork` button to
create a fork of the repository under your account.
#. Clone the repository on your machine with:
.. code-block:: console
$ git --version
$ git clone git@github.com:odoo/technical-training-sandbox.git
Once installed, register your name and email:
#. Configure the repository to push changes to your fork:
.. code-block:: console
.. code-block:: console
$ git config --global user.name "Your full name (trigram)"
$ git config --global user.email "xyz@odoo.com"
$ cd technical-training-sandbox/
$ git remote add dev git@github.com:<your_github_account>/technical-training-sandbox.git
$ git remote set-url --push origin you_should_not_push_on_this_repository
Configure GitHub
----------------
That's it! Your environment is now prepared to run Odoo from the sources, and you have successfully
created a repository to serve as an addons directory. This will allow you to push your work to
GitHub.
You need a GitHub account to fetch the sources and contribute to Odoo's development. If you don't
have one yet, create it. For the username, we recommend using your trigram "xyz" (or quadrigam)
followed by '-odoo': 'xyz-odoo'.
Now, make a small change in the `technical-training-sandbox` repository, such as updating the
:file:`README.md` file. Then, follow the :ref:`contributing/development/first-contribution` section
of the contributing guide to push your changes to GitHub and create a :abbr:`PR (Pull Request)`.
This will enable you to share your upcoming work and receive feedback. Adjust the instructions to
use the branch `master` and the repository `technical-training-sandbox`.
The easiest way to authenticate with GitHub is to use an SSH connection. Using SSH authentication
allows you to connect to GitHub without supplying your username and password every time you type a
command.
To ensure a continuous feedback loop, we recommend pushing a new commit as soon as you reach a new
milestone, such as completing a chapter of the tutorial.
.. note::
The following step-by-step procedure is based on the `official GitHub documentation
<https://docs.github.com/en/authentication/connecting-to-github-with-ssh>`_.
#. Generate a new SSH key, add it to the ssh-agent, and copy the SSH key to your clipboard.
.. code-block:: console
$ ssh-keygen -t ed25519 -C "xyz@odoo.com"
$ ssh-add ~/.ssh/id_ed25519
$ sudo apt install xclip
$ xclip -sel clip < ~/.ssh/id_ed25519.pub
#. Go to `GitHub.com <https://github.com/>`_, then click on your profile picture in the upper-right
corner of the page and then on :guilabel:`Settings`.
.. image:: 02_setup/account-settings.png
#. On the user settings sidebar, click on :guilabel:`SSH and GPG keys`.
.. image:: 02_setup/settings-sidebar-ssh-keys.png
#. Click on :guilabel:`New SSH key` or on :guilabel:`Add SSH key`.
.. image:: 02_setup/ssh-add-ssh-key.png
#. In the :guilabel:`Title` field, add a descriptive label for the new key.
#. Paste your key into the :guilabel:`Key` field.
.. image:: 02_setup/ssh-key-paste.png
#. Click on :guilabel:`Add SSH key`.
Fetch the sources
=================
It is time to fetch the source code of Odoo. First, let's create a home for the Git repositories in
:file:`$HOME/src/`.
.. code-block:: console
$ mkdir -p $HOME/src
$ cd $HOME/src
Then, clone the two repositories with SSH as explained in the :ref:`Installing Odoo guide
<setup/install/source/git>`.
.. tip::
Cloning the repositories will take a while, enjoy a cup of coffee while you wait.
.. _tutorials/getting_started/02_setup/development_repository:
Configure the Git repositories
==============================
To contribute to an Odoo repository, you first need to `fork it
<https://docs.github.com/en/get-started/quickstart/contributing-to-projects>`_, then create a branch
containing your changes on the fork, and finally submit a `Pull Request
<https://docs.github.com/en/get-started/quickstart/github-glossary#pull-request>`_ to the
repository.
.. tip::
If you are lucky enough to work at Odoo, the forks already exist. They are hosted on
https://github.com/odoo-dev/odoo and https://github.com/odoo-dev/enterprise.
After your two forks are created, their remote address can be added in your local repositories. In
the commands below, replace `odoo-dev/odoo` and `odoo-dev/enterprise` with the name of your forks if
needed.
.. code-block:: console
$ cd $HOME/src/odoo
$ git remote add odoo-dev git@github.com:odoo-dev/odoo.git # Add odoo-dev as a new remote.
$ git remote rename origin odoo # Change the name of origin (the odoo repository) to odoo.
$ git remote set-url --push odoo no_push # Remove the possibility to push directly to odoo (you can only push to odoo-dev).
$ cd $HOME/src/enterprise
$ git remote add enterprise-dev git@github.com:odoo-dev/enterprise.git
$ git remote rename origin enterprise
$ git remote set-url --push enterprise no_push
Install the dependencies
========================
As seen in :ref:`tutorials/getting_started/01_architecture`, Odoo's server runs on Python and uses
PostgreSQL as an RDBMS. In the context of a development machine, the easiest approach is to install
everything locally. To do so, follow once again the :ref:`Installing Odoo guide
<setup/install/source/prepare>`.
.. tip::
Some useful SQL commands:
.. code-block:: console
$ createdb $DB_NAME # Create a database.
$ dropdb $DB_NAME # Drop a database.
$ psql $DB_NAME # Connect to a database.
\l #List all the available databases.
\dt #List all the tables of the $DB_NAME database.
\d $TABLE_NAME #Show the structure of the table $TABLE_NAME.
\q #Quit the psql environment (ctrl + d).
The specific location of the repositories on your file system is not crucial. However, for the
sake of simplicity, we will assume that you have cloned all the repositories under the same
directory. If this is not the case, make sure to adjust the following commands accordingly,
providing the appropriate relative path from the `odoo/odoo` repository to the
`odoo/technical-training-sandbox` repository.
Run the server
==============
@ -164,7 +74,7 @@ interface of the server.
.. code-block:: console
$ cd $HOME/src/odoo/
$ ./odoo-bin --addons-path="addons/,../enterprise/" -d rd-demo
$ ./odoo-bin --addons-path="addons/,../enterprise/,../technical-training-sandbox" -d rd-demo
There are multiple :ref:`command-line arguments <reference/cmdline/server>` that you can use to run
the server. In this training you will only need some of them.

View File

@ -56,9 +56,8 @@ Prepare the addon directory
:align: center
:alt: The new module appears in the list
The first step of module creation is to create a new directory. To ease the development, we
suggest you first create the directory ``/home/$USER/src/custom``. In this directory we add
another directory ``estate``, which is our module.
The first step of module creation is to create its directory. In the `technical-training-sandbox`
directory, add a new directory :file:`estate`.
A module must contain at least 2 files: the ``__manifest__.py`` file and a ``__init__.py`` file.
The ``__init__.py`` file can remain empty for now and we'll come back to it in the next chapter.
@ -78,21 +77,15 @@ be uninstalled**. Think about your favorite Linux distribution package manager
Create the following folders and files:
- ``/home/$USER/src/custom/estate/__init__.py``
- ``/home/$USER/src/custom/estate/__manifest__.py``
- ``/home/$USER/src/technical-training-sandbox/estate/__init__.py``
- ``/home/$USER/src/technical-training-sandbox/estate/__manifest__.py``
The ``__manifest__.py`` file should only define the name and the dependencies of our modules.
The only necessary framework module for now is ``base``.
Restart the Odoo server and add the ``custom`` folder to the ``addons-path``:
.. code-block:: console
$ ./odoo-bin --addons-path=../custom,../enterprise/,addons
Go to Apps, click on Update Apps List, search for ``estate`` and... tadaaa, your module appears!
Did it not appear? Maybe try removing the default 'Apps' filter ;-)
Restart the Odoo server and go to Apps. Click on Update Apps List, search for ``estate`` and...
tadaaa, your module appears! Did it not appear? Maybe try removing the default 'Apps' filter ;-)
.. warning::
Remember to enable the :ref:`developer mode <developer-mode>` as explained in the previous

View File

@ -87,7 +87,7 @@ the server, we will add the parameters ``-d`` and ``-u``:
.. code-block:: console
$ ./odoo-bin --addons-path=../custom,../enterprise/,addons -d rd-demo -u estate
$ ./odoo-bin --addons-path=addons,../enterprise/,../technical-training-sandbox/ -d rd-demo -u estate
``-u estate`` means we want to upgrade the ``estate`` module, i.e. the ORM will
apply database schema changes. In this case it creates a new table. ``-d rd-demo`` means
@ -211,7 +211,7 @@ When the fields are added to the model, restart the server with ``-u estate``
.. code-block:: console
$ ./odoo-bin --addons-path=../custom,../enterprise/,addons -d rd-demo -u estate
$ ./odoo-bin --addons-path=addons,../enterprise/,../technical-training-sandbox/ -d rd-demo -u estate
Connect to ``psql`` and check the structure of the table ``estate_property``. You'll notice that
a couple of extra fields were also added to the table. We will revisit them later.

View File

@ -126,7 +126,7 @@ be convenient to use the ``--dev xml`` parameter when launching the server:
.. code-block:: console
$ ./odoo-bin --addons-path=../custom,../enterprise/,addons -d rd-demo -u estate --dev xml
$ ./odoo-bin --addons-path=addons,../enterprise/,../technical-training-sandbox/ -d rd-demo -u estate --dev xml
This parameter allows you to just refresh the page to view your view modifications.

View File

@ -124,10 +124,6 @@ Kanban views are a typical example of how it is always a good idea to start from
view and fine tune it instead of starting from scratch. There are many options and classes
available, so... read and learn!
It is now time to add the
:ref:`final touches to our application and submit it on GitHub
<tutorials/getting_started/16_guidelines_pr>`!
.. _templating:
https://en.wikipedia.org/wiki/Template_processor
.. _kanban board:

View File

@ -0,0 +1,32 @@
.. _tutorials/getting_started/16_final_word:
==========================
Chapter 16: The final word
==========================
Coding guidelines
=================
We will start refactoring the code to match to the Odoo coding guidelines. The guidelines aim
to improve the quality of the Odoo Apps code.
**Reference**: you will find the Odoo coding guidelines in
:doc:`/contributing/development/coding_guidelines`.
.. exercise:: Polish your code.
Refactor your code to respect the coding guidelines. Don't forget to run your linter and
respect the module structure, the variable names, the method name convention, the model
attribute order and the xml ids.
Test on the runbot
==================
Odoo has its own :abbr:`CI (Continuous integration)` server named `runbot <https://runbot.odoo.com/>`__. All
commits, branches and PR will be tested to avoid regressions or breaking of the stable versions.
All the runs that pass the tests are deployed on their own server with demo data.
.. exercise:: Play with the runbot.
Feel free to go to the runbot website and open the last stable version of Odoo to check out all the available
applications and functionalities.

View File

@ -1,154 +0,0 @@
.. _tutorials/getting_started/16_guidelines_pr:
===============================================
Chapter 16: Polish Your Code And Submit Your PR
===============================================
In the previous chapters we saw how to create a fully functional business application. Now we will
prepare our code to be shared and learn how to share it.
Coding guidelines
=================
We will start refactoring the code to match to the Odoo coding guidelines. The guidelines aim
to improve the quality of the Odoo Apps code.
**Reference**: you will find the Odoo coding guidelines in
:doc:`/contributing/development/coding_guidelines`.
.. exercise:: Polish your code.
Refactor your code to respect the coding guidelines. Don't forget to run your linter and
respect the module structure, the variable names, the method name convention, the model
attribute order and the xml ids.
Your first Pull Request (PR)
============================
**The following is intended to be used by Odoo staff members only. All repositories mentioned are
not accessible for third-parties.**
Now that your code respects the Odoo code guidelines and is polished up, let's share it with others.
Configure development repository
--------------------------------
We will start by creating a git development environment for the 'custom' folder, like we did in the
beginning for 'odoo' and 'enterprise'. The PR will target the `odoo/technical-training-sandbox` repository.
To do this the first step is to
`fork <https://guides.github.com/activities/forking/>`__ in GitHub
`this repository <https://github.com/odoo/technical-training-sandbox/>`__
to create your own development repository.
After you successfully created your development repository, we will configure your existing `$HOME/src/custom`
folder to be able to commit your work.
.. code-block:: console
$ cd $HOME/src/custom
$ git init
$ git remote add training git@github.com:odoo/technical-training-sandbox.git
$ git remote add training-dev git@github.com:xyz-odoo/technical-training-sandbox.git #Don't forget to change xyz-odoo to your own GitHub account
$ git remote set-url --push training no_push #Avoid pushing directly into the main repository
$ git fetch training master
$ git branch master training/master
$ git checkout master #Two new files will be downloaded README.md and .gitignore
Note that if your work is already in a :ref:`Git and GitHub configured folder
<tutorials/getting_started/02_setup/development_repository>` the previous steps are not needed. This
is the case when you start working in the 'odoo' or 'enterprise' folders.
Branch, Commit & Push
---------------------
Before creating the PR, a new working branch has to be created and used to commit the code. Afterwards
the branch will be pushed to the development repository.
Create your working branch:
.. code-block:: console
$ git checkout -b master-my_first_branch-xyz
Your branch name must follow the following name structure : <targetVersion>-<feature>-<trigram>
Example: The branch master-sale-fixes-abc on odoo-dev/odoo is a branch containing fixes for the
sales app in the odoo/odoo repository, to be deployed in master and done by ABC.
Commit your code:
.. code-block:: console
$ git add .
$ git commit
**Everyone reads your commit messages!**
The commit message is very important, follow the :doc:`Git guidelines
</contributing/development/git_guidelines>`.
Push your new branch to your development repository:
.. code-block:: console
$ git push -u training-dev master-my_first_branch-xyz
.. warning:: NEVER use `git push --force` (or `git push -f`) with a branch that does not belong to you
or in a stable branch. Never, never, never!
.. tip:: Remember that you can use `git status` at any point to check the current status of your branch
.. tip:: You can create git aliases to shorten some of these commands. Ask your colleagues
if they use git aliases and get inspired by their work.
Create your first PR
--------------------
After pushing your branch to your development repository you will see an output similar to:
.. code-block:: console
Enumerating objects: 24, done.
Counting objects: 100% (24/24), done.
Compressing objects: 100% (20/20), done.
Writing objects: 100% (23/23), 6.67 KiB | 525.00 KiB/s, done.
Total 23 (delta 1), reused 0 (delta 0)
remote: Resolving deltas: 100% (1/1), done.
remote:
remote: Create a pull request for 'master-my_first_branch-xyz' on GitHub by visiting:
remote: https://github.com/xyz-odoo/technical-training-sandbox/pull/new/master-my_first_branch-xyz
remote:
To github.com:xyz-odoo/technical-training-sandbox.git
* [new branch] master-my_first_branch-xyz -> master-my_first_branch-xyz
Branch 'master-my_first_branch-xyz' set up to track remote branch 'master-my_first_branch-xyz' from 'training-dev'.
There are two ways to create the PR:
- Click on the link displayed in the output of the push command.
- Open a browser in your development repository `https://github.com/xyz-odoo/technical-training-sandbox`.
There will be a button to create a new pull request.
.. image:: 16_guidelines_pr/pr_from_branch.png
You will notice that your commit message is used as the pull request message. This occurs if you have only 1 commit.
If you have multiple commits, you can either make a summary of the commits as the PR message or if there aren't that many
commits you can just copy/paste your commit messages as the PR message.
.. image:: 16_guidelines_pr/pr_message.png
Test on the runbot
==================
Odoo has its own :abbr:`CI (Continuous integration)` server named `runbot <https://runbot.odoo.com/>`__. All
commits, branches and PR will be tested to avoid regressions or breaking of the stable versions.
All the runs that pass the tests are deployed on their own server with demo data.
.. exercise:: Play with the runbot.
Feel free to go to the runbot website and open the last stable version of Odoo to check out all the available
applications and functionalities.

Binary file not shown.

Before

Width:  |  Height:  |  Size: 46 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 126 KiB

View File

@ -55,6 +55,12 @@ applications/inventory_and_mrp/inventory/management/incoming/two_steps.rst appli
applications/inventory_and_mrp/inventory/management/replenishment_strategies/virtual_warehouses.rst applications/inventory_and_mrp/inventory/management/warehouses/warehouse_replenishment_transfer.rst
applications/inventory_and_mrp/inventory/routes/concepts/inter_warehouse.rst applications/inventory_and_mrp/inventory/management/warehouses/warehouse_replenishment_transfer.rst
# applications/marketing
applications/marketing/social_marketing/overview/livechat.rst applications/marketing/social_marketing/essentials/sms_essentials.rst
applications/marketing/social_marketing/overview/push_notifications.rst applications/marketing/social_marketing/essentials/sms_essentials.rst
applications/marketing/social_marketing/overview/create_posts.rst applications/marketing/social_marketing/essentials/sms_essentials.rst
# applications/sales
applications/sales/crm/acquire_leads/generate_from_email.rst applications/sales/crm/acquire_leads/generate_leads.rst # (#986)
@ -87,6 +93,13 @@ applications/services/fsm.rst applications/services/field_service.rst
applications/services/fsm/helpdesk/plan_onsite.rst applications/services/field_service/onsite_interventions.rst # fsm/helpdesk/plan_onsite -> field_service/onsite_interventions
applications/services/fsm/sales/onsite_tasks_from_sales_orders.rst applications/services/field_service/onsite_interventions.rst # fsm/sales/onsite_tasks_from_sales_orders -> field_service/onsite_interventions
# applications/surveys
applications/marketing/surveys/overview.rst applications/marketing/surveys.rst # remove survey overview folder
applications/marketing/surveys/overview/create.rst applications/marketing/surveys/create.rst # remove survey overview folder
applications/marketing/surveys/overview/scoring.rst applications/marketing/surveys/scoring.rst # remove survey overview folder
applications/marketing/surveys/overview/time_random.rst applications/marketing/surveys/time_random.rst # remove survey overview folder
# applications/websites
applications/websites/livechat/overview/get_started.rst applications/websites/livechat.rst # livechat/overview/get_started -> livechat
@ -101,13 +114,6 @@ applications/websites/website/publish/multi_website.rst applications/websites/we
applications/websites/website/publish/on-premise_geo-ip-installation.rst applications/websites/website/configuration/on-premise_geo-ip-installation.rst # publish/* -> configuration/*
applications/websites/website/publish/translate.rst applications/websites/website/configuration/translate.rst # publish/* -> configuration/*
# applications/surveys
applications/marketing/surveys/overview.rst applications/marketing/surveys.rst # remove survey overview folder
applications/marketing/surveys/overview/create.rst applications/marketing/surveys/create.rst # remove survey overview folder
applications/marketing/surveys/overview/scoring.rst applications/marketing/surveys/scoring.rst # remove survey overview folder
applications/marketing/surveys/overview/time_random.rst applications/marketing/surveys/time_random.rst # remove survey overview folder
# developer/howtos
developer/api/external_api.rst developer/reference/external_api.rst # reorganize the developer doc
@ -141,16 +147,14 @@ developer/howtos/web.rst developer/tutorials/web.rst
developer/howtos/website.rst developer/tutorials/website.rst # reorganize the developer doc
developer/iot.rst developer/howtos/connect_device.rst # reorganize the developer doc
# applications/marketing
applications/marketing/social_marketing/overview/livechat.rst applications/marketing/social_marketing/essentials/sms_essentials.rst
applications/marketing/social_marketing/overview/push_notifications.rst applications/marketing/social_marketing/essentials/sms_essentials.rst
applications/marketing/social_marketing/overview/create_posts.rst applications/marketing/social_marketing/essentials/sms_essentials.rst
# developer/misc
developer/misc/api/external_api.rst developer/api/external_api.rst # better location for misc/ content (#2350)
# developer/tutorials
developer/tutorials/getting_started/16_guidelines_pr.rst developer/tutorials/getting_started/16_final_word.rst
# legal
legal/others/cla.rst legal/cla.rst