[ADD] inventory: packaging

closes odoo/documentation#8025

X-original-commit: a8659727e3
Signed-off-by: Zachary Straub (zst) <zst@odoo.com>
Signed-off-by: Felicia Kuan (feku) <feku@odoo.com>
Co-authored-by: hojo-odoo <123424465+hojo-odoo@users.noreply.github.com>
Co-authored-by: ksc-odoo <73958186+ksc-odoo@users.noreply.github.com>

Makefile

@@ -86,12 +86,13 @@ static: $(HTML_BUILD_DIR)/_static/style.css
 
 # Called by runbot for the ci/documentation_guideline check.
 test:
-	@python tests/main.py $(SOURCE_DIR)/administration $(SOURCE_DIR)/applications $(SOURCE_DIR)/contributing $(SOURCE_DIR)/developer $(SOURCE_DIR)/services redirects
+	@python tests/main.py $(SOURCE_DIR)/administration $(SOURCE_DIR)/applications $(SOURCE_DIR)/contributing $(SOURCE_DIR)/developer redirects
 
 # Similar as `test`, but called only manually by content reviewers to trigger extra checks.
 review:
-	@read -p "Enter content path: " path; read -p "Enter max line length (default: 100): " line_length; \
+	@read -p "Enter relative content path: " path; read -p "Enter max line length (default: 100): " line_length; \
 	if [ -z "$$path" ]; then echo "Error: Path cannot be empty"; exit 1; fi; \
+	if echo $$path | grep -q 'content/'; then path=`echo $$path | sed 's|content/||'`; fi; \
 	if [ -z "$$line_length" ]; then line_length=100; fi; \
 	export REVIEW=1; \
 	python tests/main.py --max-line-length=$$line_length $(SOURCE_DIR)/$$path

conf.py

@@ -213,6 +213,8 @@ sphinx.transforms.i18n.docname_to_domain = (
 # is populated. If a version is passed to `versions` but is not listed here, it will not be shown.
 versions_names = {
     'master': "Master",
+    'saas-17.1': "Odoo Online",
+    '17.0': "Odoo 17",
     'saas-16.4': "Odoo Online",
     'saas-16.3': "Odoo Online",
     'saas-16.2': "Odoo Online",
@@ -221,7 +223,6 @@ versions_names = {
     'saas-15.2': "Odoo Online",
     '15.0': "Odoo 15",
     '14.0': "Odoo 14",
-    '13.0': "Odoo 13",
 }
 
 # The language names that should be shown in the language switcher, if the config option `languages`
@@ -478,8 +479,24 @@ def _generate_alternate_urls(app, pagename, templatename, context, doctree):
         _version = _version or app.config.version
         _lang = _lang or app.config.language or 'en'
         _canonical_page = f'{pagename}.html'
+
+        # legal translations have different URLs schemes as they are not managed on transifex
+        # e.g. FR translation of /terms/enterprise => /fr/terms/enterprise_fr
+        if pagename.startswith('legal/terms/'):
+            if _lang in legal_translations and not pagename.endswith(f"_{_lang}"):
+                # remove language code for current translation, set target one
+                _page = re.sub("_[a-z]{2}$", "", pagename)
+                if 'terms/i18n' not in _page:
+                    _page = _page.replace("/terms/", "/terms/i18n/")
+                _canonical_page = f'{_page}_{_lang}.html'
+            elif _lang == 'en' and pagename.endswith(tuple(f"_{l}" for l in legal_translations)):
+                # remove language code for current translation, link to original EN one
+                _page = re.sub("_[a-z]{2}$", "", pagename)
+                _canonical_page = f'{_page.replace("/i18n/", "/")}.html'
+
         if app.config.is_remote_build:
             _canonical_page = _canonical_page.replace('index.html', '')
+
         return f'{_root}' \
                f'{f"/{_version}" if app.config.versions else ""}' \
                f'{f"/{_lang}" if _lang != "en" else ""}' \

content/administration/install.rst

@@ -47,3 +47,4 @@ functionalities, including functional support, upgrades, and hosting. `Pricing
    install/deploy
    install/cdn
    install/email_gateway
+   install/geo_ip

content/administration/install/deploy.rst

@@ -330,21 +330,27 @@ in ``/etc/nginx/sites-enabled/odoo.conf`` set:
       proxy_pass http://odoochat;
       proxy_set_header Upgrade $http_upgrade;
       proxy_set_header Connection $connection_upgrade;
-      proxy_set_header X-Forwarded-Host $host;
+      proxy_set_header X-Forwarded-Host $http_host;
       proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
       proxy_set_header X-Forwarded-Proto $scheme;
       proxy_set_header X-Real-IP $remote_addr;
+
+      add_header Strict-Transport-Security "max-age=31536000; includeSubDomains";
+      proxy_cookie_flags session_id samesite=lax secure;  # requires nginx 1.19.8
     }
 
     # Redirect requests to odoo backend server
     location / {
       # Add Headers for odoo proxy mode
-      proxy_set_header X-Forwarded-Host $host;
+      proxy_set_header X-Forwarded-Host $http_host;
       proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
       proxy_set_header X-Forwarded-Proto $scheme;
       proxy_set_header X-Real-IP $remote_addr;
       proxy_redirect off;
       proxy_pass http://odoo;
+
+      add_header Strict-Transport-Security "max-age=31536000; includeSubDomains";
+      proxy_cookie_flags session_id samesite=lax secure;  # requires nginx 1.19.8
     }
 
     # common gzip
@@ -352,6 +358,31 @@ in ``/etc/nginx/sites-enabled/odoo.conf`` set:
     gzip on;
   }
 
+HTTPS Hardening
+---------------
+
+Add the `Strict-Transport-Security` header to all requests, in order to prevent
+browsers from ever sending a plain HTTP request to this domain. You will need
+to maintain a working HTTPS service with a valid certificate on this domain at
+all times, otherwise your users will see security alerts or be entirely unable
+to access it.
+
+Force HTTPS connections during a year for every visitor in NGINX with the line:
+
+.. code-block:: nginx
+
+  add_header Strict-Transport-Security "max-age=31536000; includeSubDomains";
+
+Additional configuration can be defined for the `session_id` cookie. The `Secure`
+flag can be added to ensure it is never transmitted over HTTP and `SameSite=Lax`
+to prevent authenticated `CSRF`_.
+
+.. code-block:: nginx
+
+  # requires nginx 1.19.8
+  proxy_cookie_flags session_id samesite=lax secure;
+
+
 Odoo as a WSGI Application
 ==========================
 
@@ -409,51 +440,71 @@ Odoo static files are located in each module's :file:`static/` folder, so static
 by intercepting all requests to :samp:`/{MODULE}/static/{FILE}`, and looking up the right module
 (and file) in the various addons paths.
 
-.. example::
-   Say Odoo has been installed via the **debian packages** for Community and Enterprise and the
-   :option:`--addons-path <odoo-bin --addons-path>` is ``'/usr/lib/python3/dist-packages/odoo/addons'``.
+It is recommended to set the ``Content-Security-Policy: default-src 'none'`` header on all images
+delivered by the web server. It is not strictly necessary as users cannot modify/inject content
+inside of modules' :file:`static/` folder and existing images are final (they do not fetch new
+resources by themselves). However, it is good practice.
 
-   Using the above NGINX (https) configuration, the following location block should be added to
-   serve static files via NGINX.
+Using the above NGINX (https) configuration, the following ``map`` and ``location`` blocks should be
+added to serve static files via NGINX.
 
-   .. code-block:: nginx
+.. code-block:: nginx
 
-       location @odoo {
-           # copy-paste the content of the / location block
-       }
+    map $sent_http_content_type $content_type_csp {
+        default "";
+        ~image/ "default-src 'none'";
+    }
 
-       # Serve static files right away
-       location ~ ^/[^/]+/static/.+$ {
-           root /usr/lib/python3/dist-packages/odoo/addons;
-           try_files $uri @odoo;
-           expires 24h;
-       }
+    server {
+        # the rest of the configuration
+
+        location @odoo {
+            # copy-paste the content of the / location block
+        }
+
+        # Serve static files right away
+        location ~ ^/[^/]+/static/.+$ {
+            # root and try_files both depend on your addons paths
+            root ...;
+            try_files ... @odoo;
+            expires 24h;
+            add_header Content-Security-Policy $content_type_csp;
+        }
+    }
+
+The actual ``root`` and ``try_files`` directives are dependant on your installation, specifically on
+your :option:`--addons-path <odoo-bin --addons-path>`.
 
 .. example::
-   Say Odoo has been installed via the **source**. The two git repositories for Community and
-   Enterprise have been cloned in :file:`/opt/odoo/community` and :file:`/opt/odoo/enterprise`
-   respectively and the :option:`--addons-path <odoo-bin --addons-path>` is
-   ``'/opt/odoo/community/odoo/addons,/opt/odoo/community/addons,/opt/odoo/enterprise'``.
 
-   Using the above NGINX (https) configuration, the following location block should be added to
-   serve static files via NGINX.
+   .. tabs::
 
-   .. code-block:: nginx
+      .. group-tab:: Debian package
 
-       location @odoo {
-           # copy-paste the content of the / location block
-       }
+         Say Odoo has been installed via the **debian packages** for Community and Enterprise, and
+         that the :option:`--addons-path <odoo-bin --addons-path>` is
+         ``'/usr/lib/python3/dist-packages/odoo/addons'``.
 
-       # Serve static files right away
-       location ~ ^/[^/]+/static/.+$ {
-           root /opt/odoo;
-           try_files /community/odoo/addons$uri /community/addons$uri /enterprise$uri @odoo;
-           expires 24h;
-       }
+         The ``root`` and ``try_files`` should be:
 
-.. warning::
-   The actual NGINX configuration you need is highly dependent on your own installation. The two
-   above snippets only highlight two possible configurations and may not be used as-is.
+         .. code-block:: nginx
+
+            root /usr/lib/python3/dist-packages/odoo/addons;
+            try_files $uri @odoo;
+
+      .. group-tab:: Git sources
+
+         Say Odoo has been installed via the **sources**, that both the Community and Enterprise git
+         repositories were cloned in :file:`/opt/odoo/community` and :file:`/opt/odoo/enterprise`
+         respectively, and that the :option:`--addons-path <odoo-bin --addons-path>` is
+         ``'/opt/odoo/community/odoo/addons,/opt/odoo/community/addons,/opt/odoo/enterprise'``.
+
+         The ``root`` and ``try_files`` should be:
+
+         .. code-block:: nginx
+
+            root /opt/odoo;
+            try_files /community/odoo/addons$uri /community/addons$uri /enterprise$uri @odoo;
 
 Serving attachments
 -------------------
@@ -727,6 +778,7 @@ Here are the supported browsers:
     environment than over the internet.
 
 .. _regular expression: https://docs.python.org/3/library/re.html
+.. _CSRF: https://en.wikipedia.org/wiki/Cross-site_request_forgery
 .. _ARP spoofing: https://en.wikipedia.org/wiki/ARP_spoofing
 .. _Nginx termination example:
     https://nginx.com/resources/admin-guide/nginx-ssl-termination/

content/administration/install/geo_ip.rst

@@ -1,6 +1,9 @@
-==========================================
-Geo IP Installation (On-Premises Database)
-==========================================
+======
+Geo IP
+======
+
+.. note::
+   This documentation only applies to On-premise databases.
 
 Installation
 ============
@@ -32,8 +35,8 @@ Installation
    .. seealso::
       - :doc:`CLI documentation </developer/reference/cli>`.
 
-Test GeoIP Geolocation In Odoo Website
-======================================
+Test GeoIP geolocation in your Odoo website
+===========================================
 
 Edit a web page to include some geo-ip information such as the country name of the current
 request IP address. To do so:

content/administration/install/packages.rst

@@ -16,8 +16,8 @@ Official **Community** and **Enterprise** packages can be downloaded from the `O
 <https://www.odoo.com/page/download>`_.
 
 .. note::
-   It is required to be logged in as a paying customer or partner to download the Enterprise
-   packages.
+   It is required to be logged in as a paying on-premise customer or partner to download the
+   Enterprise packages.
 
 .. _install/packages/linux:
 
@@ -54,10 +54,10 @@ Odoo needs a `PostgreSQL <https://www.postgresql.org/>`_ server to run properly.
          $ sudo systemctl start postgresql
 
 .. warning::
-   `wkhtmltopdf` is not installed through **pip** and must be installed manually in `version 0.12.5
-   <https://github.com/wkhtmltopdf/wkhtmltopdf/releases/tag/0.12.5>`_ for it to support headers and
-   footers. Check out the `wkhtmltopdf wiki <https://github.com/odoo/odoo/wiki/Wkhtmltopdf>`_ for
-   more details on the various versions.
+   `wkhtmltopdf` is not installed through **pip** and must be installed manually in `version 0.12.6
+   <https://github.com/wkhtmltopdf/packaging/releases/tag/0.12.6.1-3>`_ for it to support headers
+   and footers. Check out the `wkhtmltopdf wiki <https://github.com/odoo/odoo/wiki/Wkhtmltopdf>`_
+   for more details on the various versions.
 
 Repository
 ----------

content/administration/install/source.rst

@@ -225,7 +225,7 @@ PostgreSQL user.
 
       .. code-block:: console
 
-         $ sudo -u postgres createuser -s $USER
+         $ sudo -u postgres createuser -d -R -S $USER
          $ createdb $USER
 
       .. note::
@@ -250,7 +250,7 @@ PostgreSQL user.
 
       .. code-block:: console
 
-         $ sudo -u postgres createuser -s $USER
+         $ sudo -u postgres createuser -d -R -S $USER
          $ createdb $USER
 
       .. note::
@@ -409,10 +409,10 @@ Dependencies
                $ sudo npm install -g rtlcss
 
 .. warning::
-   `wkhtmltopdf` is not installed through **pip** and must be installed manually in `version 0.12.5
-   <https://github.com/wkhtmltopdf/wkhtmltopdf/releases/tag/0.12.5>`_ for it to support headers and
-   footers. Check out the `wkhtmltopdf wiki <https://github.com/odoo/odoo/wiki/Wkhtmltopdf>`_ for
-   more details on the various versions.
+   `wkhtmltopdf` is not installed through **pip** and must be installed manually in `version 0.12.6
+   <https://github.com/wkhtmltopdf/packaging/releases/tag/0.12.6.1-3>`_ for it to support headers
+   and footers. Check out the `wkhtmltopdf wiki <https://github.com/odoo/odoo/wiki/Wkhtmltopdf>`_
+   for more details on the various versions.
 
 .. _install/source/running_odoo:
 

content/administration/maintain.rst

@@ -15,4 +15,5 @@ Maintain
     maintain/hosting_changes
     maintain/odoo_online
     maintain/on_premise
+    maintain/neutralized_database
     maintain/supported_versions

content/administration/maintain/azure_oauth.rst

@@ -25,13 +25,13 @@ To get started, go to `Microsoft's Azure Portal <https://portal.azure.com/>`_. L
 :guilabel:`Microsoft Outlook Office 365` account if there is one, otherwise log in with the
 personal :guilabel:`Microsoft account`. A user with administrative access to the Azure Settings
 will need to connect and perform the following configuration. Next, navigate to the section
-labeled :guilabel:`Manage Azure Active Directory`.
+labeled :guilabel:`Manage Microsoft Entra ID` (formally *Azure Active Directory*).
 
 Now, click on :guilabel:`Add (+)`, located in the top menu, and then select :guilabel:`App
 registration`. On the :guilabel:`Register an application` screen, rename the :guilabel:`Name` to
 `Odoo` or something recognizable. Under the :guilabel:`Supported account types` section select
-:guilabel:`Accounts in any organizational directory (Any Azure AD directory - Multitenant) and
-personal Microsoft accounts (e.g. Skype, Xbox)`.
+:guilabel:`Accounts in any organizational directory (Any Microsoft Entra ID directory - Multitenant)
+and personal Microsoft accounts (e.g. Skype, Xbox)`.
 
 Under the :guilabel:`Redirect URL` section, select :guilabel:`Web` as the platform, and then input
 `https://<odoo base url>/microsoft_outlook/confirm` in the :guilabel:`URL` field. The Odoo base URL
@@ -52,7 +52,7 @@ able to read (IMAP) and send (SMTP) emails in the Microsoft 365 setup. First, cl
 Add a Permission` button and select :guilabel:`Microsoft Graph` under :guilabel:`Commonly Used
 Microsoft APIs`. After, select the :guilabel:`Delegated Permissions` option.
 
-In the search bar, search for the following :guilabel:`Deregulated permissions` and click
+In the search bar, search for the following :guilabel:`Delegated permissions` and click
 :guilabel:`Add permissions` for each one:
 
 - :guilabel:`SMTP.Send`
@@ -188,23 +188,96 @@ configuration automatically loads the :guilabel:`token` in Odoo, and a tag stati
 Finally, click :guilabel:`Test Connection`. A confirmation message should appear. The Odoo database
 can now send safe, secure emails through Microsoft Outlook using OAuth authentication.
 
-Multiple user configuration
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.. _azure_oauth/notifications:
 
-Each user should have a separate server set up. The :guilabel:`from-filter` should be set so that
-only the user's email is sent from that server. In other words, only a user with an email address
-that matches the set :guilabel:`from-filter` is able to use this server.
+Configuration with a single outgoing mail server
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-After setting the :guilabel:`from-filter`, set up a fallback email account to allow for the sending
-of :guilabel:`notifications`. The fallback email must be configured as a :guilabel:`general
-transactional server`. The :guilabel:`mail.default.from` system parameter must be set to the
-:guilabel:`username` of the general transactional server account. For more information see
-:ref:`Use a default email address <email_communication/default>`.
+Configuring a single outgoing server is the simplest configuration available for Microsoft Azure
+and it doesn't require extensive access rights for the users in the database.
+
+A generic email address would be used to send emails for all users within the database. For example
+it could be structured with a `notifications` alias (`notifications@example.com`) or `contact` alias
+(`contact@example.com`). This address must be set as the :guilabel:`FROM Filtering` on the server.
+This address must also match the `{mail.default.from}@{mail.catchall.domain}` key combination in the
+system parameters.
+
+.. seealso::
+   For more information on the from filter visit: :ref:`email_communication/default`.
 
 .. note::
-   The :guilabel:`System Parameters` can be accessed by activating
-   :doc:`../../applications/general/developer_mode` in the :menuselection:`Settings --> Technical
-   --> Parameters --> System Parameters` menu.
+   The :guilabel:`System Parameters` can be accessed by activating :ref:`developer-mode` in the
+   :menuselection:`Settings --> Technical --> Parameters --> System Parameters` menu.
+
+When using this configuration, every email that is sent from the database will use the address of
+the configured `notification` mailbox. However it should be noted that the name of the sender will
+appear but their email address will change:
+
+.. image:: azure_oauth/from-name-remain.png
+   :align: center
+   :alt: Name from real sender with static email.
+
+.. example::
+   Single outgoing mail server configuration:
+
+   - Outgoing mail server **username** (login) = `notifications@example.com`
+   - Outgoing mail server :guilabel:`FROM Filtering` = `notifications@example.com`
+   - `mail.catchall.domain` in system parameters = `example.com`
+   - `mail.default.from` in system parameters = `notifications`
+
+User-specific (multiple user) configuration
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+In addition to a generic email server, individual email servers can be set up for users in a
+database. These email addresses must be set as the :guilabel:`FROM Filtering` on each individual
+server for this configuration to work.
+
+This configuration is the more difficult of the two Microsoft Azure configurations, in that it
+requires all users configured with email servers to have access rights to settings in order to
+establish a connection to the email server.
+
+Setup
+*****
+
+Each user should have a separate email server set up. The :guilabel:`FROM Filtering` should be set
+so that only the user's email is sent from that server. In other words, only a user with an email
+address that matches the set :guilabel:`FROM Filtering` is able to use this server.
+
+.. seealso::
+   For more information on the from filter visit: :ref:`email_communication/default`.
+
+A :ref:`fallback server <azure_oauth/notifications>` must be setup to allow for the sending of
+:guilabel:`notifications`. The :guilabel:`FROM Filtering` for this server should have the value of
+the `{mail.default.from}@{mail.catchall.domain}`.
+
+.. note::
+   The :guilabel:`System Parameters` can be accessed by activating :ref:`developer-mode` in the
+   :menuselection:`Settings --> Technical --> Parameters --> System Parameters` menu.
+
+.. important::
+   The configuration for this transactional email server can work alongside an outgoing mass-mailing
+   email server. The :guilabel:`FROM Filtering` for the mass-mailing email server can remain empty,
+   but it's require to be added in the settings of the *Email Marketing* application.
+
+   .. seealso::
+      For more information on setting the mass-mailing email server visit
+      :ref:`email_communication/mass_mails`.
+
+.. example::
+   Multiple user outgoing mail server configuration:
+
+   - User #1 mailbox
+      - Outgoing mail server #1 **username** (login) = `john@example.com`
+      - Outgoing mail server #1 :guilabel:`FROM Filtering` = `john@example.com`
+   - User #2 mailbox
+      - Outgoing mail server #2 **username** (login) = `jane@example.com`
+      - Outgoing mail server #2 :guilabel:`FROM Filtering` = `jane@example.com`
+   - Notifications mailbox
+      - Outgoing mail server #3 **username** (login) = `notifications@example.com`
+      - Outgoing mail server #3 :guilabel:`FROM Filtering` = `notifications@example.com`
+   - System Parameters
+      - `mail.catchall.domain` in system parameters = `example.com`
+      - `mail.default.from` in system parameters = `notifications`
 
 Configure incoming email server
 -------------------------------

content/administration/maintain/domain_names.rst

@@ -2,293 +2,255 @@
 Domain names
 ============
 
-A **domain name** works as an address for your website. It makes the Internet much more accessible
-as it allows users to type a meaningful web address, such as ``www.odoo.com``, rather than its
-server's IP address with a series of numbers.
+Domain names are text-based addresses identifying online locations, such as websites. They provide a
+more memorable and recognizable way for people to navigate the internet than numerical IP addresses.
 
-You can use a custom domain name to access your Odoo database and websites:
+**Odoo Online** and **Odoo.sh** databases use a **subdomain** of the `odoo.com` **domain** by
+default (e.g., `mycompany.odoo.com`).
 
-- By :ref:`registering a free domain name with Odoo <domain-name/odoo-register>` (for Odoo Online
-  databases)
-- By :ref:`configuring a custom domain that you already own <domain-name/existing>`.
-
-.. note::
-   Odoo Online and Odoo.sh databases, including their websites, use by default a subdomain of
-   ``odoo.com`` for both the URL and the emails (e.g., ``https://example.odoo.com``).
-
-.. important::
-   Odoo offers a :ref:`free custom domain name <domain-name/odoo-register>` to all Odoo Online
-   databases for one year. Visitors can then access your website with an address such as
-   ``www.example.com`` rather than the default ``example.odoo.com``.
+However, you can use a custom domain name instead by :ref:`registering a free domain name
+<domain-name/register>` (only available for Odoo Online databases) or by :ref:`configuring a
+domain name you already own <domain-name/existing>`.
 
 .. seealso::
-   - `Odoo Tutorials: Register a Free Domain Name
-     <https://www.odoo.com/slides/slide/register-a-free-domain-name-1663>`_
-   - `Odoo Quick Tips: Get a free domain name! <https://www.youtube.com/watch?v=eAfgeNOHLP4>`_
+   `Odoo Tutorials: Register a free domain name [video]
+   <https://www.odoo.com/slides/slide/register-a-free-domain-name-1663>`_
 
-.. _domain-name/about:
-
-About domain names
-==================
-
-Having a **good domain name** is as important to your branding as the name of your business or
-organization as it is the first thing your visitors will notice. We recommend you keep them *simple,
-short, easy to remember and spell*.
-
-A **subdomain** is a domain that is a part of another domain. It often refers to the additional part
-that comes before the main domain name. Traditionally, most websites use the ``www.`` subdomain,
-but any string of letters can be used as well. You can use subdomains to direct your visitors to
-other websites than your main website or to specific pages (e.g., ``experience.odoo.com`` points to
-a specific page.)
-
-All domain names are referenced in the **Domain Name System**, or **DNS**, which works as a giant
-directory for the Internet. There are many DNS servers, so any modification to the DNS can take up
-to 72 hours to propagate worldwide on all servers.
-
-.. _domain-name/indexing:
-
-Indexing of domain names by search engines
-------------------------------------------
-
-Search engines, such as Google and Bing, rely on web crawlers (:dfn:`robots that explore and analyze
-the web`) to index all websites and their related domain names. These crawlers discover new URLs
-thanks to links on known web pages. As a result, search engines should index domain names
-automatically after a while, as long as their URLs are mentioned elsewhere on the Internet.
-
-Improving the appearance and positioning of web pages on search engines is a practice named "Search
-Engine Optimization" (SEO).
-
-.. tip::
-   Adding relevant content, optimizing metadata, and building high-quality backlinks can all help
-   improve a website's search engine visibility.
-
-Some search engines provide tools for web admins, such as
-`Google Search Console <https://search.google.com/search-console>`_ and
-`Bing Webmaster Tools <https://www.bing.com/webmasters>`_, to help you analyze and improve your
-page ranking. To use these services, you must prove that you are the owner of your domain name. One
-way to verify the ownership of your domain name is by adding a DNS record. You can do this for
-:ref:`domain names registered with Odoo <domain-name/odoo-manage>` and for domain names managed by
-other providers.
-
-.. seealso::
-   - :doc:`/applications/websites/website/pages/seo`
-   - `Google Search Console Help - Verify your site ownership <https://support.google.com/webmasters/answer/9008080>`_
-   - `Bing Webmaster Tools - Add and Verify site <https://www.bing.com/webmasters/help/add-and-verify-site-12184f8b>`_
-
-.. _domain-name/odoo-register:
+.. _domain-name/register:
 
 Register a free domain name with Odoo
 =====================================
 
-You can register a domain name for your Odoo Online database directly from Odoo Website or your
-database manager.
+To register a one-year free domain name for your Odoo Online database, sign in to your account and
+go to the `database manager <https://www.odoo.com/my/databases>`_. Click the gear icon
+(:guilabel:`⚙️`) next to the database name and select :guilabel:`Domain Names`.
+
+.. image:: domain_names/domain-names.png
+   :alt: Accessing a database's domain names configuration
+
+Search for the desired domain name and check its availability.
+
+.. image:: domain_names/domain-search.png
+   :alt: Searching for an available domain name
+
+.. tip::
+   Ensure the Website app is installed if the domain name registration option does not appear.
+
+Select the desired domain name, fill in the :guilabel:`Domain Owner` form, and click
+:guilabel:`Register`. The chosen domain name is directly linked to the database, but you still need
+to :ref:`map your domain name to your Odoo website <domain-name/db-map>`.
+
+.. image:: domain_names/domain-owner.png
+   :alt: Filling in the domain owner information
 
 .. important::
-   - Your domain name is **free for one year** if you register it with Odoo!
-   - The domain name is registered with `Gandi <https://www.gandi.net/>`_, the domain name
-     registrar.
-   - You are the owner of the domain name and can use it for other purposes.
-   - Odoo manages payment and technical support for you.
-   - This offer doesn't include any mailbox. However, you can :ref:`configure your MX records
-     <domain-name/odoo-manage>` to use your own email server or solution such as Google Workspace.
+   A verification email from `noreply@domainnameverification.net` will be sent to the email address
+   provided in the :guilabel:`Domain Owner` form. It is essential to verify your email address to
+   keep the domain active and receive the renewal quote before expiration.
 
-To do so, go to :menuselection:`Website --> Domain Name`. Alternatively, open your `database manager
-<https://www.odoo.com/my/databases>`_, click on the :guilabel:`settings` button next to your
-database, then on :guilabel:`Domain names`.
-
-.. image:: domain_names/register-menu.png
-   :align: center
-   :alt: Clicking on Domain Names from an Odoo website
-
-Search for the domain name of your choice to check its availability, then select the one you want to
-register for your website.
-
-.. image:: domain_names/register-search.png
-   :align: center
-   :alt: The search of the domain name example.com shows which associated domains are available.
-
-Next, fill in the form with your information to become the domain name owner.
-
-Your domain name is directly linked to your database, but you still have to :ref:`map your domain
-name with your website <domain-name/website-map>`.
+The domain name registration is free for the first year. After this period, Odoo will continue to
+manage the domain in partnership with **Gandi.net**, the domain name registrar, and you will be
+charged `Gandi.net's renewal rate <https://www.gandi.net/en/domain>`_. Odoo sends a renewal
+quotation every year to the email address mentioned in the :guilabel:`Domain Owner` form several
+weeks before the expiration date of the domain. The domain is renewed automatically when the
+quotation is confirmed.
 
 .. note::
-   - Free domain names are also available for free Odoo Online databases (if you installed one app
-     only, for example). In this case, Odoo reviews your request and your website to avoid abuse.
-     This process can take several days due to the success of the offer.
-   - This is not available for Odoo.sh databases yet.
+   - The offer is only available for **Odoo Online** databases.
+   - The offer is limited to **one** domain name per client.
+   - The offer is limited to the registration of a **new** domain name.
+   - The offer is available to *One App Free* plans. Ensure that your website contains enough
+     original content for Odoo to verify that your request is legitimate and respects `Odoo's
+     Acceptable Use Policy <https://www.odoo.com/acceptable-use>`_. Given the high number of
+     requests, it can take Odoo several days to review them.
 
-.. _domain-name/odoo-manage:
+.. _domain-name/register-dns:
 
-Manage your domain name registered with Odoo
---------------------------------------------
+DNS records
+-----------
 
-To manage the DNS records of your domain name registered with Odoo or to visualize the contacts
-associated with it, open your `database manager <https://www.odoo.com/my/databases>`_, click on the
-:guilabel:`settings` button next to your database, on :guilabel:`Domain names`, and then on
-:guilabel:`Contacts` or :guilabel:`DNS`.
+To manage your free domain name :abbr:`DNS (domain name system)` records, open the `database manager
+<https://www.odoo.com/my/databases>`_, click the gear icon (:guilabel:`⚙️`) next to the database
+name, select :guilabel:`Domain Names`, and click :guilabel:`DNS`.
 
-.. image:: domain_names/manage.png
-   :align: center
-   :alt: Management of the domain names linked to an Odoo database
+- :guilabel:`A`: the A record holds the IP address of the domain. It is automatically created and
+  **cannot** be edited or deleted.
+- :guilabel:`CNAME`: CNAME records forward one domain or subdomain to another domain. One is
+  automatically created to map the `www.` subdomain to the database. If the database is renamed, the
+  CNAME record **must** also be renamed.
+- :guilabel:`MX`: MX records instruct servers on where to deliver emails.
+- :guilabel:`TXT`: TXT records can be used for different purposes (e.g., to verify domain name
+  ownership).
+
+Any modification to the DNS records can take up to **72 hours** to propagate worldwide on all
+servers.
 
 .. note::
-   Please `submit a support ticket <https://www.odoo.com/help>`_ if you need further assistance to
-   manage your domain name.
+   `Submit a support ticket <https://www.odoo.com/help>`_ if you need assistance to manage your
+   domain name.
+
+Mailbox
+-------
+
+The one-year free domain name offer does **not** include a mailbox. There are two options to link
+your domain name with a mailbox.
+
+Use a subdomain
+~~~~~~~~~~~~~~~
+
+You can create a subdomain (e.g., `subdomain.yourdomain.com`) to use as an alias domain for the
+database. It allows users to create records in the database from emails received on their
+`email@subdomain.yourdomain.com` alias.
+
+To do so, open the `database manager <https://www.odoo.com/my/databases>`_, click the gear icon
+(:guilabel:`⚙️`) next to the database name, and go to :menuselection:`Domain Names --> DNS --> Add
+DNS record --> CNAME`. Next, enter the desired subdomain in the :guilabel:`Name` field (e.g.,
+`subdomain`), the original database domain with a period at the end (e.g., `mycompany.odoo.com.`) in
+the :guilabel:`Content` field, and click :guilabel:`Add record`.
+
+Then, add the alias domain as your *own domain* by clicking :guilabel:`Use my own domain`, entering
+the alias domain (e.g., `subdomain.yourdomain.com`), clicking :guilabel:`Verify`, and then
+:guilabel:`I confirm, it's done`.
+
+Finally, go to your database and open the :guilabel:`Settings`. Enable :guilabel:`Custom Email
+Servers` field, enter the :guilabel:`Alias Domain` (e.g., `subdomain.yourdomain.com`) and click
+:guilabel:`Save`.
+
+Use an external email provider
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To use an external email provider, you should configure an MX record. To do so, open the `database
+manager <https://www.odoo.com/my/databases>`_, click the gear icon (:guilabel:`⚙️`) next to the
+database name, click :menuselection:`Domain Names --> DNS --> Add DNS record --> MX`. The values you
+should enter for the :guilabel:`Name`, :guilabel:`Content`, and :guilabel:`Priority` fields depend
+on the external email provider.
+
+.. seealso::
+   - `Google Workspace: MX record values <https://support.google.com/a/answer/174125?hl=en>`_
+   - `Outlook and Exchange Online: Add an MX record for email <https://learn.microsoft.com/en-us/microsoft-365/admin/get-help-with-domains/create-dns-records-at-any-dns-hosting-provider?view=o365-worldwide#add-an-mx-record-for-email-outlook-exchange-online>`_
 
 .. _domain-name/existing:
 
-Configure your existing domain name
-===================================
+Configure an existing domain name
+=================================
 
-If you already own a domain name, you can use it to point to your website.
+If you already have a domain name, you can use it for your Odoo website.
 
-To avoid any issue with the :ref:`SSL certificate validation <domain-name/ssl>`, we highly recommend
-that you proceed with the following actions in this order:
+.. warning::
+   It is strongly recommended to follow **in order** these three steps to avoid any :ref:`SSL
+   certificate validation <domain-name/ssl>` issues:
 
-#. :ref:`Add a CNAME record <domain-name/cname>` on your domain name's DNS zone.
-#. :ref:`Map your domain name with your Odoo database <domain-name/db-map>`.
-#. :ref:`Map your domain name with your Odoo website <domain-name/website-map>`.
+   #. :ref:`Add a CNAME record <domain-name/cname>`
+   #. :ref:`Map your domain name to your Odoo database <domain-name/db-map>`
+   #. :ref:`Map your domain name to your Odoo website <domain-name/website-map>`
 
 .. _domain-name/cname:
 
 Add a CNAME record
 ------------------
 
-A **CNAME record** is a type of DNS record that points to the domain of another website rather than
-directly to an IP address.
-
-You need a CNAME record that points to your Odoo database. The requirements are detailed in your
-database manager.
+Creating a CNAME record to forward your domain name to the address of your Odoo database is
+required.
 
 .. tabs::
 
    .. group-tab:: Odoo Online
 
-      The target address is the current address of your database, as defined at its creation (e.g.,
-      ``example.odoo.com``)
+      The CNAME record's target address should be your database's address as defined at its creation
+      (e.g., `mycompany.odoo.com`).
 
    .. group-tab:: Odoo.sh
 
-      Your project's main address is defined in :menuselection:`Settings --> Project Name`.
+      The CNAME record's target address can be the project's main address, which can be found on
+      Odoo.sh by going to :menuselection:`Settings --> Project Name`, or a specific branch
+      (production, staging or development) by going to :menuselection:`Branches --> select the
+      branch --> Settings --> Custom domains`, and clicking :guilabel:`How to set up my domain?`. A
+      message indicates which address your CNAME record should target.
 
-      If you want to target a specific branch (production, staging or development), go to
-      :menuselection:`Branches --> select your branch --> Settings --> Custom domains`, and click on
-      :guilabel:`How to set up my domain?`. A message indicates which address your CNAME record
-      should target.
+The specific instructions depend on your DNS hosting service.
 
-#. Open your domain name's manager dashboard.
-#. Open the **DNS zone** management page for the domain name you want to configure.
-#. Create a **CNAME record** pointing to the address of your database.
+.. seealso::
+   - `GoDaddy: Add a CNAME record <https://www.godaddy.com/help/add-a-cname-record-19236>`_
+   - `Namecheap: How to create a CNAME record for your domain <https://www.namecheap.com/support/knowledgebase/article.aspx/9646/2237/how-to-create-a-cname-record-for-your-domain>`_
+   - `OVHcloud: Add a new DNS record <https://docs.ovh.com/us/en/domains/web_hosting_how_to_edit_my_dns_zone/#add-a-new-dns-record>`_
+   - `Cloudflare: Manage DNS records
+     <https://support.cloudflare.com/hc/en-us/articles/360019093151>`_
 
-While Odoo suggests creating a CNAME record for your ``www.`` subdomain (``www.example.com``), you
-can of course use any domain name of your choice, with any subdomain (e.g.,
-``anything.example.com``).
+Creating a CNAME record to map the `www` subdomain (`www.yourdomain.com`) as some visitors are used
+to typing `www.` before entering a domain name.
 
 .. example::
-   You own the domain name ``example.com``, and you have an Odoo Online database at the address
-   ``example.odoo.com``. You want to access your Odoo database primarily with the domain
-   ``www.example.com`` but also with the :ref:`naked domain <domain-name/naked-domain>`
-   ``example.com``.
+   You own the domain name `yourdomain.com`, and your Odoo Online database's address is
+   `mycompany.odoo.com`. You want to access your Odoo database primarily with the domain
+   `www.yourdomain.com` but also with the naked domain :dfn:`(a domain name without any subdomains
+   or prefixes)` `yourdomain.com`.
 
-   To do so, you create a CNAME record for the ``www`` subdomain, with ``example.odoo.com`` as the
-   target. The DNS zone manager generates the following rule and adds it to your DNS zone: ``www IN
-   CNAME example.odoo.com.``
-
-   You also create a redirection from ``example.com`` to ``wwww.example.com``.
-
-   Your new DNS records are propagated to all DNS servers.
-
-.. note::
-   Here are some specific guidelines to create a CNAME record:
-
-   - `GoDaddy <https://www.godaddy.com/help/add-a-cname-record-19236>`_
-   - `Namecheap <https://www.namecheap.com/support/knowledgebase/article.aspx/9646/2237/how-to-create-a-cname-record-for-your-domain>`_
-   - `OVH <https://docs.ovh.com/us/en/domains/web_hosting_how_to_edit_my_dns_zone/#add-a-new-dns-record>`_
-   - `CloudFlare <https://support.cloudflare.com/hc/en-us/articles/360019093151>`_
-   - `Google Domains <https://support.google.com/domains/answer/3290350?hl=en>`_
-
-.. _domain-name/naked-domain:
-
-Naked domain
-~~~~~~~~~~~~
-
-A **naked domain** is a domain name that doesn't have any subdomain at the beginning of the address
-(e.g., ``odoo.com`` instead of ``www.odoo.com``).
-
-You may want your naked domain to redirect to your website as some visitors may not type the full
-domain name to access your website.
-
-#. Open your domain name's manager dashboard.
-#. Create a **redirection** from the naked domain (``example.com``) to your main domain name
-   (``www.example.com``).
-
-.. note::
-   Depending on your domain name registrar, this redirection may be already pre-configured.
+   To do so, create a CNAME record for the `www` subdomain, with `mycompany.odoo.com` as the
+   target. Next, create a redirect (301 permanent or visible redirect) to redirect visitors from
+   `yourdomain.com` to `wwww.yourdomain.com`.
 
 .. _domain-name/db-map:
 
-Map your domain name with your Odoo database
---------------------------------------------
+Map a domain name to an Odoo database
+-------------------------------------
+
+.. warning::
+   Ensure you have :ref:`added a CNAME record <domain-name/cname>` to your domain name's DNS
+   **before** mapping your domain name to your Odoo database.
+
+   Failing to do so may prevent the validation of the :ref:`SSL certificate <domain-name/ssl>` and
+   could result in a *certificate name mismatch* error. Web browsers often display this as a
+   warning, such as *"Your connection is not private"*.
+
+   If you encounter this error after mapping the domain name to your database, wait up to five
+   days, as the validation may still happen. If not, you can `submit a support ticket
+   <https://www.odoo.com/help>`_, including screenshots of your CNAME records.
 
 .. tabs::
 
    .. group-tab:: Odoo Online
 
-      Open your `database manager <https://www.odoo.com/my/databases>`_, click on the
-      :guilabel:`settings` button next to your database, on :guilabel:`Domain names`, and then on
-      :guilabel:`Use my own domain` at the bottom of the right column.
+      Open the `database manager <https://www.odoo.com/my/databases>`_, click the gear icon
+      (:guilabel:`⚙️`) next to the database name, and go to :menuselection:`Domain Names --> Use my
+      own domain`. Then, enter the domain name (e.g., `yourdomain.com`), click :guilabel:`Verify`
+      and :guilabel:`I confirm, it's done`.
 
-      Type the domain name you want to add to this database, then click on :guilabel:`Verify` to
-      check if the CNAME record is correctly configured. Once done, click on :guilabel:`I confirm,
-      it's done`.
-
-      .. image:: domain_names/online-map.png
-         :align: center
-         :alt: Verification of the CNAME records of a domain name before mapping it with a database
+      .. image:: domain_names/map-database-online.png
+         :alt: Mapping a domain name to an Odoo Online database
 
    .. group-tab:: Odoo.sh
 
-      Go to :menuselection:`Branches --> select your branch --> Settings --> Custom domains`, type
-      the domain name you want to add to this database, then click on :guilabel:`Add domain`.
+      On Odoo.sh, go to :menuselection:`Branches --> select your branch --> Settings --> Custom
+      domains`, type the domain name to add, then click :guilabel:`Add domain`.
 
-      .. image:: domain_names/odoo-sh-map.png
-         :align: center
-         :alt: Mapping a domain name with an Odoo.sh branch
+      .. image:: domain_names/map-database-sh.png
+         :alt: Mapping a domain name to an Odoo.sh branch
 
       .. seealso::
-         - :ref:`Odoo.sh branches: settings tab <odoosh-gettingstarted-branches-tabs-settings>`
-
-.. warning::
-   Make sure to :ref:`add a CNAME record <domain-name/cname>` to your domain name's DNS **before**
-   mapping your domain name with your Odoo database.
-
-   Failing to do so may impede the validation of the :ref:`SSL certificate <domain-name/ssl>` and
-   would result in a *certificate name mismatch* error. This is often displayed by web browsers as a
-   warning such as *"Your connection is not private"*.
-
-   If this is the case and you have added the domain name to your database's settings less than five
-   days ago, wait 24 hours as the validation may still happen. Otherwise, please `submit a support
-   ticket <https://www.odoo.com/help>`_ including screenshots of your CNAME records.
+         :ref:`Odoo.sh branches: settings tab <odoosh-gettingstarted-branches-tabs-settings>`
 
 .. _domain-name/ssl:
 
 SSL encryption (HTTPS protocol)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-**SSL encryption** is an encryption-based Internet security protocol. It allows your visitors to
-navigate your website through a secure connection, which appears as an ``https://`` protocol at the
-beginning of your web address, rather than a non-secure ``http://`` protocol.
+**SSL encryption** allows visitors to navigate a website through a secure connection, which appears
+as the *https://* protocol at the beginning of a web address rather than the non-secure *http://*
+protocol.
 
-Odoo generates a separate SSL certificate for each domain :ref:`mapped in the database manager
-<domain-name/db-map>`, using integration with `Let's Encrypt Certificate Authority and ACME protocol
+Odoo generates a separate SSL certificate for each domain :ref:`mapped to a database
+<domain-name/db-map>` using `Let's Encrypt's certificate authority and ACME protocol
 <https://letsencrypt.org/how-it-works/>`_.
 
 .. note::
-   - The certificate generation may take up to 24h.
-   - Several attempts to validate your certificate are made during the five days following the
-     moment you add your domain name in your database's settings.
-   - If you already use another service, you can keep using it or simply change for Odoo.
+   - Certificate generation may take up to 24 hours.
+   - Several attempts to validate your certificate are made for five days after you map your domain
+     name to your database.
+   - If you use another service, you can keep using it or change to Odoo's.
+
+.. important::
+   No SSL certificate is generated for naked domains :dfn:`(domain names without any subdomains
+   or prefixes)`.
 
 .. _domain-name/web-base-url:
 
@@ -296,71 +258,57 @@ Web base URL of a database
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 .. note::
-   If you have Odoo Website, you can disregard this part and directly :ref:`map your domain name
-   with your website <domain-name/website-map>`.
+   If the Website app is installed on your database, skip this section and continue from the
+   :ref:`Map a domain name to a website <domain-name/website-map>` section.
 
-The **web base URL** of a database, or **root URL** affects your main website address and all the
+The *web base URL* or root URL of a database affects your main website address and all the
 links sent to your customers (e.g., quotations, portal links, etc.).
 
-To configure it, access your Odoo database with your custom address, then log in as an administrator
-of your database (any user in the *Settings* group) from the login screen.
+To make your custom domain name the *web base URL* of your database, access your database using your
+custom domain name and log in as an administrator :dfn:`(a user part of the Settings access right
+group under Administration)`.
 
 .. warning::
-   Connecting to your database with the original Odoo subdomain address (e.g., ``example.odoo.com``
-   also updates the web base URL of your database. See below to prevent these automatic updates.
-
-Alternatively, you can do it manually. To do so, activate the :ref:`developer mode
-<developer-mode>`, then go to :menuselection:`Settings --> Technical --> System Parameters`.
-
-Find the key called ``web.base.url`` (or create it if it does not exist) and enter the full address
-of your website as value, such as ``https://www.example.com``.
+   If you access your database with the original Odoo address (e.g., `mycompany.odoo.com`), the *web
+   base URL* of your database will be updated accordingly. To prevent the automatic update of the
+   *web base URL* when an administrator logs in to the database, activate the :ref:`developer mode
+   <developer-mode>`, go to :menuselection:`Settings --> Technical --> System Parameters --> New`,
+   and enter `web.base.url.freeze` as the :guilabel:`Key` and `True` as the :guilabel:`Value`.
 
 .. note::
-   The URL must include the protocol ``https://`` (or ``http://``) and must not end with a slash
-   (``/``).
-
-To prevent the automatic update of the web base URL when an administrator logs in the database, you
-can create the following System Parameter:
-
-- key: ``web.base.url.freeze``
-- value: ``True``
+   You can also set the web base URL manually. To do so, activate the :ref:`developer mode
+   <developer-mode>`, go to :menuselection:`Settings --> Technical --> System Parameters`, and
+   search for the `web.base.url` key (create it if necessary) and enter the full address of your
+   website as the value (e.g., `https://www.yourdomain.com`). The URL must include the protocol
+   `https://` (or `http://`) and *not* end with a slash (`/`).
 
 .. _domain-name/website-map:
 
-Map your domain name with your website
-======================================
+Map a domain name to an Odoo website
+------------------------------------
 
-Mapping your domain name to your website isn't the same as mapping it with your database:
+Mapping your domain name to your website is different than mapping it to your database:
 
 - It defines your domain name as the main one for your website, helping search engines to index your
-  website properly.
-- It defines your domain name as the base URL for your database, including the portal links sent by
+  website correctly.
+- It defines your domain name as the base URL for your database, including portal links sent by
   email to your customers.
-- If you have multiple websites, it maps your domain name with the appropriate website.
+- If you have multiple websites, it maps your domain name to the appropriate website.
 
-Go to :menuselection:`Website --> Configuration --> Settings --> Website Info`. If you have multiple
-websites, select the one you want to configure.
-
-In the :guilabel:`Domain` field, fill in the web address of your website (e.g.,
-``https://www.example.com``) and click on :guilabel:`Save`.
-
-.. image:: domain_names/website-settings.png
-   :align: center
-   :alt: Configuring https://www.example.com as the Domain of the website
+Go to :menuselection:`Website --> Configuration --> Settings`. If you have multiple websites, select
+the one you want to configure. In the :guilabel:`Domain` field, enter the address of your website
+(e.g., `https://www.yourdomain.com`) and :guilabel:`Save`.
 
 .. warning::
-   Mapping your domain name with your Odoo website prevents Google from indexing both your custom
-   domain name ``www.example.com`` and your original odoo database address ``example.odoo.com``.
+   Mapping your domain name to your Odoo website prevents Google Search from indexing your original
+   database address (e.g., `mycompany.odoo.com`).
 
-   If both addresses are already indexed, it may take some time before Google removes the indexation
-   of the second address. You may also try using the `Google Search Console
-   <https://search.google.com/search-console>`_ to fix this.
+   If both addresses are already indexed, it may take some time before the indexation of the second
+   address is removed from Google Search. You can use the `Google Search Console
+   <https://search.google.com/search-console/welcome>`_ to fix the issue.
 
 .. note::
-   If you have multiple websites and companies on your database, make sure that you select the
-   right :guilabel:`Company` in the website settings, next to the :guilabel:`Domain` settings. Doing
-   so indicates Odoo which URL to use as the :ref:`base URL <domain-name/web-base-url>` according to
+   If you have multiple websites and companies on your database, make sure to select the right
+   :guilabel:`Company` under :menuselection:`Website --> Configuration --> Settings`. Doing so
+   indicates Odoo which URL to use as the :ref:`base URL <domain-name/web-base-url>` according to
    the company in use.
-
-.. seealso::
-  - :doc:`/applications/general/email_communication/email_servers`

content/administration/maintain/neutralized_database.rst

@@ -0,0 +1,35 @@
+====================
+Neutralized database
+====================
+
+A neutralized database is a non-production database on which several parameters are deactivated.
+This enables one to carry out tests without the risk of launching specific automated processes that
+could impact production data (e.g., sending emails to customers). Live access is removed and
+turned into a testing environment.
+
+.. note::
+   **Any testing database created is a neutralized database:**
+
+   - testing backup databases
+   - duplicate databases
+   - for Odoo.sh: staging and development databases
+
+.. important::
+   A database can also be neutralized when upgrading, as it is vital to do some tests before
+   switching to a new version.
+
+Deactivated features
+====================
+
+Here is a non-exhaustive list of the deactivated parameters:
+
+- all planned actions (e.g., automatic invoicing of subscriptions, mass mailing, etc.)
+- outgoing emails
+- bank synchronization
+- payment providers
+- delivery methods
+- :abbr:`IAP (In-App Purchase)` tokens
+
+.. note::
+   **A red banner at the top of the screen is displayed on the neutralized database so that it can
+   be seen immediately.**

content/administration/maintain/odoo_online.rst

@@ -30,8 +30,8 @@ Upgrade
 Trigger a database upgrade.
 
 .. seealso::
-   For more information about the upgrade process, check out the :doc:`Odoo Online upgrade
-   documentation <../upgrade/odoo_online>`.
+   For more information about the upgrade process, check out the :ref:`Odoo Online upgrade
+   documentation <upgrade/request-test-database>`.
 
 .. _odoo_online/duplicate:
 
@@ -72,7 +72,7 @@ Domain names
 Use a custom :doc:`domain name <domain_names>` to access the database via another URL.
 
 .. tip::
-   You can :ref:`register a domain name for free <domain-name/odoo-register>`.
+   You can :ref:`register a domain name for free <domain-name/register>`.
 
 .. _odoo_online/tags:
 
@@ -129,6 +129,5 @@ users, click :guilabel:`Add more users`.
 To remove users, select them and click :guilabel:`Remove`.
 
 .. seealso::
-   - :doc:`../../applications/general/users/manage_users`
-   - :doc:`../../applications/general/users/delete_account`
-
+   - :doc:`/applications/general/users/manage_users`
+   - :doc:`/applications/general/users/odoo_account`

content/administration/maintain/supported_versions.rst

@@ -1,3 +1,4 @@
+:hide-page-toc:
 
 .. _supported_versions:
 
@@ -16,9 +17,6 @@ Odoo provides support and bug fixing **for the 3 last major versions** of Odoo.
    - Online versions are *not* released for Odoo.sh and On-Premise installations.
    - Online versions are listed below as *SaaS*.
 
-What's the support status of my Odoo?
-=====================================
-
 This matrix shows the support status of every version.
 
 **Major releases are in bold type.**
@@ -33,6 +31,18 @@ This matrix shows the support status of every version.
      - On-Premise
      - Release date
      - End of support
+   * - Odoo saas~17.1
+     - |green|
+     - N/A
+     - N/A
+     - January 2024
+     -
+   * - **Odoo 17.0**
+     - |green|
+     - |green|
+     - |green|
+     - November 2023
+     - October 2026 (planned)
    * - Odoo saas~16.4
      - |green|
      - N/A
@@ -62,7 +72,7 @@ This matrix shows the support status of every version.
      - |green|
      - |green|
      - October 2022
-     - October 2025 (planned)
+     - November 2025 (planned)
    * - Odoo saas~15.2
      - |red|
      - N/A
@@ -80,21 +90,27 @@ This matrix shows the support status of every version.
      - |green|
      - |green|
      - October 2021
-     - October 2024 (planned)
+     - November 2024 (planned)
    * - **Odoo 14.0**
-     - |green|
-     - |green|
-     - |green|
+     - |red|
+     - |red|
+     - |red|
      - October 2020
-     - November 2023 (planned)
+     - November 2023
    * - **Odoo 13.0**
      - |red|
      - |red|
      - |red|
      - October 2019
      - October 2022
+   * - Older versions
+     - |red|
+     - |red|
+     - |red|
+     - Before 2019
+     - Before 2022
 
-.. note::
+.. admonition:: Legend
 
     |green| Supported version
 
@@ -102,7 +118,9 @@ This matrix shows the support status of every version.
 
     N/A Never released for this platform
 
-    🏁 Future version, not released yet
+.. important::
+   Even though we don't support older versions, you can always `upgrade from any version
+   <https://upgrade.odoo.com/>`_.
 
 .. |green| raw:: html
 
@@ -111,14 +129,3 @@ This matrix shows the support status of every version.
 .. |red| raw:: html
 
    <span class="text-danger" style="font-size: 32px; line-height: 0.5">●</span>
-
-I run an older version of Odoo/OpenERP/TinyERP
-==============================================
-
-Odoo 12.0, 11.0, 10.0, 9.0, and 8.0 are not supported anymore, on any platform.
-
-OpenERP 7.0, 6.1, 6.0 and 5.0 are not supported anymore, on any platform.
-
-TinyERP 4.0, 3.0, 2.0 and 1.0 are not supported anymore, on any platform.
-
-Even though we don't support older versions, you can always `upgrade from any version <https://upgrade.odoo.com/>`_.

content/administration/maintain/update.rst

@@ -110,7 +110,7 @@ to replace the installation directory with a newer version. First download the l
 from Odoo.com. They are updated daily and include the latest security fixes (see step #1)
 After downloading the package, extract it to a temporary location on your server.
 
-You will get a folder labelled with the version of the source code, for example "odoo-13.0+e.20190719",
+You will get a folder labeled with the version of the source code, for example "odoo-13.0+e.20190719",
 that contains a folder "odoo.egg-info" and the actual source code folder named "odoo" (for Odoo 10
 and later) or "openerp" for older versions.
 You can ignore the odoo.egg-info folder. Locate the folder where your current installation is deployed,

content/administration/odoo_sh/getting_started/branches.rst

@@ -295,7 +295,7 @@ Upgrade
 Available for production and staging branches for valid projects.
 
 .. seealso::
-    :doc:`Upgrade - Odoo.sh <../../upgrade/odoo_sh>`
+    :doc:`Upgrade documentation <../../upgrade>`
 
 .. _odoosh-gettingstarted-branches-tabs-settings:
 

content/administration/upgrade.rst

@@ -1,226 +1,372 @@
-:show-content:
-
-.. |assistance-contact| replace::
-   If you need Odoo assistance on this matter, please get in touch with your Odoo Account Manager or
-   our `Sales department`_.
-.. _Sales department: mailto:sales@odoo.com
-
 =======
 Upgrade
 =======
 
-.. toctree::
-   :titlesonly:
+.. _administration/upgrade:
 
-   upgrade/odoo_online
-   upgrade/odoo_sh
-   upgrade/on_premise
-   upgrade/faq
+An upgrade is the process of moving your database from an older version to a newer :doc:`supported
+version <maintain/supported_versions>` (e.g., Odoo 14.0 to Odoo 16.0). Frequently upgrading is
+essential as each version comes with new and improved features, bug fixes, and security patches.
 
-An upgrade is switching to a newer version of Odoo (e.g., Odoo 14.0 to Odoo 15.0).
+.. _upgrade_faq/rolling_release:
+
+.. spoiler:: Automatic upgrades: Odoo Online's Rolling Release process
+
+   The Rolling Release process allows Odoo Online customers to upgrade their database directly from
+   a message prompt sent to the database administrator as soon as a new version is released. The
+   invitation to upgrade is only sent if no issues are detected during the automatic tests.
+
+   .. image:: upgrade/rr-upgrade-message.png
+      :alt: The upgrade message prompt on the top right of the database
+
+   It is strongly recommended to manually :ref:`test the upgrade first <upgrade/test_your_db>`.
+   Clicking :guilabel:`I want to test first` redirects to `the database manager
+   <https://www.odoo.com/my/databases/>`_, where it is possible to request an upgraded test database
+   and check it for any discrepancies.
+
+   It is **not** recommended to click :guilabel:`Upgrade Now` without testing first, as it
+   immediately triggers the live production database upgrade.
+
+   If the Rolling Release process detects an issue with the upgrade, it will be deactivated until
+   the issue is resolved.
 
 An upgrade does not cover:
 
-* Changing :ref:`editions <upgrade-faq/editions-change>` (i.e., Community to Enterprise edition)
-* Switching :ref:`hosting type <upgrade-faq/hosting-types-switch>` (i.e., On-Premise to Odoo Online
-  or Odoo.sh)
-* Migration from another ERP to Odoo
+  - Downgrading to a previous version of Odoo
+  - :doc:`Switching editions <maintain/enterprise>` (e.g., from Community to Enterprise)
+  - :doc:`Changing hosting type </administration/maintain/hosting_changes>` (e.g., from on-premise
+    to Odoo Online)
+  - Migrating from another ERP to Odoo
 
-.. note:: |assistance-contact|
+.. warning::
+   If your database contains custom modules, it cannot be upgraded until a version of your custom
+   modules is available for the target version of Odoo. For customers maintaining their own custom
+   modules, we recommend to parallelize the process by :ref:`requesting an upgraded database
+   <upgrade/request-test-database>` while also :doc:`upgrading the source code of your custom
+   modules </developer/howtos/upgrade_custom_db>`.
 
-.. seealso::
-   - :ref:`upgrade/sla`
 
-.. _upgrade/process-workflow:
+Upgrading in a nutshell
+-----------------------
 
-Process workflow
-================
+#. Request an upgraded test database (see :ref:`obtaining an upgraded test database
+   <upgrade/request-test-database>`).
 
-The upgrade process in a nutshell:
+#. If applicable, upgrade the source code of your custom module to be compatible with the new
+   version of Odoo (see :doc:`/developer/howtos/upgrade_custom_db`).
 
-#. You create a test upgrade request.
-#. Odoo processes the request automatically by running the database through an upgrade script, which
-   takes between 20 and 120 minutes.
-#. Odoo delivers a test database.
-#. You test your database for possible discrepancies (see :ref:`upgrade/test-guidance`).
-#. If there are any discrepancies, you report them to the Upgrade support team via the help portal
-   (see :ref:`upgrade/test-assistance`).
-#. We fix the issues and send you a new test database.
-#. Once you have completed the testing and are happy with the result, you decide on a date and time
-   when you stop users from accessing Odoo, freeze all data entries, and create an upgrade request
-   for the production upgrade.
-#. Odoo delivers the production database through the automated process.
-#. You restore it in your Production environment a few short hours later and continue working on the
-   newly upgraded database (this is done automatically on Odoo Online).
+#. Thoroughly test the upgraded database (see :ref:`testing the new version of the database
+   <upgrade/test_your_db>`).
 
-.. seealso::
-   - :doc:`Upgrade process for Odoo Online <upgrade/odoo_online>`
-   - :doc:`Upgrade process for Odoo.sh <upgrade/odoo_sh>`
-   - :doc:`Upgrade process for On-Premise <upgrade/on_premise>`
+#. Report any issue encountered during the testing to Odoo via the `support page
+   <https://odoo.com/help?stage=migration>`__.
 
-.. _upgrade/testing-phase:
+#. Once all issues are resolved and you are confident that the upgraded database can be used as
+   your main database without any issues, plan the upgrade of your production database.
 
-Testing
-=======
+#. Request the upgrade for the production database, rendering it unavailable for the time it takes
+   to complete the process (see :ref:`upgrading the production database <upgrade/upgrade-prod>`).
 
-This phase allows you to review an upgraded version of your database without affecting your
-production database in any way. We suggest that you run the test upgrade process at least once, but
-you can do it as many times as you need (one at a time).
+#. Report any issue encountered during the upgrade to Odoo via the `support page
+   <https://odoo.com/help?stage=post_upgrade>`__.
 
-Once you receive your upgraded test database, check that all data, processes, and functionality are
-still correct and working as expected.
+.. _upgrade/request-test-database:
 
-If you do find discrepancies, :ref:`report your issues <upgrade/test-assistance>` and :ref:`request
-a new test database <upgrade/test-db-request>` when the reported issues are fixed in the upgrade
-script.
-
-If you do not find any discrepancies, you can move on to the upgrade of your production database.
-
-.. important::
-   A test database is only intended for testing and remains completely unrelated to your present or
-   future production database. Any data you add, or changes you make, will not be reflected in your
-   upgraded production database.
-
-.. note::
-   Test databases are neutered and features are disabled to prevent them from having an impact on
-   the production database:
-
-   #. The serial number of the database is modified (to prevent it from sending information as if it
-      was the production database).
-   #. The :ref:`base URL of the database <domain-name/web-base-url>` is reset to
-      ``http://localhost:8069`` and the email domain to ``localhost``.
-   #. Scheduled actions are disabled (the calendar synchronization, the bank statement
-      synchronization, the planned automated actions, the fetching of incoming mail servers, etc.).
-   #. Outgoing mail servers are disabled by archiving the existing ones and adding a
-      fake/non-working one.
-   #. Payment providers and delivery carriers are reset to test environment.
-   #. Accounting localization Electronic Data Interchange (EDI) services are disabled.
-   #. A system parameter is set to tell the database has been neutered.
-
-.. _upgrade/test-db-request:
-
-Request a test database
-=======================
-
-Follow the instructions available per hosting type on the `website form
-<https://upgrade.odoo.com>`_ and select *Testing* purpose.
-
-.. image:: upgrade/test-purpose.png
-   :align: center
-   :alt: Selection of the "Testing" purpose in the upgrade form on Odoo
-
-.. _upgrade/test-guidance:
-
-Test guidance
-=============
-
-Every business and organization has its own operational needs and has to test its specific Odoo
-database individually. We recommend you look at `the test scenario
-<https://docs.google.com/document/d/1ypNs7JKPOsjNbKpdiKFH7Al6g6whZ9jr7f7duAQ5E1w/>`_ for further
-information.
-
-.. todo:: change link "test scenario" once the related doc is published
-
-.. _upgrade/test-assistance:
-
-Assistance
-----------
-
-If you encounter an issue in the **test database**, please get in touch with Odoo Upgrade Support
-via the `Odoo Support page <https://www.odoo.com/help>`_.
-
-Under the *Ticket Description* section, select *An issue related to my upgrade* ticket type.
-
-   .. image:: upgrade/test-assistance.png
-      :align: center
-      :alt: Selection of "An issue related to my upgrade" as Ticket Type in the support form on Odoo
-
-   .. warning::
-      If you choose another *Ticket Description* type, the request will be redirected to another
-      team. This will slow down the processing and response time.
-
-Please provide as much detail as you can (i.e., videos and screenshots to illustrate your issue).
-This will avoid clarifying questions and speed up the resolution process significantly.
-
-.. note::
-   * The purpose of the test phase is not to correct existing data or configurations in your
-     database.
-   * |assistance-contact|
-
-.. _upgrade/steps-production:
-
-The production launch
-=====================
-
-The production upgrade request is when you decide to upgrade your current database with all your
-production data (invoices, VAT returns, inventories, current orders) to a new version of your
-choice.
-
-After your :ref:`tests <upgrade/testing-phase>` are completed to your satisfaction, submit the
-request to upgrade your production database via our `website form <https://upgrade.odoo.com>`_.
-Select *Production* purpose.
-
-.. important::
-   Going into production without first testing may lead to:
-
-   - business interruptions (e.g., no longer having the possibility to validate an action)
-   - poor customer experiences (e.g., an eCommerce website that does not work correctly)
-
-.. _upgrade/production-assistance:
-
-Assistance
-----------
-
-If you encounter issues or problems in the **production database**, please get in touch with **Odoo
-Support**:
-
-#. Connect to our `Odoo Support page <https://www.odoo.com/help>`_.
-#. Under the *Ticket Description* section, select the appropriate type related to your issue but
-   **do not select** the option *An issue related to my upgrade*.
-
-   .. note::
-      After upgrading to production, the support will be provided by the Support team instead of the
-      Upgrade team.
-
-#. Please provide as much detail as you can (i.e., videos and screenshots to illustrate your issue).
-   This will avoid clarifying questions and speed up the resolution process significantly.
-
-   .. warning::
-      If you choose *An issue related to my upgrade* as ticket type, the request will be redirected
-      to another team than the support one and will slow down the processing and response time.
-
-.. _upgrade/assistance:
-
-Help
-====
-
-.. _upgrade/contact:
-
-Contact our upgrade service support
+Obtaining an upgraded test database
 -----------------------------------
 
-Should you have any more questions about the upgrade, do not hesitate to send a message to `Odoo
-Upgrade Team <mailto:upgrade@odoo.com>`_. We will be happy to answer it as soon as possible.
+The `Upgrade page <https://upgrade.odoo.com/>`_ is the main platform for requesting an upgraded
+database. However, depending on the hosting type, you can upgrade from the command line
+(on-premise), the `Odoo Online database manager <https://odoo.com/my/databases>`_, or your `Odoo.sh
+project <https://odoo.sh/project>`_.
 
-.. _upgrade/supported-versions:
+.. note::
+   The Upgrade platform follows the same `Privacy Policy <https://www.odoo.com/privacy>`_ as the
+   other Odoo.com services. Visit the `General Data Protection Regulation page
+   <https://www.odoo.com/gdpr>`_ to learn more about how Odoo handles your data and privacy.
 
-Supported versions
-------------------
+.. tabs::
 
-Please note that Odoo provides support and bug fixing only for the three last major versions of
-Odoo.
+   .. group-tab:: Odoo Online
 
-This is a factor to take into consideration before upgrading. If you are on an older version, we
-suggest you to prefer the most recent version to benefit from longer support (before having to
-upgrade again).
+      Odoo Online databases can be manually upgraded via the `database manager
+      <https://odoo.com/my/databases>`_.
+
+      The database manager displays all databases associated with the user's account. Databases
+      not on the most recent version of Odoo display an arrow in a circle icon next to their name,
+      indicating that they can be upgraded.
+
+      .. image:: upgrade/databases-page.png
+         :alt: The database manager with an upgrade button next to the name of a database.
+
+      Click the **arrow in a circle** icon to start the upgrade process. In the popup, fill in:
+
+      - The **version** of Odoo you want to upgrade to, usually the latest version
+      - The **email** address that should receive the link to the upgraded database
+      - The :guilabel:`Purpose` of the upgrade, which is automatically set to :guilabel:`Test` for
+        your first upgrade request
+
+      .. image:: upgrade/upgrade-popup.png
+         :alt: The "Upgrade your database" popup.
+
+      The :guilabel:`Upgrade in progress` tag is displayed next to the database name until
+      completion. Once the process succeeds, an email containing a link to the upgraded test
+      database is sent to the address provided. The database can also be accessed from the database
+      manager by clicking the dropdown arrow before the database name.
+
+      .. image:: upgrade/access-upgraded-db.png
+         :alt: Clicking the menu arrow displays the upgraded test database.
+
+   .. group-tab:: Odoo.sh
+
+      Odoo.sh is integrated with the upgrade platform to simplify the upgrade process.
+
+      .. image:: upgrade/odoo-sh-staging.png
+         :alt: Odoo.sh project and tabs
+
+      The **latest production daily automatic backup** is then sent to the `upgrade platform
+      <https://upgrade.odoo.com>`_.
+
+      Once the upgrade platform is done upgrading the backup and uploading it on the branch, it is
+      put in a **special mode**: each time a **commit is pushed** on the branch, a **restore
+      operation** of the upgraded backup and an **update of all the custom modules** occur. This
+      allows you to test your custom modules on a pristine copy of the upgraded database. The log
+      file of the upgrade process can be found in your newly upgraded staging build by going to
+      :file:`~/logs/upgrade.log`.
+
+      .. important::
+         In databases where custom modules are installed, their source code must be up-to-date with
+         the target version of Odoo before the upgrade can be performed. If there are none, the
+         "update on commit" mode is skipped, the upgraded database is built as soon as it is
+         transferred from the upgrade platform, and the upgrade mode is exited.
+
+         Check out the :doc:`/developer/howtos/upgrade_custom_db` page for more information.
+
+   .. group-tab:: On-premise
+
+      The standard upgrade process can be initiated by entering the following command line on the
+      machine where the database is hosted:
+
+      .. code-block:: console
+
+         $ python <(curl -s https://upgrade.odoo.com/upgrade) test -d <your db name> -t <target version>
+
+      The following command can be used to display the general help and the main commands:
+
+      .. code-block:: console
+
+         $ python <(curl -s https://upgrade.odoo.com/upgrade) --help
+
+      An upgraded test database can also be requested via the `Upgrade page
+      <https://upgrade.odoo.com/>`_.
+
+      .. important::
+         In databases where custom modules are installed, their source code must be up-to-date with
+         the target version of Odoo before the upgrade can be performed. Check out the
+         :doc:`/developer/howtos/upgrade_custom_db` page for more information.
+
+      .. note::
+         - For security reasons, only the person who submitted the upgrade request can download it.
+         - For storage reasons, the database's copy is submitted without a filestore to the upgrade
+           server. Therefore, the upgraded database does not contain the production filestore.
+         - Before restoring the upgraded database, its filestore must be merged with the production
+           filestore to be able to perform tests in the same conditions as it would be in the new
+           version.
+         - The upgraded database contains:
+
+           - A `dump.sql` file containing the upgraded database
+           - A `filestore` folder containing files extracted from in-database records into
+             attachments (if there are any) and new standard Odoo files from the targeted Odoo
+             version (e.g., new images, icons, payment provider's logos, etc.).
+             This is the folder that should be merged with the production filestore
+             in order to get the full upgraded filestore.
+
+.. note::
+   You can request multiple test databases if you wish to test an upgrade more than once.
+
+.. _upgrade/upgrade_report:
+
+.. note::
+   When an upgrade request is completed, an upgrade report is attached to the successful upgrade
+   email, and it becomes available in the Discuss app for users who are part of the "Administration
+   / Settings" group. This report provides important information about the changes introduced by
+   the new version.
+
+.. _upgrade/test_your_db:
+
+Testing the new version of the database
+---------------------------------------
+
+It is essential to spend some time testing the upgraded test database to ensure that you are not
+stuck in your day-to-day activities by a change in views, behavior, or an error message once the
+upgrade goes live.
+
+.. note::
+   Test databases are neutralized, and some features are disabled to prevent them from impacting the
+   production database:
+
+   #. Scheduled actions are disabled.
+   #. Outgoing mail servers are disabled by archiving the existing ones and adding a fake one.
+   #. Payment providers and delivery carriers are reset to the test environment.
+   #. Bank synchronization is disabled. Should you want to test the synchronization, contact your
+      bank synchronization provider to get sandbox credentials.
+
+Testing as many of your business flows as possible is strongly recommended to ensure they are
+working correctly and to get more familiar with the new version.
+
+.. admonition:: Basic test checklist
+
+   - Are there views that are deactivated in your test database but active in your production
+     database?
+   - Are your usual views still displayed correctly?
+   - Are your reports (invoice, sales order, etc.) correctly generated?
+   - Are your website pages working correctly?
+   - Are you able to create and modify records? (sales orders, invoices, purchases, users, contacts,
+     companies, etc.)
+   - Are there any issues with your mail templates?
+   - Are there any issues with saved translations?
+   - Are your search filters still present?
+   - Can you export your data?
+
+.. spoiler:: Example of end-to-end testing
+
+   - Checking a random product in your product catalog and comparing its test and production data to
+     verify everything is the same (product category, selling price, cost price, vendor, accounts,
+     routes, etc.).
+   - Buying this product (Purchase app).
+   - Confirming the reception of this product (Inventory app).
+   - Checking if the route to receive this product is the same in your production database
+     (Inventory app).
+   - Selling this product (Sales app) to a random customer.
+   - Opening your customer database (Contacts app), selecting a customer (or company), and checking
+     its data.
+   - Shipping this product (Inventory app).
+   - Checking if the route to ship this product is the same as in your production database
+     (Inventory app).
+   - Validating a customer invoice (Invoicing or Accounting app).
+   - Crediting the invoice (issuing a credit note) and checking if it behaves as in your production
+     database.
+   - Checking your reports' results (Accounting app).
+   - Randomly checking your taxes, currencies, bank accounts, and fiscal year (Accounting app).
+   - Making an online order (Website apps) from the product selection in your shop until the
+     checkout process and checking if everything behaves as in your production database.
+
+   This list is **not** exhaustive. Extend the example to your other apps based on your use of Odoo.
+
+If you face an issue while testing your upgraded test database, you can request the assistance of
+Odoo via the `support page <https://odoo.com/help?stage=migration>`__ by selecting the option
+related to testing the upgrade. In any case, it is essential to report any
+problem encountered during the testing to fix it before upgrading your production database.
+
+You might encounter significant differences with standard views, features, fields, and models during
+testing. Those changes cannot be reverted on a case-by-case basis. However, if a change introduced
+by a new version breaks a customization, it is the responsibility of the maintainer of your custom
+module to make it compatible with the new version of Odoo.
+
+.. tip::
+   Do not forget to test:
+
+   - Integrations with external software (EDI, APIs, etc.)
+   - Workflows between different apps (online sales with eCommerce, converting a lead all the way to
+     a sales order, delivery of products, etc.)
+   - Data exports
+   - Automated actions
+   - Server actions in the action menu on form views, as well as by selecting multiple records on
+     list views
+
+.. _upgrade/upgrade-prod:
+
+Upgrading the production database
+---------------------------------
+
+Once the :ref:`tests <upgrade/test_your_db>` are completed and you are confident that the upgraded
+database can be used as your main database without any issues, it is time to plan the go-live day. It
+can be planned in coordination with Odoo's upgrade support analysts, reachable via the `support page
+<https://odoo.com/help>`__.
+
+Your production database will be unavailable during its upgrade. Therefore, we recommend planning
+the upgrade at a time when the use of the database is minimal.
+
+As the standard upgrade scripts and your database are constantly evolving, it is also recommended
+to frequently request another upgraded test database to ensure that the upgrade process is
+still successful, especially if it takes a long time to finish. **Fully rehearsing the upgrade
+process the day before upgrading the production database is also recommended.**
+
+.. important::
+   - Going into production without first testing may lead to:
+
+     - Users failing to adjust to the changes and new features
+     - Business interruptions (e.g., no longer having the possibility to validate an action)
+     - Poor customer experience (e.g., an eCommerce website that does not work correctly)
+
+The process of upgrading a production database is similar to upgrading a test database with a few
+exceptions.
+
+.. tabs::
+
+   .. group-tab:: Odoo Online
+
+      The process is similar to :ref:`obtaining an upgraded test database
+      <upgrade/request-test-database>`, except for the purpose option, which must be set to
+      :guilabel:`Production` instead of :guilabel:`Test`.
+
+      .. warning::
+         Once the upgrade is requested, the database will be unavailable until the upgrade is
+         finished. Once the process is completed, it is impossible to revert to the previous
+         version.
+
+   .. group-tab:: Odoo.sh
+
+      The process is similar to :ref:`obtaining an upgraded test database
+      <upgrade/request-test-database>` on the :guilabel:`Production` branch.
+
+      .. image:: upgrade/odoo-sh-prod.png
+         :alt: View from the upgrade tab
+
+      The process is **triggered as soon as a new commit is made** on the branch. This
+      allows the upgrade process to be synchronized with the deployment of the custom modules'
+      upgraded source code.
+      If there are no custom modules, the upgrade process is triggered immediately.
+
+      .. important::
+         The database is unavailable throughout the process. If anything goes wrong, the platform
+         automatically reverts the upgrade, as it would be for a regular update. In case of success,
+         a backup of the database before the upgrade is created.
+
+      The update of your custom modules must be successful to complete the entire upgrade process.
+      Make sure the status of your staging upgrade is :guilabel:`successful` before trying it in
+      production. More information on how to upgrade your custom modules can be found on
+      :doc:`/developer/howtos/upgrade_custom_db`.
+
+   .. group-tab:: On-premise
+
+      The command to upgrade a database to production is similar to the one of upgrading a test
+      database except for the argument `test`, which must be replaced by `production`:
+
+      .. code-block:: console
+
+         $ python <(curl -s https://upgrade.odoo.com/upgrade) production -d <your db name> -t <target version>
+
+      An upgraded production database can also be requested via the `Upgrade page
+      <https://upgrade.odoo.com/>`_.
+      Once the database is uploaded, any modification to your production database will **not** be
+      present on your upgraded database. This is why we recommend not using it during the upgrade
+      process.
+
+      .. important::
+         When requesting an upgraded database for production purposes, the copy is submitted without
+         a filestore. Therefore, the upgraded database filestore must be merged with the production
+         filestore before deploying the new version.
+
+In case of an issue with your production database, you can request the assistance of Odoo via the
+`support page <https://odoo.com/help?stage=post_upgrade>`__ by selecting the option related to
+the upgrade in production.
 
-.. seealso::
-   :doc:`maintain/supported_versions`
 
 .. _upgrade/sla:
 
 Service-level agreement (SLA)
-=============================
+-----------------------------
 
 With Odoo Enterprise, upgrading a database to the most recent version of Odoo is **free**, including
 any support required to rectify potential discrepancies in the upgraded database.
@@ -230,7 +376,7 @@ Information about the upgrade services included in the Enterprise Licence is ava
 upgrade services you can expect.
 
 Upgrade services covered by the SLA
------------------------------------
+===================================
 
 Databases hosted on Odoo's cloud platforms (Odoo Online and Odoo.sh) or self-hosted (On-Premise) can
 benefit from upgrade services at all times for:
@@ -245,7 +391,7 @@ Upgrade services are limited to the technical conversion and adaptation of a dat
 modules and data) to make it compatible with the version targeted by the upgrade.
 
 Upgrade services not covered by the SLA
----------------------------------------
+=======================================
 
 The following upgrade-related services are **not** included:
 
@@ -256,9 +402,6 @@ The following upgrade-related services are **not** included:
   <studio/automated-actions/action>`; and
 - **training** on using the upgraded version's features and workflows.
 
-.. note:: |assistance-contact|
-
 .. seealso::
-   - :doc:`Upgrade FAQ <upgrade/faq>`
    - :doc:`Odoo.sh documentation <odoo_sh>`
    - :doc:`Supported Odoo versions <maintain/supported_versions>`

content/administration/upgrade/faq.rst

@@ -1,228 +0,0 @@
-.. |assistance-contact| replace::
-   If you need Odoo assistance on this matter, please get in touch with your Odoo Account Manager or
-   our `Sales department`_.
-.. _Sales department: mailto:sales@odoo.com
-
-===
-FAQ
-===
-
-.. _upgrade-faq/why:
-
-Why upgrade
-===========
-
-* You benefit from the latest features of the :ref:`new major version
-  <upgrade-faq/release-notes>` released by Odoo.
-* If you are in an :ref:`unsupported version <upgrade/supported-versions>`, you get a new version
-  with support.
-
-.. _upgrade-faq/when:
-
-When to upgrade
-===============
-
-Whenever you want. You can make your upgrade request as soon as a new version is released or when
-your version turns unsupported, and you still wish to enjoy support.
-
-.. _upgrade-faq/availability:
-
-Availability of the new version
-===============================
-
-As soon as Odoo announces the release of a new major version, you can create a test upgrade request
-to try the latest version. Please note that at this point, the upgrade scripts will only have been
-tested with demo data. Please report any issue you might encounter while testing via the `Odoo
-Support page <https://www.odoo.com/help>`_ and make sure to be happy with your test version before
-requesting the upgrade of your database in production.
-
-.. _upgrade-faq/duration:
-
-Duration of the upgrade
-=======================
-
-It is impossible to give time estimates for every upgrade request.
-
-In general, the "smaller" the database, the quickest the upgrade request is completed. A single-user
-database that uses only CRM will be processed faster than a multi-company, multi-user database that
-uses Accounting, Sales, Purchase, and Manufacturing.
-
-You can expect the time it takes for the platform to upgrade the test database to be similar to the
-production upgrade.
-
-.. _upgrade-faq/project:
-
-Duration of the upgrade project
--------------------------------
-
-It depends on the user involvement (the time spent on testing, reporting problems, etc.) and the
-issues encountered that might need to be addressed by our technical team.
-
-So, in a nutshell, what can impact your upgrade lead time?
-
-* Source & targeted versions
-* Installed apps
-* Volume of data
-* Amount of customization (models, fields, methods, workflows, reports, website, etc.)
-* Installation of new apps or configuration changes after the start of the test phase
-* User commitment
-
-.. _upgrade-faq/custom-modules:
-
-Upgrade of the custom modules
-=============================
-
-As stated in our :doc:`/legal/terms/enterprise`, section :ref:`charges_standard`, this optional
-service is subject to additional fees.
-
-Depending on your situation, the custom code could be upgraded by our services, by one of our
-partners, or you can do it yourself.
-
-.. note:: |assistance-contact|
-
-.. _upgrade-faq/upgrade-or-migration:
-
-Upgrade or Migration
-====================
-
-An upgrade is switching to a newer version of Odoo, while a migration reflects the change of
-:ref:`editions <upgrade-faq/editions-change>` or change of :ref:`hosting type
-<upgrade-faq/hosting-types-switch>`.
-
-.. note:: |assistance-contact|
-
-.. _upgrade-faq/editions-change:
-
-Editions change (from Community to Enterprise)
-==============================================
-
-The upgrade always returns an Enterprise edition of Odoo, whether the database you sent was a
-community or enterprise edition. It is required to have an enterprise subscription to upgrade.
-
- .. note::
-    If you need assistance on this matter,  please contact us via the `Odoo Support page
-    <https://www.odoo.com/help>`_.
-
-.. seealso::
-   - `Editions <https://www.odoo.com/page/editions>`_
-
-.. _upgrade-faq/hosting-types-switch:
-
-Switching the hosting types (On-premise vs. Odoo Online vs. Odoo.sh)
-====================================================================
-
-An upgrade does not cover a change of `Hosting types <https://www.odoo.com/page/hosting-types>`_.
-
-Open the following link to get :doc:`more information about how to change your hosting type
-<../maintain/hosting_changes>`.
-
-.. note:: |assistance-contact|
-
-.. _upgrade-faq/upgrade-report:
-
-The Upgrade Report
-==================
-
-When an upgrade request completes successfully (test or production), you receive an email
-notification about it that includes an 'Upgrade Report'. This report is also sent to you via the
-Discuss app. It contains valuable information regarding changes that occurred during the upgrade.
-While it serves as a guide to possible issues to look out for, it is not an exhaustive list. It
-remains imperative that you test the upgraded database thoroughly and report any discrepancies you
-might find, before you decide to upgrade your production database.
-
-.. _upgrade-faq/custom-views:
-
-Custom views
-============
-
-During the upgrade, some custom views might get disabled for technical reasons. Therefore they might
-have to be fixed after the upgrade. The :ref:`Upgrade Report <upgrade-faq/upgrade-report>` that is
-generated after the upgrade is available in the Discuss app, and lists all the custom views that
-might be impacted by this.
-
-.. _upgrade-faq/release-notes:
-
-Release Notes by version
-========================
-
-Open our `Release Note <https://www.odoo.com/page/release-notes>`_ page to get a summary of the new
-features and improvements made in each version.
-
-How long is my test available for
-=================================
-
-An Odoo Online test database is available for one month by default. We can extend this trial period
-upon request. For Odoo.sh or on-premise, there is no restriction.
-
-How many tests to perform before upgrading to production?
-=========================================================
-
-As many as needed. When you are comfortable with the database, run a last test upgrade 48 hours
-before requesting your production upgrade and test your workflows one last time.
-
-How to/Where to report upgrade issues?
-======================================
-
-If you encounter issues during the upgrade process, please contact the Odoo Support through the
-`Odoo Support page <https://www.odoo.com/help>`_.
-
-- To report an issue discovered during the testing phase, please select **An issue related to my
-  upgrade (test phase)**.
-- To report an issue discovered post-upgrade, please select **An issue related to my upgrade
-  (production)**.
-
-Upgrading to production
-=======================
-
-Once you have completed testing and are happy with the result, you decide on a date and time when
-you stop users from accessing Odoo, freeze all data entries, and create an upgrade request for the
-production upgrade.
-
-How is my data handled in the Upgrade Platform?
-===============================================
-
-The Odoo Upgrade platform uses the same Privacy Policy as the rest of Odoo.com services.
-
-Your data is hosted on servers that follow our security guidelines, namely:
-
-- SSL - All web connections to client instances are protected with 256-bit SSL encryption
-  (HTTPS with a 2048-bit modulus SSL certificate), and running behind Grade A SSL stacks. All our
-  certificate chains are using SHA-2 already.
-- Safe System - Our servers are running recent Linux distribution with up-to-date security patches,
-  with firewall and intrusion countermeasures (not disclosed for obvious reasons).
-
-Servers are located at the same locations as our Cloud providers with the following services:
-
-- Restricted perimeter, physically accessed by authorized data center employees only
-- Physical access control with security badges or biometrical security
-- Security cameras monitoring the data center locations 24/7
-- Security personnel on-site 24/7
-
-The uploaded and migrated databases uploaded to the Upgrade platform are kept for up to 3 months and
-are permanently deleted following that period.
-
-You can learn more about privacy and data handling at Odoo by visiting our `General Data Protection
-Regulation page <https://www.odoo.com/gdpr>`_.
-
-Rolling Release (applicable to Odoo Online databases)
-=====================================================
-
-This feature allows customers to upgrade their database directly from a message prompt sent to the
-database administrator as soon as the new version is released. Odoo first tests the upgrade to the
-next version. The rolling release upgrade option is displayed if the automated tests are successful.
-The message offers two options:
-
-#. To 'Upgrade Now', which immediately triggers the upgrade of your live production database.
-
-#. To take you to your `database manager <https://www.odoo.com/my/databases/>`_ where you can
-   `request an upgraded test database <https://upgrade.odoo.com/#online/>`_ and check the upgraded
-   test database for any discrepancies.
-
-When you choose to proceed with the production upgrade directly, make sure all users have saved
-their work and are logged out. The upgrade takes approximately 15 minutes. During this time your
-database is unreachable. If you notice any problem after the upgrade, please report it via the `Odoo
-Support page <https://www.odoo.com/help>`_.
-
-.. note::
-   If you are using the Website or Studio app, we recommend you always do a test upgrade before
-   upgrading your production instance.

content/administration/upgrade/odoo_online.rst

@@ -1,92 +0,0 @@
-===========
-Odoo Online
-===========
-
-Odoo databases can be manually upgraded directly from the main Odoo website. To upgrade an Odoo
-database, navigate to the `database manager <https://www.odoo.com/my/databases>`_ page and sign in.
-
-The database manager page displays all of the Odoo databases associated with the user's account. Any
-databases that are not already on the most recent version of Odoo display an **arrow in a circle**
-icon next to the database name, indicating that the database can be upgraded.
-
-.. image:: odoo_online/databases-page.png
-   :align: center
-   :alt: The database manager page with an upgrade button next to the name of a database.
-
-.. important::
-   - If the database's version is **lower** than the latest major release: the database must be
-     upgraded within two months. After these two months, an automatic upgrade is initiated.
-   - If the database's version is **equal** to or **higher** than the latest major release:
-     you can disregard the invitation to upgrade, as the database probably would not benefit from
-     new features every two months.
-
-If a database is *not* on the latest online version, its administrator should receive an invitation
-to upgrade on the database's dashboard, displayed as an **arrow in a circle**.
-
-.. image:: odoo_online/database-notification.png
-   :alt: Invitation to upgrade on the database dashboard.
-
-.. note::
-   Versions that are not supported anymore become deprecated and must be updated to avoid
-   security issues. It is recommended to initiate the upgrade yourself and not wait for the
-   automatic upgrade, as the former method allows you to request a test upgrade of the database to
-   check for any discrepancies.
-
-Test database
-=============
-
-Click on the **arrow in a circle** icon to start the upgrade process. On the :guilabel:`Upgrade your
-database` pop-up, select the version of Odoo that the platform will be upgraded to. In the
-:guilabel:`Email to notify` field, enter an email address that will receive email notifications
-about the database upgrade.
-
-There is also a :guilabel:`Purpose` section on the pop-up that is used to specify the reason for the
-upgrade. However, at this stage of the process, the only selectable option is :guilabel:`Test`, as
-Odoo requires users to create a test copy of the upgraded database before converting the actual
-database.
-
-.. image:: odoo_online/upgrade-pop-up.png
-   :align: center
-   :alt: The "Upgrade your database" pop-up.
-
-After filling out the form, click the :guilabel:`Upgrade` button. The pop-up disappears and the
-database being upgraded shows a red :guilabel:`Upgrade in progress` tag next to its name. An email
-confirming that the upgrade is in progress is also sent to the email address specified on the
-pop-up.
-
-.. image:: odoo_online/upgrade-in-progress.png
-   :align: center
-   :alt: The "Upgrade in progress" tag next to the database name.
-
-Once the upgrade is complete, a new test database appears on the `database manager
-<https://www.odoo.com/my/databases>`_ page. To access the test database, click the drop-down arrow
-(:guilabel:`⯆`) to the left of the main database's name. Doing so makes the test version appear
-below it. Finally, click the green :guilabel:`Connect` button on the right side of the test
-version's row to go to the database.
-
-.. image:: odoo_online/test-database.png
-   :align: center
-   :alt: A test database on the database manager page.
-
-Except for being on the newer version of Odoo, the test database is an exact copy of the one being
-upgraded. It is important to do extensive testing in this database to ensure that the upgrade has
-not altered or corrupted any data, and that all workflows still proceed as expected.
-
-Production database
-===================
-
-After confirming the integrity of the new version, return to the `database manager
-<https://www.odoo.com/my/databases>`_ page. Once again, click on the **arrow in a circle** icon next
-to the database being upgraded. The :guilabel:`Upgrade your database` pop-up appears as before,
-except that there is now a :guilabel:`Production` option under the :guilabel:`Purpose` section.
-
-Select the :guilabel:`Production` option and then click :guilabel:`Upgrade` to begin the upgrade
-process. As before, a notification email is sent to the email address provided and a red
-:guilabel:`Upgrade in progress` tag appears next to the name of the database.
-
-The production database is then taken offline and will be upgraded automatically. The time it takes
-to upgrade the production database should be similar to the time that was necessary to upgrade the
-test database. Make sure to inform database users of the scheduled downtime.
-
-After the upgrade is finished, the :guilabel:`Upgrade in progress` tag disappears and the database
-is upgraded to the version specified.

content/administration/upgrade/odoo_sh.rst

@@ -1,132 +0,0 @@
-=======
-Odoo.sh
-=======
-
-.. _upgrade/odoo_sh/overview:
-
-Overview
-========
-
-Odoo.sh is integrated with the upgrade platform to make the upgrade process easier.
-
-.. note::
-   The :guilabel:`Upgrade` tab is available in the branches view. It is only available for valid
-   projects with a valid production build.
-
-.. image:: odoo_sh/odoo-sh-menu.png
-   :align: center
-   :alt: Click on the upgrade menu
-
-The suggested upgrade steps on Odoo.sh are:
-
-#. On a :guilabel:`Development` branch, upgrade your custom modules to keep them compatible with the
-   new version and thoroughly **test them**.
-#. Switch that branch to the :guilabel:`Staging` branch, **upgrade** the last daily production
-   backup and **test it**. Write upgrade scripts if necessary.
-#. Trigger the production upgrade from your :guilabel:`Production` branch and sit tight.
-
-.. seealso::
-   - :doc:`../../administration/upgrade`
-   - :doc:`Upgrade FAQ <../upgrade/faq>`
-   - :doc:`Introduction to Odoo.sh <../odoo_sh/overview/introduction>`
-
-.. _upgrade/odoo_sh/custom-modules:
-
-Upgrade your custom modules
-===========================
-
-The first step is to upgrade your custom modules to keep them compatible with the new version. Fork
-your :guilabel:`Production` branch in the :guilabel:`Development` stage, then go to the settings of
-your :guilabel:`Development` branch and select the Odoo version you target. If needed, modify your
-code to be compatible with the new version. Make sure to **test** your features are still working
-correctly.
-
-.. note::
-   Depending on your contract, the upgrade of your custom modules can be done by yourself, by your
-   Partner or by Odoo (if you hold a subscription including maintenance of customizations).
-
-.. _upgrade/odoo_sh/testing-phase:
-
-Upgrade your database on a staging branch
-=========================================
-
-Take the upgraded development branch and drag & drop it to :guilabel:`Staging`.
-
-Go to the :guilabel:`Upgrade` tab and select the :guilabel:`target version`. Then, click on
-:guilabel:`Test Upgrade`.
-
-.. image:: odoo_sh/odoo-sh-staging.png
-   :align: center
-   :alt: Odoo.sh project and tabs
-
-The **latest production daily automatic backup** is sent to the
-`upgrade platform <https://www.upgrade.odoo.com>`_ to start the upgrade test process.
-
-.. note::
-   You can follow the upgrade process by going to the :guilabel:`Upgrade` menu of your
-   :guilabel:`Production` branch.
-
-When the upgraded backup is ready on the `upgrade platform <https://www.upgrade.odoo.com>`_, it is
-automatically downloaded back to your project.
-
-The branch is now in a **special mode**: each time a **commit is pushed** on the branch, a
-**restore operation** of the upgraded backup occurs, and an **update of all the custom modules**
-happens. This allows you to quickly iterate on your custom modules upgrade scripts. The log file of
-the upgrade process can be found at :file:`~/logs/upgrade.log` in your newly upgraded staging build.
-
-.. note::
-   - The **special upgrade mode** is automatically closed after 30 days.
-   - It may happen that custom modules are no longer needed after an upgrade. Custom modules in the
-     upgraded database are set to be updated. If the modules are missing in the code, the update
-     fails, thus failing the whole process. An empty module with a manifest and possibly some custom
-     upgrade script are necessary to clean up the database. The complete removal of the module has
-     to be handled afterwards.
-
-Functionally test your upgraded database
-========================================
-
-Now that the test upgraded database is available on your staging branch, **thoroughly test it** and
-make sure everything runs as it's supposed to. Once you are satisfied with the result, you are ready
-to upgrade your production database.
-
-Production upgrade
-==================
-
-Once you are happy with your testing, you can start the process on the :guilabel:`Production`
-branch.
-
-On your :guilabel:`Production` branch, go to the :guilabel:`Upgrade` tab, select the
-:guilabel:`targeted version` and click on the :guilabel:`start Upgrade` button.
-
-.. image:: odoo_sh/odoo-sh-prod.png
-   :align: center
-   :alt: View from the upgrade tab
-
-The actual process is **triggered as soon as you push a new commit** in your branch. Make sure you
-are pushing code that is compatible with the new version. For example by merging the code from your
-upgraded staging branch.
-
-.. note::
-   You can see the progress of the upgrade by going to the :guilabel:`Upgrade` tab of the main
-   branch.
-
-.. image:: odoo_sh/odoo-sh-progress.png
-   :align: center
-   :alt: View showing the progress of the upgrade
-
-.. important::
-   Your database is unavailable throughout the process.
-
-.. note::
-   If anything goes wrong, the platform automatically reverts the upgrade, the same as it would be
-   for a regular update. In case of success, a backup is always made.
-
-The update of your custom modules must be successful to complete the entire upgrade process. Make
-sure the status of your staging upgrade is :guilabel:`successful` before trying it in production.
-
-.. note::
-   It may happen that custom modules are no longer needed after an upgrade. Custom modules in the
-   upgraded database are set to be updated. If the modules are missing in the code, the update
-   fails, thus failing the whole process. An empty module with a manifest and possibly some custom
-   upgrade script are necessary to clean up the database. The complete removal of the module has to
-   be handled afterwards.

content/administration/upgrade/on_premise.rst

@@ -1,76 +0,0 @@
-==========
-On-Premise
-==========
-
-Test upgrade request
-====================
-
-There are two ways to create your upgrade request.
-
-Upgrade request via command line
---------------------------------
-
-For technically-advanced users and partners, the upgrade process can be initiated via the following
-command line on the server where the database is hosted:
-
-:command:`python <(curl -s https://upgrade.odoo.com/upgrade) test -d <your db name> -t
-<target version>`
-
-The above command creates the database dump, sends it to the upgrade platform, and initiates the
-automated upgrade process. During the upgrade, you can follow the live logs on your screen.
-Once the upgrade process is completed successfully, the upgraded database is restored onto the
-server (as a duplicate test database).
-
-Upgrade request via the Odoo Upgrade Portal
--------------------------------------------
-
-#. Download a recent copy of your database and select the option :guilabel:`pg_dump custom format
-   (without filestore)`.
-#. Upload this dump file at https://upgrade.odoo.com and select *Testing* as the aim.
-   Odoo performs the automated upgrade process. Once it is completed, you receive an email with a
-   link to download the upgrade database dump file.
-#. Import the upgraded database into your on-premise environment and manually test all processes and
-   workflows.
-
-.. note::
-   - For security reasons, only the person who submitted the upgrade request is able to download it.
-   - Any problem found during testing should be reported via the `helpdesk
-     <https://odoo.com/help>`_.
-   - For storage reasons, the copy of your database is submitted without a filestore to the upgrade
-     server. Therefore, the upgraded database does not contain the production filestore.
-   - Before restoring the upgraded database, its filestore must be merged with the production
-     filestore to be able to perform tests in the same conditions as it would be in the new version.
-   - The upgraded database contains:
-
-      - A `dump.sql` file containing the upgraded database.
-      - A `filestore` folder containing files that were extracted from in-database records into
-        attachments (if there are any) and new standard Odoo files from the targeted Odoo version
-        (like new images, icons, payment provider's logos, etc.). This is the folder that should be
-        merged with the production filestore in order to get the full upgraded filestore.
-
-Upgrade your production database
-================================
-
-Once you have completed the testing successfully, you can proceed to upgrade your live database in
-production. Download your upgraded database from the link in the email and import it onto your live
-environment.
-
-.. important::
-   - Same as in the test phase, when requesting an upgrade for production purposes, the copy of your
-     database is submitted without a filestore.
-   - Therefore, the upgraded database filestore must be merged with the production filestore before
-     deploying the new version.
-
-Custom modules (if applicable)
-==============================
-
-The upgrade of a database that contains custom modules is a two-step process.
-
-#. The standard upgrade is done when your upgrade request is completed.
-#. Your custom modules also need to be upgraded to keep them compatible with the new version.
-
-Depending on your contract, the upgrade of your custom modules can be done
-
-#. by yourself.
-#. by your Partner.
-#. by Odoo (if you hold a subscription to 'Maintenance of Customizations').

content/applications/finance/accounting.rst

@@ -203,8 +203,7 @@ available methods are standard price, average price, :abbr:`LIFO (Last-In, First
 :abbr:`FIFO (First-In, First-Out).`
 
 .. seealso::
-   :doc:`View the impact of the valuation methods on transactions
-   <../inventory_and_mrp/inventory/management/reporting/inventory_valuation_config>`
+   :doc:`../inventory_and_mrp/inventory/warehouses_storage/inventory_valuation/inventory_valuation_config`
 
 Retained earnings
 =================

content/applications/finance/accounting/bank/bank_synchronization.rst

@@ -107,9 +107,9 @@ If your connection with the proxy is disconnected, you can reconnect with the pr
 :guilabel:`Fetch Account` button.
 
 .. note::
-   This disconnection can be caused by the Odoo support. In this case, please contact the `support
-   <https://www.odoo.com/help>`_ directly with your client id or the reference of the error listed
-   in the chatter.
+   If you are unable to reconnect using the :guilabel:`Fetch Account` button, please contact the
+   `support <https://www.odoo.com/help>`_ directly with your client id or the reference of the error
+   listed in the chatter.
 
 .. _MigrationOnlineSync:
 

content/applications/finance/accounting/bank/reconciliation.rst

@@ -2,94 +2,135 @@
 Bank reconciliation
 ===================
 
-Overview
-========
+**Bank reconciliation** is the process of matching your :doc:`bank transactions <transactions>` with
+your business records, such as :doc:`customer invoices <../customer_invoices>`, :doc:`vendor bills
+<../vendor_bills>`, and :doc:`payments <../payments>`. Not only is this compulsory for most
+businesses, but it also offers several benefits, such as reduced risk of errors in financial
+reports, detection of fraudulent activities, and improved cash flow management.
 
-Matching your bank statements with your accounting records can be a tedious task. You need to find the corresponding invoices, compare the amounts and partners' details with those in the bank statement. These steps can take a lot of time. Luckily, with Odoo you can very easily match your invoices or any other payment document with your bank statements.
-
-Two options of the reconciliation process exist in Odoo.
-
-1. We can directly specify the payment on the invoice
-2. We can reconcile open invoices with bank statements
-
-Configuration
-=============
-
-No special configuration is necessary to record invoices. All we need
-to do is to install the accounting app.
-
-.. image:: reconciliation/use01.png
-
-Use cases
-=========
-
-Case 1: Payments registration
------------------------------
-
-We received the proof of payment of our invoice in the amount of 2100 euros issued to
-Smith & Co.
-
-We start at our issued Invoice of 2100 euros for Smith & Co. Because the
-sold product is a service we demand an immediate payment. Our accountant
-only handles bank statements at the end of week, so we have to mark
-this invoice as paid immediately in order to indicate that we can start rendering services to our
-customer.
-
-Our customer send us a payment confirmation. We can thus register a
-payment and mark the invoice as paid.
-
-.. image:: reconciliation/use02.png
-
-By clicking on **register payment,** we are telling Odoo that our
-customer has paid the Invoice. We thus have to specify the amount and the
-payment method.
-
-.. image:: reconciliation/use03.png
-
-Now we can always find the payment details in the Invoice by clicking on the
-:menuselection:`Info --> Open Payment`.
-
-.. image:: reconciliation/use04.png
-
-The invoice has been paid and **the reconciliation has been done
-automatically.**
-
-Case 2: Bank statements reconciliations
----------------------------------------
-
-We start at our issued Invoice of 3000 euros for Smith & Co. Let's also
-assume that other Invoices are open for different customers.
-
-.. image:: reconciliation/use05.png
-
-We receive our bank statement and find that not only the invoice issued to Smith & Co has
-been paid, but the one to Buzz of 92 euros as well.
-
-**Import** or **Create** the bank statements. Please refer to the
-documents from the Bank Feeds section.
-
-.. image:: reconciliation/use06.png
-
-On the dashboard, click on **Reconcile # Items**
-
-.. image:: reconciliation/use07.png
-
-If everything was right (correct partner name, right amount) odoo will
-do the reconciliations **automatically**.
-
-.. image:: reconciliation/use08.png
-
-If some issues are found, you will need to take **manual actions**.
-
-For example, if the partner is missing from your bank statement, just
-fill it in :
-
-.. image:: reconciliation/use09.png
-
-If the payment is done with a down payment, just check if it is all
-right and validate all related payments :
-
-.. image:: reconciliation/use10.png
+Thanks to the bank :doc:`reconciliation models <reconciliation_models>`, Odoo pre-selects the
+matching entries automatically.
 
 .. seealso::
-   :doc:`bank_synchronization`
+   - `Odoo Tutorials: Bank reconciliation
+     <https://www.odoo.com/slides/slide/bank-reconciliation-2724>`_
+   - :doc:`bank_synchronization`
+   - :doc:`transactions`
+
+Bank reconciliation view
+========================
+
+To access a bank journal's **reconciliation view**, go to your :guilabel:`Accounting Dashboard` and
+either:
+
+- click the journal name (e.g., :guilabel:`Bank`) to display all transactions, including those
+  previously reconciled or
+- click the :guilabel:`Reconcile items` button to display all transactions Odoo pre-selected for
+  reconciliation. You can remove the :guilabel:`Not Matched` filter from the search bar to include
+  previously reconciled transactions.
+
+.. image:: reconciliation/bank-card.png
+   :alt: Reaching the bank reconciliation tool from your accounting dashboard
+
+The bank reconciliation view is structured into three distinct sections: transactions, counterpart
+entries, and resulting entry.
+
+.. image:: reconciliation/user-interface.png
+   :alt: The user interface of the reconciliation view of a bank journal.
+
+Transactions
+   The transactions section on the left shows all bank transactions, with the newest displayed
+   first. Click a transaction to select it.
+
+Counterpart entries
+   The counterpart entries section on the bottom right displays the options to match the selected
+   bank transaction. Multiple tabs are available, including
+   :ref:`reconciliation/existing-entries`, :ref:`reconciliation/batch-payments`,
+   :ref:`reconciliation/manual-operations`, and :guilabel:`Discuss`, which contains the chatter for
+   the selected bank transaction.
+
+Resulting entry
+   The resulting entry section on the top right displays the selected bank transaction matched with
+   the counterpart entries and includes any remaining debits or credits. In this section, you can
+   validate the reconciliation or mark it as :guilabel:`To Check`. Any :ref:`reconciliation model
+   buttons <reconciliation/button>` are also available in the resulting entry section.
+
+Reconcile transactions
+======================
+
+Transactions can be matched automatically with the use of :doc:`reconciliation models
+<reconciliation_models>`, or they can be matched with :ref:`existing entries
+<reconciliation/existing-entries>`, :ref:`batch payments <reconciliation/batch-payments>`,
+:ref:`manual operations <reconciliation/manual-operations>`, and :ref:`reconciliation model buttons
+<reconciliation/button>`.
+
+#. Select a transaction among unmatched bank transactions.
+#. Define the counterpart. There are several options for defining a counterpart, including
+   :ref:`matching existing entries <reconciliation/existing-entries>`, :ref:`manual operations
+   <reconciliation/manual-operations>`, :ref:`batch payments <reconciliation/batch-payments>`, and
+   :ref:`reconciliation model buttons <reconciliation/button>`.
+#. If the resulting entry isn't fully balanced, balance it by adding another existing counterpart
+   entry or writing it off with a :ref:`manual operation <reconciliation/manual-operations>`.
+#. Click the :guilabel:`Validate` button to confirm the reconciliation and move to the next
+   transaction.
+
+.. tip::
+   If you aren't sure how to reconcile a particular transaction and would like to deal with it
+   later, use the :guilabel:`To Check` button instead. All transactions marked as :guilabel:`To
+   Check` can be displayed using the :guilabel:`To Check` filter.
+
+.. note::
+   Bank transactions are posted on the **journal's suspense account** until reconciliation. At this
+   point, reconciliation modifies the transaction journal entry by replacing the bank suspense
+   account with the corresponding receivable, payable, or outstanding account.
+
+.. _reconciliation/existing-entries:
+
+Match existing entries
+----------------------
+
+This tab contains matching entries Odoo automatically pre-selects according to the reconciliation
+models. The entry order is based on :doc:`reconciliation models <reconciliation_models>`, with
+suggested entries appearing first.
+
+.. tip::
+   The search bar within the :guilabel:`Match Existing Entries` tab allows you to search for
+   specific journal items.
+
+.. _reconciliation/batch-payments:
+
+Batch payments
+--------------
+
+`Batch payments <payments/batch-payments>`_ allow you to group different payments to ease
+reconciliation. Use the :guilabel:`Batch Payments` tab to find batch payments for customers and
+vendors. Similarly to the :guilabel:`Match Existing Entries` tab, the :guilabel:`Batch Payments` tab
+has a search bar that allows you to search for specific batch payments.
+
+.. _reconciliation/manual-operations:
+
+Manual operations
+-----------------
+
+If there isn't an existing entry to match the selected transaction, you may instead wish to
+reconcile the transaction manually by choosing the correct account and amount. Then, complete any
+of the relevant optional fields.
+
+.. tip::
+   You can use the :guilabel:`fully paid` option to reconcile a payment, even in cases where only a
+   partial payment is received. A new line appears in the resulting entry section to reflect the
+   open balance registered on the Account Receivable by default. You can choose another
+   account by clicking on the new line in the resulting entry section and selecting the
+   :guilabel:`Account` to record the open balance.
+
+   .. image:: reconciliation/fully-paid.png
+      :alt: Click on fully paid to manually set an invoice as entirely paid.
+
+.. _reconciliation/button:
+
+Reconciliation model buttons
+----------------------------
+
+Use a :doc:`reconciliation model <reconciliation_models>` button for manual operations that are
+frequently used. These custom buttons allow you to quickly reconcile bank transactions manually and
+can also be used in combination with existing entries.

content/applications/finance/accounting/bank/reconciliation_models.rst

@@ -1,129 +1,123 @@
 =====================
-Reconciliation Models
+Reconciliation models
 =====================
 
-Once the bank statements are correctly imported, it is essential to *reconcile* the records properly
-and ensure all *Journal Entries* are balanced and in agreement. To ease and speed up the
-reconciliation process, you can configure **Reconciliation Models**, which are particularly useful
-with recurrent entries such as bank fees.
+Reconciliation models are used to automate the :doc:`bank reconciliation <reconciliation>` process,
+which is especially handy when dealing with recurring entries like bank fees. Reconciliation models
+can also be helpful in handling :doc:`cash discounts <../customer_invoices/cash_discounts>`.
 
-.. todo:: Add a link to the Reconciliation process in the paragraph above, once the doc will have
-   been updated.
-
-.. note::
-   Reconciliation Models are also useful to handle *Cash Discounts*. Please refer to
-   :doc:`this documentation <../customer_invoices/cash_discounts>` for more
-   information.
-
-.. _reconciliation_models_types:
-
-Types of Reconciliation Models
-==============================
-
-There are three types of Reconciliation Models:
-
-#. :ref:`Write-off Button <reconciliation_models_button>`
-#. :ref:`Suggestion of counterpart values <reconciliation_models_suggestion>`
-#. :ref:`Match existing invoices/bills <reconciliation_models_match>`
-
-.. _reconciliation_models_button:
-
-Manually create a write-off on clicked button
----------------------------------------------
-
-When you are reconciling an entry with an *Open Balance*, you can use the buttons available under
-the *Manual Operations* tab to pre-fill all the values automatically, before validating the
-reconciliation. Each button is a different Reconciliation Model.
-
-.. image:: reconciliation_models/reconciliation_models_button.png
-   :align: center
-   :alt: Example of a Reconciliation Model with a write-off button in Odoo Accounting
-
-.. _reconciliation_models_suggestion:
-
-Suggest counterpart values
---------------------------
-
-This type of Reconciliation Model suggests immediately counterpart values that only need to be
-validated. This automation is based on a set of rules defined in the reconciliation model.
-
-.. image:: reconciliation_models/reconciliation_models_suggestion.png
-   :align: center
-   :alt: Example of a Reconciliation Model that suggests counterpart values in Odoo Accounting
-
-.. _reconciliation_models_match:
-
-Match existing invoices/bills
------------------------------
-
-This type of Reconciliation Model automatically selects the right Customer Invoice or Vendor Bill
-that matches the payment. All that is left to do is to validate the entry. This automation is based
-on a set of rules defined in the reconciliation model.
-
-.. image:: reconciliation_models/reconciliation_models_match.png
-   :align: center
-   :alt: Example of a Reconciliation Model that matches existing invoices and bills automatically
-         in Odoo Accounting
-
-Configuration
-=============
-
-To manage or create new **Reconciliation Models**, go to :menuselection:`Accounting -->
-Reconciliation --> Reconciliation Models`. Alternatively, you can also open this menu from the
-Accounting Overview, by going to your Bank Journal card, clicking on the three little dots, and then
-on *Reconciliation Models*.
-
-.. image:: reconciliation_models/reconciliation_models_overview.png
-   :align: center
-   :alt: Open the Reconciliation Model menu from the overview dashboard in Odoo Accounting
-
-.. important::
-   The first entry, named *Invoices Matching Rule*, is the one responsible for the current matching
-   of invoices and bills. Therefore, it is advised to leave it at the top of the list and not to
-   delete it.
-
-Open the model you want to modify, or click on *Create* to create a new one, then fill out the form.
-
-Type
-----
-
-See :ref:`above <reconciliation_models_types>` for an explanation about the different types of
-Reconciliation Models.
-
-.. note::
-   If the *Documents* application is installed on your database, an additional **Activity type**
-   field appears when *To check* is ticked. Selecting the value *Reconciliation request* implies
-   that, whenever you use this model, a *Request Document* window pops up to request a document from
-   a user.
-
-Conditions on Bank Statement Line
----------------------------------
-
-Define here all the conditions that are required for a Reconciliation Model to be applied.
-
-.. important::
-   If a record matches with several Reconciliation Models, the first one in the *sequence* of models
-   will be applied. The sequence is simply the order of the models in the *list view*. They can be
-   rearranged by dragging-and-dropping the handle next to the name.
-
-.. image:: reconciliation_models/reconciliation_models_conditions.png
-   :align: center
-   :alt: Conditions for the Reconciliation Model to be applied in Odoo Accounting
-
-Counterpart Values
-------------------
-
-This section comprises the values that are applied by the Reconciliation Model.
-
-If the value to reconcile needs to be written-off in two separate accounts, click on *Add a second
-line*.
-
-.. image:: reconciliation_models/reconciliation_models_counterparts.png
-   :align: center
-   :alt: Counterparts values of a Reconciliation Model in Odoo Accounting
+Each model is created based on a :ref:`model type <models/type>` and :guilabel:`bank transaction
+conditions`.
 
 .. seealso::
-
-   - :doc:`reconciliation`
    - :doc:`bank_synchronization`
-   - :doc:`../customer_invoices/cash_discounts`
+   - `Odoo Tutorials: Reconciliation models <https://www.odoo.com/slides/slide/reconciliation-models-1841?fullscreen=1>`_
+
+.. _models/type:
+
+Reconciliation model types
+==========================
+
+The reconciliation models are available by going to :menuselection:`Accounting --> Configuration
+--> Banks: Reconciliation Models`. For each reconciliation model, a :guilabel:`Type` must be set.
+Three types of models exist:
+
+- :guilabel:`Button to generate counterpart entry`: a button is created in the resulting entry
+  section of the bank reconciliation view. If clicked, this button generates a counterpart entry to
+  reconcile with the active transaction based on the rules set in the model. The rules specified in
+  the model determine the counterpart entry's account(s), amount(s), label(s), and analytic
+  distribution;
+- :guilabel:`Rule to suggest counterpart entry`: used for recurring transactions to match the
+  transaction to a new entry based on conditions that must match the information on the transaction;
+- :guilabel:`Rule to match invoices/bills`: used for recurring transactions to match the transaction
+  to existing invoices, bills, or payments based on conditions that must match the information on
+  the transaction.
+
+Default reconciliation models
+=============================
+
+In Odoo, different models are available by default depending on the company's fiscal localization.
+These can be updated if needed. Users can also create their own reconciliation models by clicking
+:guilabel:`New`.
+
+.. important::
+   If a record matches with several reconciliation models, the first one in the *sequence* of models
+   is applied. You can rearrange the order by dragging and dropping the handle next to the name.
+
+   .. image:: reconciliation_models/list-view.png
+      :alt: Rearrange the sequence of models in the list view.
+
+Invoices/Bills perfect match
+----------------------------
+
+This model should be at the top of the *sequence* of models, as it enables Odoo to suggest matching
+existing invoices or bills with a bank transaction based on set conditions.
+
+.. image:: reconciliation_models/invoices-bills-perfect-match.png
+   :alt: Set rules to trigger the reconciliation.
+
+Odoo automatically reconciles the payment when the :guilabel:`Auto-validate` option is selected, and
+the model conditions are perfectly met. In this case, it expects to find on the bank statement's
+line the invoice/payment's reference (as :guilabel:`Label` is selected) and the partner's name
+(as :guilabel:`Partner is set` is selected) to suggest the correct counterpart entry and reconcile
+the payment automatically.
+
+Invoices/Bills partial match if underpaid
+-----------------------------------------
+
+This model suggests a customer invoice or vendor bill that partially matches the payment when the
+amount received is slightly lower than the invoice amount, for example in the case of
+**cash discounts**. The difference is reconciled with the account indicated in the
+:guilabel:`counterpart entries` tab.
+
+The reconciliation model :guilabel:`Type` is :guilabel:`Rule to match invoices/bills`, and the
+:guilabel:`Payment tolerance` should be set.
+
+.. image:: reconciliation_models/partial-match.png
+   :alt: Set rules to trigger the reconciliation.
+
+.. note::
+   The :guilabel:`Payment tolerance` is only applicable to lower payments. It is disregarded when an
+   overpayment is received.
+
+.. seealso::
+   :doc:`../customer_invoices/cash_discounts`
+
+Line with bank fees
+-------------------
+
+This model suggests a counterpart entry according to the rules set in the model. In this case, the
+reconciliation model :guilabel:`Type` is :guilabel:`Rule to suggest counterpart entry`, and the
+:guilabel:`Label` can be used for example, to identify the information referring to the
+:guilabel:`Bank fees` in the label of the transaction.
+
+.. image:: reconciliation_models/bank-fees.png
+   :alt: Set rules to trigger the reconciliation.
+
+.. note::
+   `Regular expressions <https://regexone.com/>`_, often abbreviated as **Regex**, can be used in
+   Odoo in various ways to search, validate, and manipulate data within the system. Regex can be
+   powerful but also complex, so it's essential to use it judiciously and with a good understanding
+   of the patterns you're working with.
+
+   To use regular expressions in your reconciliation models, set the :guilabel:`Transaction Type`
+   to :guilabel:`Match Regex` and add your expression. Odoo automatically retrieves the
+   transactions that match your Regex expression and the conditions specified in your model.
+
+   .. image:: reconciliation_models/regex.png
+      :alt: Using Regex in Odoo
+
+Partner mapping
+===============
+
+Partner mapping allows you to establish rules for automatically matching transactions to the correct
+partner account, saving time and reducing the risk of errors that can occur during manual
+reconciliation. For example, you can create a partner mapping rule for incoming payments with
+specific reference numbers or keywords in the transaction description. When an incoming payment
+meets these criteria, Odoo automatically maps it to the corresponding customer's account.
+
+To create a partner mapping rule, go to the :guilabel:`Partner Mapping` tab and enter the
+:guilabel:`Find Text in Label`, :guilabel:`Find Text in Notes`, and :guilabel:`Partner`.
+
+.. image:: reconciliation_models/partner-mapping.png
+   :alt: defining partner mapping

content/applications/finance/accounting/get_started.rst

@@ -187,7 +187,8 @@ Send yourself a sample invoice by email to make sure everything is correctly con
    * :doc:`get_started/chart_of_accounts`
    * :doc:`bank/bank_synchronization`
    * :doc:`../fiscal_localizations`
-   * `Odoo Tutorials: Accounting Basics <https://www.odoo.com/r/lsZ>`_
+   * `Odoo Tutorials: Accounting and Invoicing - Getting started [video]
+     <https://www.odoo.com/slides/slide/getting-started-1692>`_
 
 .. toctree::
    :titlesonly:

content/applications/finance/accounting/get_started/avg_price_valuation.rst

@@ -1,167 +1,439 @@
-=================================
-Inventory average price valuation
-=================================
+===============================
+Average price on returned goods
+===============================
 
-As stated in the :doc:`inventory valuation page
-</applications/inventory_and_mrp/inventory/management/reporting/inventory_valuation_config>`,
-one of the possible costing method you can use in perpetual stock
-valuation, is the average cost.
+.. |AVCO| replace:: :abbr:`AVCO (Average Cost Valuation)`
+.. _inventory/avg_cost/definition:
 
-This document answers to one recurrent question for companies using that
-method to make their stock valuation: how does a shipping returned to
-its supplier impact the average cost and the accounting entries? This
-document is **only** for the specific use case of a perpetual valuation (as
-opposed to the periodic one) and in average price costing method (as
-opposed to standard of FIFO).
+*Average cost valuation* (AVCO) is an inventory valuation method that evaluates cost based on the
+total cost of goods bought or produced during a period, divided by the total number of items
+on-hand. Inventory valuation is used to:
 
-Definition of average cost
-==========================
+- reflect the value of a company's assets;
+- keep track of the amount of unsold goods;
+- account for monetary value in goods that have yet to generate profit;
+- report on flow of goods throughout the quarter.
 
-The average cost method calculates the cost of ending inventory and cost
-of goods sold on the basis of weighted average cost per unit of
-inventory.
+Because |AVCO| uses the weighted average to evaluate the cost, it is a good fit for companies that
+sell only a few different products in large quantities. In Odoo, this costing analysis is
+*automatically updated* each time products are received.
 
-The weighted average cost per unit is calculated using the following
-formula:
+Thus, when shipments are returned to their supplier, Odoo automatically generates accounting entries
+to reflect the change in inventory valuation. However, Odoo does **not** automatically update the
+|AVCO| calculation, because :ref:`this can potentially create inconsistencies with inventory
+valuation <inventory/avg_price/leaving_inventory>`.
 
-- When new products arrive in a warehouse, the new average cost is
-  recomputed as:
+.. note::
+   This document addresses a specific use case for theoretical purposes. Navigate :ref:`here
+   <inventory/management/inventory_valuation_config>` for instructions on how to set up and use
+   |AVCO| in Odoo.
 
-.. image:: avg_price_valuation/avg01.png
+.. seealso::
+   - :ref:`Using inventory valuation <inventory/reporting/using_inventory_val>`
+   - :ref:`Other inventory valuation methods <inventory/inventory_valuation_config/costing_methods>`
+
+Configuration
+=============
+
+To use average cost inventory valuation on a product, navigate to :menuselection:`Inventory -->
+Configuration --> Product Categories` and select the category that will be using |AVCO|. On the
+product category page, set :guilabel:`Costing Method` to `Average Cost (AVCO)` and
+:guilabel:`Inventory Valuation` to `Automated`.
+
+.. seealso::
+   :ref:`Inventory valuation configuration <inventory/management/inventory_valuation_config>`
+
+Using average cost valuation
+============================
+
+The average cost method adjusts the inventory valuation when products are received in the warehouse.
+This section explains how it works, but if the explanation is unnecessary, skip to the :ref:`return
+to supplier use case <inventory/avg_cost/return>` section.
+
+.. _inventory/avg_cost/formula:
+
+Formula
+-------
+
+When new products arrive, the new average cost for each product is recomputed using the formula:
+
+.. math::
+   Avg~Cost = \frac{(Old~Qty \times Old~Avg~Cost) + (Incoming~Qty \times Purchase~Price)}{Final~Qty}
+
+- **Old Qty**: product count in stock before receiving the new shipment;
+- **Old Avg Cost**: calculated average cost for a single product from the previous inventory
+  valuation;
+- **Incoming Qty**: count of products arriving in the new shipment;
+- **Purchase Price**: estimated price of products at the reception of products (since vendor bills
+  may arrive later). The amount includes not only the price for the products, but also added costs,
+  such as shipping, taxes, and :ref:`landed costs <inventory/reporting/landed_costs>`. At reception
+  of the vendor bill, this price is adjusted;
+- **Final Qty**: quantity of on-hand stock after the stock move.
+
+.. _inventory/avg_cost/definite_rule:
+
+.. important::
+   When products leave the warehouse, the average cost **does not** change. Read about why the
+   average cost valuation is **not** adjusted :ref:`here <inventory/avg_price/leaving_inventory>`.
+
+.. _inventory/avg_cost/math_table:
+
+Compute average cost
+--------------------
+
+To understand how the average cost of a product changes with each shipment, consider the following
+table of warehouse operations and stock moves. Each is a different example of how the average cost
+valuation is affected.
+
++--------------------------------+---------------+-------------------+---------------+------------+
+| Operation                      | Incoming Value| Inventory Value   | Qty On Hand   | Avg Cost   |
++================================+===============+===================+===============+============+
+|                                |               | $0                | 0             | $0         |
++--------------------------------+---------------+-------------------+---------------+------------+
+| Receive 8 tables at $10/unit   | 8 * $10       | $80               | 8             | $10        |
++--------------------------------+---------------+-------------------+---------------+------------+
+| Receive 4 tables at $16/unit   | 4 * $16       | $144              | 12            | $12        |
++--------------------------------+---------------+-------------------+---------------+------------+
+| Deliver 10 tables              | -10 * $12     | $24               | 2             | $12        |
++--------------------------------+---------------+-------------------+---------------+------------+
+
+.. _inventory/avg_cost/ex-1:
+
+.. exercise::
+   Ensure comprehension of the above computations by reviewing the "Receive 8 tables at $10/unit"
+   example.
+
+   Initially, the product stock is 0, so all values are $0.
+
+   In the first warehouse operation, `8` tables are received at `$10` each. The average cost is
+   calculated using the :ref:`formula <inventory/avg_cost/formula>`:
+
+   .. math::
+      Avg~Cost = \frac{0 + 8 \times $10}{8} = \frac{$80}{8} = $10
+
+   - Since the *incoming quantity* of tables is `8` and the *purchase price* for each is `$10`,
+   - The inventory value in the numerator is evaluated to `$80`;
+   - `$80` is divided by the total amount of tables to store, `8`;
+   - `$10` is the average cost of a single table from the first shipment.
+
+   To verify this in Odoo, in the *Purchase* app, order `8` quantities of a new product, `Table`,
+   with no previous stock moves, for `$10` each.
+
+   In the table's :guilabel:`Product Category` field in the :guilabel:`General Information` tab of
+   the product form, click the :guilabel:`➡️ (arrow)` icon, to open an :guilabel:`External Link` to
+   edit the product category. Set the :guilabel:`Costing Method` to `Average Cost (AVCO)` and
+   :guilabel:`Inventory Valuation` to `Automated`.
+
+   Then, return to the purchase order. Click :guilabel:`Confirm Order`, and click :guilabel:`Receive
+   Products` to confirm receipt.
+
+   Next, check the inventory valuation record generated by the product reception by navigating to
+   :menuselection:`Inventory --> Reporting --> Inventory Valuation`. Select the drop-down for
+   `Table`, and view the :guilabel:`Total Value` column for the *valuation layer* (:dfn:`inventory
+   valuation at a specific point in time = on-hand quantity * unit price`). The 8 tables in-stock
+   are worth $80.
+
+   .. image:: avg_price_valuation/inventory-val-8-tables.png
+      :align: center
+      :alt: Show inventory valuation of 8 tables in Odoo.
+
+.. tip::
+   When the product category's :guilabel:`Costing Method` is set to :guilabel:`AVCO`, then the
+   average cost of a product is also displayed on the :guilabel:`Cost` field, under the
+   :guilabel:`General Information` tab, on the product page itself.
+
+Product delivery (use case)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+For outgoing shipments, :ref:`outbound products have no effect on the average cost valuation
+<inventory/avg_cost/definite_rule>`. Although the average cost valuation is not recalculated, the
+inventory value still decreases because the product is removed from stock and delivered to the
+customer location.
+
+.. exercise::
+   To demonstrate that the average cost valuation is not recalculated, examine the "Deliver 10
+   tables" example.
+
+   .. math::
+      Avg~Cost = \frac{12 \times $12 + (-10) \times $12}{12-10} = \frac{24}{2} = $12
+
+   #. Because 10 tables are being sent out to customers, the *incoming quantity* is `-10`. The
+      previous average cost (`$12`) is used in lieu of a vendor's *purchase price*;
+   #. The *incoming inventory value* is `-10 * $12 = -$120`;
+   #. The old *inventory value* (`$144`) is added to the *incoming inventory value* (`-$120`), so
+      `$144 + -$120 = $24`;
+   #. Only `2` tables remain after shipping out `10` tables from `12`. So the current *inventory
+      value* (`$24`) is divided by the on-hand quantity (`2`);
+   #. `$24 / 2 = $12`, which is the same average cost as the previous operation.
+
+   To verify this in Odoo, sell `10` tables in the *Sales* app, validate the delivery, and then
+   review the inventory valuation record by going to in :menuselection:`Inventory --> Reporting -->
+   Inventory Valuation`. In the topmost valuation layer, delivering `10` tables reduces the
+   product's value by `-$120`.
+
+   **Note**: What is not represented in this stock valuation record is the revenue made from this
+   sale, so this decrease is not a loss to the company.
+
+   .. image:: avg_price_valuation/inventory-val-send-10-tables.png
+      :align: center
+      :alt: Show how deliveries decrease inventory valuation.
+
+.. _inventory/avg_cost/return:
+
+Return items to supplier (use case)
+===================================
+
+Because the price paid to suppliers can differ from the price the product is valued at with the
+|AVCO| method, Odoo handles returned items in a specific way.
+
+#. Products are returned to suppliers at the original purchase price, but;
+#. The internal cost valuation remains unchanged.
+
+The above :ref:`example table <inventory/avg_cost/math_table>` is updated as follows:
+
++--------------------------------+---------------+-------------------+---------------+------------+
+| Operation                      | Qty*Avg Cost  | Inventory Value   | Qty On Hand   | Avg Cost   |
++================================+===============+===================+===============+============+
+|                                |               | $24               | 2             | $12        |
++--------------------------------+---------------+-------------------+---------------+------------+
+| Return 1 table bought at $10   | -1 * $12      | $12               | 1             | $12        |
++--------------------------------+---------------+-------------------+---------------+------------+
+
+In other words, returns to vendors are perceived by Odoo as another form of a product exiting the
+warehouse. To Odoo, because the table is valued at $12 per unit, the inventory value is reduced by
+`$12` when the product is returned; the initial purchase price of `$10` is unrelated to the table's
+average cost.
+
+.. example::
+   To return a single table that was purchased for `$10`, navigate to the receipt in the *Inventory*
+   app for the :ref:`8 tables purchased in Exercise 1 <inventory/avg_cost/ex-1>` by going to the
+   :guilabel:`Inventory Overview`, clicking on :guilabel:`Receipts`, and selecting the desired
+   receipt.
+
+   Then, click :guilabel:`Return` on the validated delivery order, and modify the quantity to `1` in
+   the reverse transfer window. This creates an outgoing shipment for the table. Select
+   :guilabel:`Validate` to confirm the outgoing shipment.
+
+   Return to :menuselection:`Inventory --> Reporting --> Inventory Valuation` to see how the
+   outgoing shipment decreases the inventory value by $12.
+
+   .. image:: avg_price_valuation/inventory-valuation-return.png
+      :align: center
+      :alt: Inventory valuation for return.
+
+.. _inventory/avg_price/leaving_inventory:
+
+Eliminate stock valuation errors in outgoing products
+-----------------------------------------------------
+
+Inconsistencies can occur in a company's inventory when the average cost valuation is recalculated
+on outgoing shipments.
+
+To demonstrate this error, the table below displays a scenario in which 1 table is shipped to a
+customer and another is returned to a supplier at the purchased price.
+
++------------------------------------------+---------------+-------------------+---------------+------------+
+| Operation                                | Qty*Price     | Inventory Value   | Qty On Hand   | Avg Cost   |
++==========================================+===============+===================+===============+============+
+|                                          |               | $24               | 2             | $12        |
++------------------------------------------+---------------+-------------------+---------------+------------+
+| Ship 1 product to customer               | -1 \* $12     | $12               | 1             | $12        |
++------------------------------------------+---------------+-------------------+---------------+------------+
+| Return 1 product initially bought at $10 | -1 \* $10     | **$2**            | **0**         | $12        |
++------------------------------------------+---------------+-------------------+---------------+------------+
+
+In the final operation above, the final inventory valuation for the table is `$2` even though there
+are `0` tables left in stock.
+
+.. admonition:: Correct method
+
+   Use the average cost to value the return. This does not mean the company gets $12 back for a $10
+   purchase; the item returned for $10 is valued internally at $12. The inventory value change
+   represents a product worth $12 no longer being accounted for in company assets.
+
+Anglo-Saxon accounting
+======================
+
+In addition to using |AVCO|, companies that use **Anglo-Saxon accounting** also keep a holding
+account that tracks the amount to be paid to vendors. Once a vendor delivers an order, **inventory
+value** increases based on the vendor price of the products that have entered the stock. The holding
+account (called **stock input**) is credited and only reconciled once the vendor bill is received.
+
+.. seealso::
+   - :ref:`Anglo-Saxon vs. Continental <inventory/inventory_valuation_config/accounting>`
+
+The table below reflects journal entries and accounts. The *stock input* account stores the money
+intended to pay vendors when the vendor bill has not yet been received. To balance accounts when
+returning products that have a price difference between the price the product is **valued at** and
+the price it was bought for, a *price difference* account is created.
+
+.. _inventory/avg_price/price-table:
+
++-----------------------------------------+---------------+--------------+-------------------+---------------+------------+
+| Operation                               | Stock Input   | Price Diff   | Inventory Value   | Qty On Hand   | Avg Cost   |
++=========================================+===============+==============+===================+===============+============+
+|                                         |               |              | $0                | 0             | $0         |
++-----------------------------------------+---------------+--------------+-------------------+---------------+------------+
+| Receive 8 tables at $10                 | ($80)         |              | $80               | 8             | $10        |
++-----------------------------------------+---------------+--------------+-------------------+---------------+------------+
+| Receive vendor bill $80                 | $0            |              | $80               | 8             | $10        |
++-----------------------------------------+---------------+--------------+-------------------+---------------+------------+
+| Receive 4 tables at $16                 | ($64)         |              | $144              | 12            | $12        |
++-----------------------------------------+---------------+--------------+-------------------+---------------+------------+
+| Receive vendor bill $64                 | $0            |              | $144              | 12            | $12        |
++-----------------------------------------+---------------+--------------+-------------------+---------------+------------+
+| Deliver 10 tables to customer           | $0            |              | $24               | 2             | $12        |
++-----------------------------------------+---------------+--------------+-------------------+---------------+------------+
+| Return 1 table initially bought at $10  | **$10**       | **$2**       | **$12**           | 1             | $12        |
++-----------------------------------------+---------------+--------------+-------------------+---------------+------------+
+| Receive vendor refund $10               | $0            | $2           | $12               | 1             | $12        |
++-----------------------------------------+---------------+--------------+-------------------+---------------+------------+
+
+Product reception
+-----------------
+
+Summary
+~~~~~~~
+
+At product reception, Odoo ensures companies can pay for goods that were purchased by preemptively
+moving an amount matching the price of received goods into the :doc:`liability account
+</applications/finance/accounting/get_started/cheat_sheet>`, **Stock Input**. Then, once the bill
+has been received, the amount in the holding account is transferred to *Accounts Payable*. Transfers
+into this account means the bill has been paid. **Stock Input** is reconciled once the vendor bill
+is received.
+
+Inventory valuation is a method of calculating how much each in-stock product is worth internally.
+Since there is a difference between the price the product is **valuated at** and the price the
+product was actually **purchased for**, the **Inventory Valuation** account is unrelated to the
+crediting and debiting operations of the **Stock Input** account.
+
+To conceptualize all this, follow the breakdown below.
+
+Accounts balanced at received products
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+In this example, a company starts with zero units of a product, `table`, in stock. Then, 8 tables
+are received from the vendor:
+
+#. The **Stock Input** account stores `$80` of credit owed to the vendor. The amount in this account
+   is unrelated to the inventory value.
+#. `$80` worth of tables came **in** (**debit** the *Inventory Value* account `$80`), and
+#. `$80` must be paid **out** for received goods (**credit** the *Stock Input* account `$80`).
+
+In Odoo
+*******
+
+Odoo generates an accounting journal entry when shipments that use |AVCO| costing method are
+received. Configure a :guilabel:`Price Difference Account` by selecting the :guilabel:`➡️ (arrow)`
+icon next to the :guilabel:`Product Category` field on the product page.
+
+Under :guilabel:`Account Properties`, create a new :guilabel:`Price Difference Account` by typing in
+the name of the account and clicking :guilabel:`Create and Edit`. Then set the account
+:guilabel:`Type` as `Expenses`, and click :guilabel:`Save`.
+
+.. image:: avg_price_valuation/create-price-difference.png
    :align: center
+   :alt: Create price difference account.
 
-- When products leave the warehouse: the average cost **does not** change
+Then, receive the shipment in the *Purchase* app or *Inventory* app, and navigate to the
+:menuselection:`Accounting app --> Accounting --> Journal Entries`. In the list, find the
+:guilabel:`Reference` that matches the warehouse reception operation for the relevant product.
 
-Defining the purchase price
----------------------------
+.. image:: avg_price_valuation/search-for-entry-of-tables.png
+   :align: center
+   :alt: Show accounting entry of 8 tables from the list.
 
-The purchase price is estimated at the reception of the products (you
-might not have received the vendor bill yet) and reevaluated at the
-reception of the vendor bill. The purchase price includes the cost you
-pay for the products, but it may also includes additional costs, like
-landed costs.
+Click on the line for 8 tables. This accounting journal entry shows that when the 8 tables were
+received, the `Stock Valuation` account increased by `$80`. Conversely, the **Stock Input** account
+(set as `Stock Interim (Received)` account by default) is credited `$80`.
 
-Average cost example
-====================
+.. image:: avg_price_valuation/accounting-entry-8-tables.png
+   :align: center
+   :alt: Debit stock valuation and credit stock input 80 dollars.
 
-+-----------------------------+---------------+-------------------+---------------+------------+
-| Operation                   | Delta Value   | Inventory Value   | Qty On Hand   | Avg Cost   |
-+=============================+===============+===================+===============+============+
-|                             |               | $0                | 0             | $0         |
-+-----------------------------+---------------+-------------------+---------------+------------+
-| Receive 8 Products at $10   | +8\*$10       | $80               | 8             | $10        |
-+-----------------------------+---------------+-------------------+---------------+------------+
-| Receive 4 Products at $16   | +4\*$16       | $144              | 12            | $12        |
-+-----------------------------+---------------+-------------------+---------------+------------+
-| Deliver 10 Products         | -10\*$12      | $24               | 2             | $12        |
-+-----------------------------+---------------+-------------------+---------------+------------+
-+-----------------------------+---------------+-------------------+---------------+------------+
+Accounts balanced at received vendor bill
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-At the beginning, the Avg Cost is set to 0 set as there is no product in
-the inventory. When the first reception is made, the average cost
-becomes logically the purchase price.
+In this example, a company starts with zero units of a product, table, in stock. Then, 8 tables are
+received from the vendor. When the bill is received from vendor for 8 tables:
 
-At the second reception, the average cost is updated because the total
-inventory value is now ``$80 + 4*$16 = $144``. As we have 12 units on
-hand, the average price per unit is ``$144 / 12 = $12``.
+#. Use `$80` in the **Stock Input** account to pay the bill. This cancels out and the account now
+   holds `$0`.
+#. Debit **Stock Input** `$80` (to reconcile this account).
+#. Credit **Accounts payable** `$80`. This account stores the amount the company owes others, so
+   accountants use the amount to write checks to vendors.
 
-By definition, the delivery of 10 products does not change the average
-cost. Indeed, the inventory value is now $24 as we have only 2 units
-remaining of each ``$24 / 2 = $12``.
+In Odoo
+*******
 
-Purchase return use case
-========================
+Once the vendor requests payment, navigate to the :menuselection:`Purchase app --> Orders -->
+Purchase` and select the :abbr:`PO (Purchase Order)` for 8 tables. Inside the :abbr:`PO (Purchase
+Order)`, select :guilabel:`Create Bill`.
 
-In case of a product returned to its supplier after reception, the
-inventory value is reduced using the average cost formulae (not at the
-initial price of these products!).
+Switch to the :guilabel:`Journal Items` tab to view how `$80` is transferred from the holding
+account, `Stock Interim (Received)` to `Accounts Payable`. :guilabel:`Confirm` the bill to record
+the payment to the vendor.
 
-Which means that the above table will be updated as follow:
+.. image:: avg_price_valuation/receive-8-table-bill.png
+   :align: center
+   :alt: Show bill linked to the purchase order for 8 tables.
 
-+-----------------------------------------------+---------------+-------------------+---------------+------------+
-| Operation                                     | Delta Value   | Inventory Value   | Qty On Hand   | Avg Cost   |
-+===============================================+===============+===================+===============+============+
-|                                               |               | $24               | 2             | $12        |
-+-----------------------------------------------+---------------+-------------------+---------------+------------+
-| Return of 1 Product initially bought at $10   | -1\*$12       | $12               | 1             | $12        |
-+-----------------------------------------------+---------------+-------------------+---------------+------------+
+On product delivery
+-------------------
 
-Explanation: counter example
-----------------------------
+In the :ref:`above example table <inventory/avg_price/price-table>`, when 10 products are delivered
+to a customer, the **Stock Input** account is untouched because there are no new products coming in.
+To put it simply:
 
-Remember the definition of **Average Cost**, saying that we do not update
-the average cost of a product leaving the inventory. If you break this
-rule, you may lead to inconsistencies in your inventory.
+#. **Inventory valuation** is credited `$120`. Subtracting from inventory valuation represents
+   `$120` worth of products exiting the company.
+#. Debit **Accounts Receivable** to record revenue from the sale.
 
-As an example, here is the scenario when you deliver one piece to the
-customer and return the other one to your supplier (at the cost you
-purchased it). Here is the operation:
+.. image:: avg_price_valuation/sell-10-tables.png
+   :align: center
+   :alt: Show journal items linked to sale order.
 
-+-----------------------------------------------+---------------+-------------------+---------------+------------+
-| Operation                                     | Delta Value   | Inventory Value   | Qty On Hand   | Avg Cost   |
-+===============================================+===============+===================+===============+============+
-|                                               |               | $24               | 2             | $12        |
-+-----------------------------------------------+---------------+-------------------+---------------+------------+
-| Customer Shipping 1 product                   | -1\*$12       | $12               | 1             | $12        |
-+-----------------------------------------------+---------------+-------------------+---------------+------------+
-| Return of 1 Product initially bought at $10   | -1\*$10       | **$2**            | **0**         | $12        |
-+-----------------------------------------------+---------------+-------------------+---------------+------------+
+.. spoiler:: Understand Anglo-Saxon expensing
 
-As you can see in this example, this is not correct: an inventory
-valuation of $2 for 0 pieces in the warehouse.
+   In the accounting journal entry invoicing a customer for 10 tables, the accounts **Product
+   Sales**, **Tax Received**, and **Accounts Receivable** all pertain to the sale of the product.
+   **Accounts Receivable** is the account where the customer payment will be received.
 
-The correct scenario should be to return the goods at the current
-average cost:
+   Anglo-Saxon accounting recognizes the cost of goods sold (COGS) once the sale is made. So, up
+   until the product is sold, scrapped, or returned, costs of keeping the product in stock are not
+   accounted for. The **Expense** account is debited `$120` to log the costs of storing 10 tables
+   during this period of time.
 
-+-----------------------------------------------+---------------+-------------------+---------------+------------+
-| Operation                                     | Delta Value   | Inventory Value   | Qty On Hand   | Avg Cost   |
-+===============================================+===============+===================+===============+============+
-|                                               |               | $24               | 2             | $12        |
-+-----------------------------------------------+---------------+-------------------+---------------+------------+
-| Customer Shipping 1 product                   | -1\*$12       | $12               | 1             | $12        |
-+-----------------------------------------------+---------------+-------------------+---------------+------------+
-| Return of 1 Product initially bought at $10   | -1\*$12       | **$0**            | **0**         | $12        |
-+-----------------------------------------------+---------------+-------------------+---------------+------------+
+On product return
+-----------------
 
-On the other hand, using the average cost to value the return ensure a
-correct inventory value at all times.
+In the :ref:`above example table <inventory/avg_price/price-table>`, when returning 1 product to a
+vendor purchased at `$10`, a company expects `$10` in the **Accounts Payable** account from the
+vendor. However, **Stock Input** account must be debited `$12` because the average cost is `$12` at
+the time of the return. The missing `$2` is accounted for in the :guilabel:`Price Difference
+Account`, which is set up in the product's :guilabel:`Product Category`.
 
-Further thoughts on anglo saxon mode
-------------------------------------
+.. note::
+   Behavior of *price difference accounts* varies from localization. In this case, the account is
+   intended to store differences between vendor price and *automated* inventory valuation methods.
 
-For people in using the **anglo saxon accounting** principles, there is
-another concept to take into account: the stock input account of the
-product, which is intended to hold at any time the value of vendor bills
-to receive. So the stock input account will increase on reception of
-incoming shipments and will decrease when receiving the related vendor
-bills.
+Summary:
 
-Back to our example, we see that when the return is valued at the
-average price, the amount booked in the stock input account is the
-original purchase price:
+#. Debit **Stock Input** account `$10` to move the table from stock to stock input. This move is to
+   indicate that the table is to be processed for an outgoing shipment.
+#. Debit **Stock Input** an additional `$2` to account for the **Price Difference**.
+#. Credit **Stock Valuation** `$12` because the item is leaving the stock.
 
-+-----------------------------------------------+---------------+--------------+-------------------+---------------+------------+
-| Operation                                     | stock input   | price diff   | Inventory Value   | Qty On Hand   | Avg Cost   |
-+===============================================+===============+==============+===================+===============+============+
-|                                               |               |              | $0                | 0             | $0         |
-+-----------------------------------------------+---------------+--------------+-------------------+---------------+------------+
-| Receive 8 Products at $10                     | ($80)         |              | $80               | 8             | $10        |
-+-----------------------------------------------+---------------+--------------+-------------------+---------------+------------+
-| Receive vendor bill $80                       | $0            |              | $80               | 8             | $10        |
-+-----------------------------------------------+---------------+--------------+-------------------+---------------+------------+
-| Receive 4 Products at $16                     | ($64)         |              | $144              | 12            | $12        |
-+-----------------------------------------------+---------------+--------------+-------------------+---------------+------------+
-| Receive vendor bill $64                       | $0            |              | $144              | 12            | $12        |
-+-----------------------------------------------+---------------+--------------+-------------------+---------------+------------+
-| Deliver 10 Products                           | $0            |              | $24               | 2             | $12        |
-+-----------------------------------------------+---------------+--------------+-------------------+---------------+------------+
-| Return of 1 Product initially bought at $10   | **$10**       | **$2**       | **$12**           | 1             | $12        |
-+-----------------------------------------------+---------------+--------------+-------------------+---------------+------------+
-| Receive vendor refund $10                     | $0            | $2           | $12               | 1             | $12        |
-+-----------------------------------------------+---------------+--------------+-------------------+---------------+------------+
+.. image:: avg_price_valuation/expensing-price-difference-account.png
+   :align: center
+   :alt: 2 dollar difference expensed in Price Difference account.
 
-This is because the vendor refund will be made using the original
-purchase price, so to zero out the effect of the return in the stock
-input in last operation, we need to reuse the original price. The price
-difference account located on the product category is used to book the
-difference between the average cost and the original purchase price.
+Once the vendor's refund is received,
+
+#. Credit **Stock Input** account `$10` to reconcile the price of the table.
+#. Debit **Accounts Payable** `$10` to have the accountants collect and register the payment in
+   their journal.
+
+.. image:: avg_price_valuation/return-credit-note.png
+   :align: center
+   :alt: Return to get 10 dollars back.

content/applications/finance/accounting/get_started/chart_of_accounts.rst

@@ -3,48 +3,37 @@ Chart of accounts
 =================
 
 The **chart of accounts (COA)** is the list of all the accounts used to record financial
-transactions in the general ledger of an organization.
+transactions in the general ledger of an organization. The chart of accounts can be found under
+:menuselection:`Accounting-->Configuration-->Chart of Accounts`.
 
-The accounts are usually listed in the order of appearance in the financial reports. Most of the
-time, they are listed as follows :
+When browsing your chart of accounts, you can sort the accounts by :guilabel:`Code`,
+:guilabel:`Account Name`, or :guilabel:`Type`, but other options are available in the drop-down menu
+:guilabel:`(⋮)`.
 
-- Balance Sheet accounts:
-
-  - Assets
-  - Liabilities
-  - Equity
-
-- Profit & Loss:
-
-  - Income
-  - Expense
-
-When browsing your chart of accounts, you can filter the accounts by number, in the left column, and
-also group them by :guilabel:`Account Type`.
-
-.. image:: chart_of_accounts/chart-of-accounts.png
-   :align: center
+.. image:: chart_of_accounts/chart-of-accounts-sort.png
    :alt: Group the accounts by type in Odoo Accounting
 
 Configuration of an account
 ===========================
 
-The country you select at the creation of your database (or additional company on your database)
-determines which **fiscal localization package** is installed by default. This package includes a
-standard chart of accounts already configured according to the country's regulations. You can use
-it directly or set it according to your company's needs.
+The country you select during the creation of your database (or additional company in your database)
+determines which :doc:`fiscal localization package <../../fiscal_localizations>` is installed by
+default. This package includes a standard chart of accounts already configured according to the
+country's regulations. You can use it directly or set it according to your company's needs.
+
+To create a new account, go to :menuselection:`Accounting-->Configuration-->Chart of Accounts`,
+click :guilabel:`Create`, and fill in (at the minimum) the required fields
+(:guilabel:`Code, Account Name, Type`).
 
 .. warning::
    It is not possible to modify the **fiscal localization** of a company once a journal entry has
    been posted.
 
-To create a new account, go to :menuselection:`Accounting --> Configuration --> Chart of Accounts`,
-click on :guilabel:`Create`, and fill out the form.
-
 Code and name
 -------------
 
-Each account is identified by its **code** and **name**, which also indicates the account's purpose.
+Each account is identified by its :guilabel:`Code` and :guilabel:`Name`, which also indicate the
+account's purpose.
 
 .. _chart-of-account/type:
 
@@ -59,7 +48,7 @@ Correctly configuring the **account type** is critical as it serves multiple pur
 - Generate opening entries
 
 To configure an account type, open the :guilabel:`Type` field's drop-down selector and select the
-right type among the following list:
+corresponding type from the following list:
 
 +---------------+--------------+-------------------------+
 | Report        | Category     | Account Types           |
@@ -104,29 +93,31 @@ right type among the following list:
 Assets, deferred expenses, and deferred revenues automation
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Some **account types** display a new field **to automate** the creation of :ref:`assets
-<assets-automation>` entries, :ref:`deferred expenses <deferred-expenses-automation>` entries,
-and :ref:`deferred revenues <deferred-revenues-automation>` entries.
+Some **account types** can **automate** the creation of :ref:`assets <assets-automation>` entries,
+:ref:`deferred expenses <deferred-expenses-automation>` entries, and
+:ref:`deferred revenues <deferred-revenues-automation>` entries. To **automate** entries, click
+:guilabel:`Setup` on an account line and go to the :guilabel:`Automation` tab.
 
-You have three choices for the :guilabel:`Automation` field:
+You have three choices for the :guilabel:`Automation` tab:
 
 #. :guilabel:`No`: this is the default value. Nothing happens.
 #. :guilabel:`Create in draft`: whenever a transaction is posted on the account, a draft entry is
-   created, but not validated. You must first fill out the corresponding form.
-#. :guilabel:`Create and validate`: you must also select a **model**. Whenever a transaction is
-   posted on the account, an entry is created and immediately validated.
+   created but not validated. You must first fill out the corresponding form.
+#. :guilabel:`Create and validate`: you must also select a :guilabel:`Deferred Expense Model`.
+   Whenever a transaction is posted on the account, an entry is created and immediately validated.
 
 Default taxes
 -------------
 
-Select a **default tax** that will be applied when this account is chosen for a product sale or
-purchase.
+In the :guilabel:`Setup` menu of an account, select a **default tax** to be applied when this
+account is chosen for a product sale or purchase.
 
 Tags
 ----
 
-Some accounting reports require **tags** to be set on the relevant accounts. By default, you can
-choose among the tags that are used by the *Cash Flow Statement*.
+Some accounting reports require **tags** to be set on the relevant accounts. To add a tag, under
+:guilabel:`Setup`, click the :guilabel:`Tags` field and select an existing tag or :guilabel:`Create`
+a new one.
 
 Account groups
 --------------
@@ -134,31 +125,29 @@ Account groups
 **Account groups** are useful to list multiple accounts as *sub-accounts* of a bigger account and
 thus consolidate reports such as the **Trial Balance**. By default, groups are handled automatically
 based on the code of the group. For example, a new account `131200` is going to be part of the group
-`131000`.
+`131000`. You can attribute a specific group to an account in the :guilabel:`Group` field under
+:guilabel:`Setup`.
 
 Create account groups manually
-------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 .. note::
    Regular users should not need to create account groups manually. The following section is only
    intended for rare and advanced use cases.
 
-To create a new account group, :ref:`developer mode <developer-mode>` and head to
-:menuselection:`Accounting app --> Configuration --> Account Groups`. Here, create a new group and
-enter the :guilabel:`name, code prefix, and company` to which that group account should be
-available. Note that you must enter the same code prefix in both :guilabel:`From` and :guilabel:`to`
-fields.
+To create a new account group, activate :ref:`developer mode <developer-mode>` and head to
+:menuselection:`Accounting app-->Configuration-->Account Groups`. Here, create a new group and enter
+the :guilabel:`name, code prefix, and company` to which that group account should be available. Note
+that you must enter the same code prefix in both :guilabel:`From` and :guilabel:`to` fields.
 
 .. image:: chart_of_accounts/account-groups.png
-   :align: center
    :alt: Account groups creation.
 
-To display your **Trial Balance** report with your account groups, go to :menuselection:`Accounting
-app-->Reporting-->Trial Balance`, then open the :guilabel:`Options` menu and select
-:guilabel:`Hierarchy and Subtotals`.
+To display your **Trial Balance** report with your account groups, go to
+:menuselection:`Accounting-->Reporting-->Trial Balance`, then open the :guilabel:`Options` menu and
+select :guilabel:`Hierarchy and Subtotals`.
 
-.. image:: chart_of_accounts/trial-balance.png
-   :align: center
+.. image:: chart_of_accounts/chart-of-accounts-groups.png
    :alt: Account Groups in the Trial Balance in Odoo Accounting
 
 Allow reconciliation
@@ -171,15 +160,18 @@ For example, an invoice paid with a credit card can be marked as :guilabel:`paid
 its payment. Therefore, the account used to record credit card payments needs to be configured as
 **allowing reconciliation**.
 
-To do so, check the :guilabel:`Allow Reconciliation` box in the account's settings, and save.
+To do so, check the :guilabel:`Allow Reconciliation` box in the account's settings, and
+:guilabel:`Save`; or enable the button from the chart of accounts view.
+
+.. image:: chart_of_accounts/chart-of-accounts-reconciliation.png
+   :alt: Allow reconciliation for accounts in Odoo Accounting
 
 Deprecated
 ----------
 
 It is not possible to delete an account once a transaction has been recorded on it. You can make
-them unusable by using the **Deprecated** feature.
-
-To do so, check the :guilabel:`Deprecated` box in the account's settings, and save.
+them unusable by using the **Deprecated** feature: check the :guilabel:`Deprecated` box in the
+account's settings, and :guilabel:`Save`.
 
 .. seealso::
    * :doc:`cheat_sheet`

content/applications/finance/accounting/get_started/cheat_sheet.rst

@@ -129,6 +129,8 @@ Example
 
       .. placeholder
 
+.. _cheat_sheet/journals:
+
 Journal entries
 ===============
 

content/applications/finance/accounting/payments.rst

@@ -4,15 +4,15 @@
 Payments
 ========
 
-In Odoo, payments can either be linked automatically to an invoice or bill or be stand-alone records
-for use at a later date.
+In Odoo, payments can either be automatically linked to an invoice or bill or be stand-alone records
+for use at a later date:
 
-If a payment is **linked to an invoice or bill**, it reduces the amount due of the invoice. You can
-have multiple payments related to the same invoice.
+- If a payment is **linked to an invoice or bill**, it reduces/settles the amount due of the
+  invoice. You can have multiple payments related to the same invoice.
 
-If a payment is **not linked to an invoice or bill**, the customer has an outstanding credit with
-your company, or your company has an outstanding debit with a vendor. You can use those outstanding
-amounts to reduce unpaid invoices/bills.
+- If a payment is **not linked to an invoice or bill**, the customer has an outstanding credit with
+  your company, or your company has an outstanding debit with a vendor. You can use those
+  outstanding amounts to reduce/settle unpaid invoices/bills.
 
 .. seealso::
    - :doc:`Internal transfers <payments/internal_transfers>`
@@ -23,69 +23,66 @@ amounts to reduce unpaid invoices/bills.
 Registering payment from an invoice or bill
 ===========================================
 
-When clicking on :guilabel:`Register payment` in a customer invoice or vendor bill, it generates a
-new journal entry and changes the amount due according to the amount of the payment. The counterpart
-is reflected in an outstanding receipts or payments account. At this point, the customer invoice or
-vendor bill is marked as :guilabel:`In payment`. Then, when the outstanding account is reconciled
-with a bank statement line, the invoice or vendor bill changes to the :guilabel:`Paid` status.
+When clicking :guilabel:`Register payment` in a customer invoice or vendor bill, it generates a new
+journal entry and changes the amount due according to the payment amount. The counterpart is
+reflected in an :ref:`outstanding <bank/outstanding-accounts>` **receipts** or **payments** account.
+At this point, the customer invoice or vendor bill is marked as :guilabel:`In payment`. Then, when
+the outstanding account is reconciled with a bank statement line, the invoice or vendor bill changes
+to the :guilabel:`Paid` status.
 
 The information icon near the payment line displays more information about the payment. You can
-access additional information, such as the related journal, by clicking on :guilabel:`View`.
+access additional information, such as the related journal, by clicking :guilabel:`View`.
 
 .. image:: payments/information-icon.png
-   :alt: See detailed information of a payment
+   :alt: See detailed information of a payment.
 
 .. note::
-   - The customer invoice or vendor bill should be in the status :guilabel:`Posted` to register the
+   - The customer invoice or vendor bill must be in the :guilabel:`Posted` status to register the
      payment.
-   - When clicking on :guilabel:`Register payment`, you can select the amount to pay and make a
-     partial or full payment.
-   - If your main bank account is set as :ref:`outstanding account
-     <bank/outstanding-accounts>`, and the payment is made in Odoo (not related to a
-     bank statement), invoices and bills are directly registered in the status :guilabel:`Paid`.
-   - If you unreconciled a payment, it still appears in your books but is no longer linked to the
+   - If you unreconcile a payment, it still appears in your books but is no longer linked to the
      invoice.
    - If you (un)reconcile a payment in a different currency, a journal entry is automatically
      created to post the currency exchange gains/losses (reversal) amount.
    - If you (un)reconcile a payment and an invoice having cash basis taxes, a journal entry is
      automatically created to post the cash basis tax (reversal) amount.
 
-.. seealso::
-   - :doc:`bank/reconciliation`
+.. tip::
+   - If your main bank account is set as an :ref:`outstanding account
+     <bank/outstanding-accounts>`, and the payment is registered in Odoo (not through a related
+     bank statement), invoices and bills are directly registered as :guilabel:`Paid`.
 
 Registering payments not tied to an invoice or bill
 ===================================================
 
-When a new payment is registered via the menu :menuselection:`Customers / Vendors --> Payments`, it
-is not directly linked to an invoice or bill. Instead, the account receivable or the account payable
-are matched with the outstanding account until they are manually matched with their related invoice
-or bill.
+When a new payment is registered via :menuselection:`Customers / Vendors --> Payments` menu, it is
+not directly linked to an invoice or bill. Instead, the account receivable or the account payable is
+matched with the **outstanding account** until it is manually matched with its related invoice or
+bill.
 
 Matching invoices and bills with payments
 -----------------------------------------
 
-A blue banner appears when you validate a new invoice or bill and there is an outstanding payment
-for this specific customer or vendor. It can easily be matched from the invoice or the bill by
-clicking on :guilabel:`ADD` under :guilabel:`Outstanding Credits` or :guilabel:`Outstanding Debits`.
+A blue banner appears when you validate a new invoice/bill and an **outstanding payment** exists for
+this specific customer or vendor. It can easily be matched from the invoice or bill by clicking
+:guilabel:`ADD` under :guilabel:`Outstanding Credits` or :guilabel:`Outstanding Debits`.
 
 .. image:: payments/add-option.png
-   :alt: Shows the ADD option to reconcile an invoice or a bill with a payment
+   :alt: Shows the ADD option to reconcile an invoice or a bill with a payment.
 
-The invoice or bill is now marked as :guilabel:`In payment` until it is reconciled with the bank
-statement.
+The invoice or bill is now marked as :guilabel:`In payment` until it is reconciled with its
+corresponding bank statement.
 
-.. seealso::
-   - :doc:`bank/reconciliation`
+.. _payments/batch-payments:
 
 Batch payment
 -------------
 
 Batch payments allow you to group different payments to ease :doc:`reconciliation
-<bank/reconciliation>`. They are also useful when you deposit checks to the bank or
-for SEPA Payments. To do so, go to :menuselection:`Accounting --> Customers --> Batch Payments` or
-:menuselection:`Accounting --> Vendors --> Batch Payments`. In the list view of payments, you can
-select several payments and group them in a batch by clicking on :menuselection:`Action --> Create
-Batch Payment`.
+<bank/reconciliation>`. They are also useful when you deposit :doc:`checks <payments/checks>` to the
+bank or for :doc:`SEPA payments <payments/pay_sepa>`. To do so, go to :menuselection:`Accounting -->
+Customers --> Batch Payments` or :menuselection:`Accounting --> Vendors --> Batch Payments`. In the
+list view of payments, you can select and group several payments in a batch by clicking
+:menuselection:`Action --> Create Batch Payment`.
 
 .. seealso::
   - :doc:`payments/batch`
@@ -97,36 +94,50 @@ Payments matching
 -----------------
 
 The :guilabel:`Payments matching` tool opens all unreconciled customer invoices or vendor bills and
-gives you the opportunity to process them all one by one, doing the matching of all their payments
-and invoices at once. You can reach this tool from the :menuselection:`Accounting Dashboard -->
-Customer Invoices / Vendor Bills`, and click on :guilabel:`⋮` and select :guilabel:`Payments
-Matching`, or by going to :menuselection:`Accounting --> Reconciliation`.
+allows you to process them individually, matching all payments and invoices in one place. You can
+reach this tool from the :menuselection:`Accounting Dashboard --> Customer Invoices / Vendor Bills`,
+click the drop-down menu button (:guilabel:`⋮`), and select :guilabel:`Payments Matching`, or go to
+:menuselection:`Accounting --> Accounting --> Reconciliation`.
+
+.. image:: payments/payments-journal.png
+   :alt: Payments matching menu in the drop-down menu.
 
 .. note::
-   During the :doc:`reconciliation <bank/reconciliation>`, if the sum of the debits
-   and credits does not match, there is a remaining balance. This either needs to be reconciled at a
-   later date or needs to be written off directly.
+   During the :doc:`reconciliation <bank/reconciliation>`, if the sum of the debits and credits does
+   not match, there is a remaining balance. This either needs to be reconciled at a later date or
+   needs to be written off directly.
 
 Batch payments matching
 -----------------------
 
-To reconcile several outstanding payments or invoices at once, for a specific customer or vendor,
-the batch reconciliation feature can be used. Go to :menuselection:`Accounting --> Reporting -->
-Aged Receivable / Aged Payable`. You now see all transactions that have not been reconciled yet, and
-when you select a customer or vendor, the :guilabel:`Reconcile` option is displayed.
+You can use the batch reconciliation feature to reconcile several outstanding payments or invoices
+simultaneously for a specific customer or vendor. Go to :menuselection:`Accounting --> Reporting -->
+Aged Receivable / Aged Payable`. You can see all transactions that have not been reconciled yet for
+that partner, and when you select a customer or vendor, the :guilabel:`Reconcile` option is
+displayed.
 
 .. image:: payments/reconcile-option.png
-   :alt: See the reconcile option
+   :alt: See the reconcile option.
+
+Registering a partial payment
+=============================
+
+To register a **partial payment**, click :guilabel:`Register payment` from the related invoice or
+bill, and enter the amount received or paid. Upon entering the amount, a prompt appears to decide
+whether to :guilabel:`Keep open` the invoice or bill, or :guilabel:`Mark as fully paid`. Select
+:guilabel:`Keep open` and click :guilabel:`Create payment`. The invoice or bill is now marked as
+:guilabel:`Partial`. Select :guilabel:`Mark as fully paid` if you wish to settle the invoice or bill
+with a difference in the amount.
+
+.. image:: payments/payment-difference.png
+   :alt: Partial payment of an invoice or bill.
 
 Reconciling payments with bank statements
 =========================================
 
 Once a payment has been registered, the status of the invoice or bill is :guilabel:`In payment`. The
-next step is to reconcile it with the related bank statement line to have the transaction finalized
-and the invoice or bill marked as :guilabel:`Paid`.
-
-.. seealso::
-   - :doc:`bank/reconciliation`
+next step is :doc:`reconciling <bank/reconciliation>` it with the related bank statement line to
+have the transaction finalized and the invoice or bill marked as :guilabel:`Paid`.
 
 .. toctree::
    :titlesonly:
@@ -139,6 +150,5 @@ and the invoice or bill marked as :guilabel:`Paid`.
    payments/internal_transfers
    payments/pay_sepa
    payments/pay_checks
-   payments/multiple
    payments/forecast
    payments/trusted_accounts

content/applications/finance/accounting/payments/follow_up.rst

@@ -79,7 +79,7 @@ To know whether a customer usually pays late or not, you can set a trust level b
 :guilabel:`Good Debtor`, :guilabel:`Normal Debtor`, or :guilabel:`Bad Debtor` on their follow-up
 report. To do so, click on the bullet next to the customer's name and select a trust level.
 
-.. image:: follow_up/debtors-trust-level.png
+.. image:: follow_up/debtor-level.png
     :alt: Set debtor's trust level
 
 Send reminders in batches