msgid "This documentation serves as a guide for first-timer and veteran contributors. As an open-core project, Odoo accepts contributions from everyone, Odoo employees and members of the Odoo community alike. The Odoo community comprises users, developers, and other interested parties who contribute their time and expertise."
msgstr ""
#: ../../content/contributing.rst:15
msgid "Depending on your skill set and interest, there are many ways to contribute to Odoo. The table below lists the most important of them."
msgstr ""
#: ../../content/contributing.rst:23
msgid "Contribution"
msgstr ""
#: ../../content/contributing.rst:24
msgid "Description"
msgstr ""
#: ../../content/contributing.rst:25
msgid "Resources"
msgstr ""
#: ../../content/contributing.rst:26
msgid "Target Audience"
msgstr ""
#: ../../content/contributing.rst:27
msgid "Join the community"
msgstr ""
#: ../../content/contributing.rst:28
msgid "Participate in discussions on the forums, help answer questions, and assist other members of the Odoo community."
msgid "Help improve the stability of Odoo by reporting the bugs that you discover in :doc:`supported versions </administration/supported_versions>` directly to Odoo support. Make sure to include as many details (version, environment, test scenario...) as possible. If you don't have the Odoo Enterprise license required for contacting the support, open a new issue on the GitHub repository of Odoo."
msgid "`Odoo support <https://www.odoo.com/help>`_"
msgstr ""
#: ../../content/contributing.rst:39
msgid "`Issue tracker on GitHub <https://github.com/odoo/odoo/issues>`_"
msgstr ""
#: ../../content/contributing.rst:40
msgid "Users of Odoo"
msgstr ""
#: ../../content/contributing.rst:41
msgid "Translate Odoo"
msgstr ""
#: ../../content/contributing.rst:42
msgid "Translate the user interface and documentation of Odoo into different languages."
msgstr ""
#: ../../content/contributing.rst:43
msgid "`Odoo project on Transifex <https://explore.transifex.com/odoo/>`_"
msgstr ""
#: ../../content/contributing.rst:44
msgid "Anyone fluent in multiple languages"
msgstr ""
#: ../../content/contributing.rst:45
msgid "Contribute to the codebase"
msgstr ""
#: ../../content/contributing.rst:46
msgid "Submit pull requests to the Odoo GitHub repositories to fix bugs, add new features, or improve the performance and reliability of the product. You can also review and comment on pull requests from other contributors. By contributing to the codebase, you can make a direct and lasting impact on the quality and features of Odoo."
msgstr ""
#: ../../content/contributing.rst:50
msgid ":doc:`Guide: Contributing to the codebase <contributing/development>`"
msgid "Submit corrections and improvements to the Documentation. The product evolves fast, and it can be challenging to consistently reflect these changes in the documentation. By updating the documentation, you can help many users find their way in Odoo."
msgid "Develop new modules to extend the functionality of Odoo. Custom modules can be made available for free or paid on the Odoo App Store or on any other Odoo modules library. By creating custom modules and making them available to others, you can help grow the Odoo ecosystem and provide additional value to users of the platform."
msgid "It is mainly Odoo employees who develop new features for the codebase and write new content for the documentation. Be sure to discuss any idea for a new feature or page with the Odoo team so they can give you the green light before you begin working on it. Some features may already be in development on their side, and only approved features can be merged."
msgid "First, you need to `create a GitHub account <https://github.com/join>`_. Odoo uses GitHub to manage the source code of its products, and this is where you will make your changes and submit them for review."
msgstr ""
#: ../../content/contributing/development.rst:5
msgid "Development"
msgstr ""
#: ../../content/contributing/development.rst:13
msgid "If you are reading this, chances are that you are interested in learning how to contribute to the codebase of Odoo. Whether that's the case or you landed here by accident, we've got you covered!"
msgid ":doc:`Discover other ways to contribute to Odoo <../contributing>`"
msgstr ""
#: ../../content/contributing/development.rst:19
msgid "When you feel ready, jump to the :ref:`contributing/development/setup` section to begin your journey in contributing to the development of Odoo."
msgid "The instructions below help you prepare your environment for making local changes to the codebase and then push them to GitHub. Skip this section and go to :ref:`contributing/development/first-contribution` if you have already completed this step."
msgstr ""
#: ../../content/contributing/development.rst:33
msgid "Go to `github.com/odoo/odoo <https://github.com/odoo/odoo>`_ and click on the :guilabel:`Fork` button in the top right corner to create a fork (:dfn:`your own copy`) of the repository on your account. Do the same with `github.com/odoo/enterprise <https://github.com/odoo/enterprise>`_ if you have access to it. This creates a copy of the codebase to which you can make changes without affecting the main codebase. Skip this step if you work at Odoo."
msgid "`Install Git <https://git-scm.com/book/en/v2/Getting-Started-Installing-Git>`_. It is a command-line (:dfn:`a text interface`) tool that allows tracking the history of changes made to a file and, more importantly, working on different versions of that file simultaneously. It means you do not need to worry about overwriting someone else’s pending work when making changes."
msgid "Follow the `guide to update the PATH variable on Linux and macOS <https://unix.stackexchange.com/a/26059>`_ with the installation path of Git (by default :file:`/usr/bin/git`)."
msgid "Follow the `guide to update the PATH variable on Windows <https://www.howtogeek.com/118594/how-to-edit-your-system-path-for-easy-command-line-access/>`_ with the installation path of Git (by default :file:`C:\\\\Program Files\\\\Git`)."
msgid "Configure Git to push changes to your fork(s) rather than to the main codebase. If you work at Odoo, configure Git to push changes to the shared forks created on the account **odoo-dev**."
msgstr ""
#: ../../content/contributing/development.rst:47
msgid "Link Git with your fork(s)"
msgstr ""
#: ../../content/contributing/development.rst:49
msgid "In the command below, replace `<your_github_account>` with the name of the GitHub account on which you created the fork(s)."
msgid "Odoo development can be challenging for beginners. We recommend you to be knowledgeable enough to code a small module before contributing. If that is not the case, take some time to go through the :doc:`developer tutorials </developer/howtos>` to fill in the gaps."
msgid "Some steps of this guide require to be comfortable with Git. Here are some `tutorials <https://www.atlassian.com/git/tutorials>`_ and an `interactive training <https://learngitbranching.js.org/>`_ if you are stuck at some point."
msgid "Now that your environment is set up, you can start contributing to the codebase. In a terminal, navigate to the directory where you installed Odoo from sources and follow the guide below."
msgid "Choose the version of Odoo to which you want to make changes. Keep in mind that contributions targeting an :doc:`unsupported version of Odoo </administration/supported_versions>` are not accepted. This guide assumes that the changes target Odoo 17, which corresponds to branch `17.0`."
msgid "Create a new branch starting from branch 17.0. Prefix the branch name with the base branch: `17.0-...`. If you work at Odoo, suffix the branch name with your Odoo handle: `17.0-...-xyz`."
msgid "Keep your changes focused and specific. It is best to work on one particular feature or bug fix at a time rather than tackle multiple unrelated changes simultaneously."
msgid "Respect the `stable policy <https://github.com/odoo/odoo/wiki/Contributing#what-does-stable-mean>`_ when working in another branch than `master`."
msgid "Test your changes thoroughly and :doc:`write tests </developer/reference/backend/testing>` to ensure that everything is working as expected and that there are no regressions or unintended consequences."
msgid "Go to the `compare page of the odoo/odoo codebase <https://github.com/odoo/odoo/compare>`_, or the `compare page of the odoo/enterprise codebase <https://github.com/odoo/enterprise/compare>`_, depending on which codebase your changes target."
msgid "Select **<your_github_account>/odoo** or **<your_github_account>/enterprise** for the head repository. Replace `<your_github_account>` with the name of the GitHub account on which you created the fork or by **odoo-dev** if you work at Odoo."
msgid "As soon as your :abbr:`PR (Pull Request)` is ready for merging, a member of the Odoo team will be automatically assigned for review. If the reviewer has questions or remarks, they will post them as comments and you will be notified by email. Those comments must be resolved for the contribution to go forward."
msgid "This page introduces the Odoo Coding Guidelines. Those aim to improve the quality of Odoo Apps code. Indeed proper code improves readability, eases maintenance, helps debugging, lowers complexity and promotes reliability. These guidelines should be applied to every new module and to all new development."
msgid "When modifying existing files in **stable version** the original file style strictly supersedes any other style guidelines. In other words please never modify existing files in order to apply these guidelines. It avoids disrupting the revision history of code lines. Diff should be kept minimal. For more details, see our `pull request guide <https://odoo.com/submit-pr>`_."
msgid "When modifying existing files in **master (development) version** apply those guidelines to existing code only for modified code or if most of the file is under revision. In other words modify existing files structure only if it is going under major changes. In that case first do a **move** commit then apply the changes related to the feature."
msgid "A module is organized in important directories. Those contain the business logic; having a look at them should make you understand the purpose of the module."
msgid "File naming is important to quickly find information through all odoo addons. This section explains how to name files in a standard odoo module. As an example we use a `plant nursery <https://github.com/tivisse/odoodays-2018/tree/master/plant_nursery>`_ application. It holds two main models *plant.nursery* and *plant.order*."
msgid "Concerning *models*, split the business logic by sets of models belonging to a same main model. Each set lies in a given file named based on its main model. If there is only one model, its name is the same as the module name. Each inherited model should be in its own file to help understanding of impacted models."
msgid "Concerning *views*, backend views should be split like models and suffixed by ``_views.xml``. Backend views are list, form, kanban, activity, graph, pivot, .. views. To ease split by model in views main menus not linked to specific actions may be extracted into an optional ``<module>_menus.xml`` file. Templates (QWeb pages used notably for portal / website display) are put in separate files named ``<model>_templates.xml``."
msgid "Concerning *data*, split them by purpose (demo or data) and main model. Filenames will be the main_model name suffixed by ``_demo.xml`` or ``_data.xml``. For instance for an application having demo and data for its main model as well as subtypes, activities and mail templates all related to mail module:"
msgid "Concerning *controllers*, generally all controllers belong to a single controller contained in a file named ``<module_name>.py``. An old convention in Odoo is to name this file ``main.py`` but it is considered as outdated. If you need to inherit an existing controller from another module do it in ``<inherited_module_name>.py``. For example adding portal controller in an application is done in ``portal.py``."
msgid "Concerning *static files*, Javascript files follow globally the same logic as python models. Each component should be in its own file with a meaningful name. For instance, the activity widgets are located in ``activity.js`` of mail module. Subdirectories can also be created to structure the 'package' (see web module for more details). The same logic should be applied for the templates of JS widgets (static XML files) and for their styles (scss files). Don't link data (image, libraries) outside Odoo: do not use an URL to an image but copy it in the codebase instead."
msgid "Concerning *wizards*, naming convention is the same of for python models: ``<transient>.py`` and ``<transient>_views.xml``. Both are put in the wizard directory. This naming comes from old odoo applications using the wizard keyword for transient models."
msgid "For field declaration, ``name`` attribute is first. Then place the *value* either in the ``field`` tag, either in the ``eval`` attribute, and finally other attributes (widget, options, ...) ordered by importance."
msgid "The tag *<data>* is only used to set not-updatable data with ``noupdate=1``. If there is only not-updatable data in the file, the ``noupdate=1`` can be set on the ``<odoo>`` tag and do not set a ``<data>`` tag."
msgid "For an action: the main action respects :samp:`{<model_name>}_action`. Others are suffixed with :samp:`_{<detail>}`, where *detail* is a lowercase string briefly explaining the action. This is used only if multiple actions are declared for the model."
msgid "For a rule: :samp:`{<model_name>}_rule_{<concerned_group>}` where *concerned_group* is the short name of the concerned group ('user' for the 'model_name_group_user', 'public' for public user, 'company' for multi-company rules, ...)."
msgid "Xml Ids of inheriting views should use the same ID as the original record. It helps finding all inheritance at a glance. As final Xml Ids are prefixed by the module that creates them there is no overlap."
msgid "Using a linter can help show syntax and semantic warnings or errors. Odoo source code tries to respect Python standard, but some of them can be ignored."
msgid "Useless variable : Temporary variables can make the code clearer by giving names to objects, but that doesn't mean you should create temporary variables all the time:"
msgid "Learn list comprehensions : Use list comprehension, dict comprehension, and basic manipulation using ``map``, ``filter``, ``sum``, ... They make the code easier to read."
msgid "Collections are booleans too : In python, many objects have \"boolean-ish\" value when evaluated in a boolean context (such as an if). Among these are collections (lists, dicts, sets, ...) which are \"falsy\" when empty and \"truthy\" when containing items:"
msgid "In additions to these guidelines, you may also find the following link interesting: http://python.net/~goodger/projects/pycon/2007/idiomatic/handout.html (a little bit outdated, but quite relevant)"
msgid "The context is a ``frozendict`` that cannot be modified. To call a method with a different context, the ``with_context`` method should be used :"
msgid "Since the values are propagated automatically, some unexpected behavior may appear. Calling ``create()`` method of a model with *default_my_field* key in context will set the default value of *my_field* for the concerned model. But if during this creation, other objects (such as sale.order.line, on sale.order creation) having a field name *my_field* are created, their default value will be set too."
msgid "If you need to create a key context influencing the behavior of some object, choose a good name, and eventually prefix it by the name of the module to isolate its impact. A good example are the keys of ``mail`` module : *mail_create_nosubscribe*, *mail_notrack*, *mail_notify_user_signature*, ..."
msgid "Functions and methods should not contain too much logic: having a lot of small and simple methods is more advisable than having few large and complex methods. A good rule of thumb is to split a method as soon as it has more than one responsibility (see http://en.wikipedia.org/wiki/Single_responsibility_principle)."
msgid "Also, name your functions accordingly: small and properly named functions are the starting point of readable/maintainable code and tighter documentation."
msgid "The Odoo framework is in charge of providing the transactional context for all RPC calls. The principle is that a new database cursor is opened at the beginning of each RPC call, and committed when the call has returned, just before transmitting the answer to the RPC client, approximately like this:"
msgid "Similarly, the system also provides a dedicated transaction during the execution of tests suites, so it can be rolled back or not depending on the server startup options."
msgid "The consequence is that if you manually call ``cr.commit()`` anywhere there is a very high chance that you will break the system in various ways, because you will cause partial commits, and thus partial and unclean rollbacks, causing among others:"
msgid "tests that can't be rolled back cleanly, and will start polluting the database, and triggering error (this is true even if no error occurs during the transaction)"
msgid "You should **NEVER** call ``cr.commit()`` yourself, **UNLESS** you have created your own database cursor explicitly! And the situations where you need to do that are exceptional!"
msgid "And by the way if you did create your own cursor, then you need to handle error cases and proper rollback, as well as properly close the cursor when you're done with it."
msgid "And contrary to popular belief, you do not even need to call ``cr.commit()`` in the following situations: - in the ``_auto_init()`` method of an *models.Model* object: this is taken care of by the addons initialization method, or by the ORM transaction when creating custom models - in reports: the ``commit()`` is handled by the framework too, so you can update the database even from within a report - within *models.Transient* methods: these methods are called exactly like regular *models.Model* ones, within a transaction and with the corresponding ``cr.commit()/rollback()`` at the end - etc. (see general rule above if you are in doubt!)"
msgid "All ``cr.commit()`` calls outside of the server framework from now on must have an **explicit comment** explaining why they are absolutely necessary, why they are indeed correct, and why they do not break the transactions. Otherwise they can and will be removed !"
msgid "Odoo uses a GetText-like method named \"underscore\" ``_( )`` to indicate that a static string used in the code needs to be translated at runtime using the language of the context. This pseudo-method is accessed within your code by importing as follows:"
msgid "Basically, this method should only be used for static strings written manually in the code, it will not work to translate field values, such as Product names, etc. This must be done instead using the translate flag on the corresponding field."
msgid "The method accepts optional positional or named parameter The rule is very simple: calls to the underscore method should always be in the form ``_('literal string')`` and nothing else:"
msgid "Also, keep in mind that translators will have to work with the literal values that are passed to the underscore function, so please try to make them easy to understand and keep spurious characters and formatting to a minimum. Translators must be aware that formatting patterns such as ``%s`` or ``%d``, newlines, etc. need to be preserved, but it's important to use these in a sensible and obvious manner:"
msgid "In general in Odoo, when manipulating strings, prefer ``%`` over ``.format()`` (when only one variable to replace in a string), and prefer ``%(varname)`` instead of position (when multiple variables have to be replaced). This makes the translation easier for the community translators."
msgid "When defining an Odoo Transient (wizard) : use ``<related_base_model>.<action>`` where *related_base_model* is the base model (defined in *models/*) related to the transient, and *action* is the short name of what the transient do. Avoid the *wizard* word. For instance : ``account.invoice.make``, ``project.task.delegate.batch``, ..."
msgid "suffix your variable name with *_id* or *_ids* if it contains a record id or list of id. Don't use ``partner_id`` to contain a record of res.partner"
msgid "Action method : an object action method is prefix with *action_*. Since it uses only one record, add ``self.ensure_one()`` at the beginning of the method."
msgid "Odoo addons have some conventions on how to structure various files. We explain here in more details how web assets are supposed to be organized."
msgid "The first thing to know is that the Odoo server will serve (statically) all files located in a *static/* folder, but prefixed with the addon name. So, for example, if a file is located in *addons/web/static/src/js/some_file.js*, then it will be statically available at the url *your-odoo-server.com/web/static/src/js/some_file.js*"
msgid "*static/lib*: this is the place where js libs should be located, in a sub folder. So, for example, all files from the *jquery* library are in *addons/web/static/lib/jquery*"
msgid "More precise JS guidelines are detailed in the `github wiki <https://github.com/odoo/odoo/wiki/Javascript-coding-guidelines>`_. You may also have a look at existing API in Javascript by looking Javascript References."
msgid ":ref:`Scoped SCSS variables <contributing/coding_guidelines/scss/scoped_scss_variables>` and :ref:`CSS variables <contributing/coding_guidelines/scss/css_variables>` must be placed at the very top, followed by an empty line separating them from other declarations."
msgid "Avoid `id` selectors, and prefix your classes with `o_<module_name>`, where `<module_name>` is the technical name of the module (`sale`, `im_chat`, ...) or the main route reserved by the module (for website modules mainly, i.e. : `o_forum` for the `website_forum` module)."
msgid "Our standard convention is `o-[name]`. Use descriptive names. When naming functions, use verbs in the imperative form (e.g.: `get`, `make`, `apply`...)."
msgid "In Odoo, the use of CSS variables is strictly DOM-related, meaning that are used to **contextually** adapt the design and layout rather than to manage the global design-system. These are typically used when a component's properties can vary in specific contexts or in other circumstances."
msgid "Despite being apparently similar, `CSS` and `SCSS` variables behave very differently. The main difference is that, while `SCSS` variables are **imperative** and compiled away, `CSS` variables are **declarative** and included in the final output."
msgid "`CSS/SCSS variables difference on the SASS Documentation <https://sass-lang.com/documentation/variables#:~:text=CSS%20variables%20are%20included%20in,use%20will%20stay%20the%20same>`_"
msgid "In Odoo, we take the best of both worlds: using the `SCSS` variables to define the design-system while opting for the `CSS` ones when it comes to contextual adaptations."
msgid "The implementation of the previous example should be improved by adding SCSS variables in order to gain control at the top-level and ensure consistency with other components."
msgid "Defining CSS variables on the `:root` pseudo-class is a technique we normally **don't use** in Odoo's UI. The practice is commonly used to access and modify CSS variables globally. We perform this using SCSS instead."
msgid "Exceptions to this rule should be fairly apparent, such as templates shared across bundles that require a certain level of contextual awareness in order to be rendered properly."
msgid "Commit message has four parts: tag, module, short description and full description. Try to follow the preferred structure for your commit messages"
msgid "**[MOV]** for moving files: use git move and do not change content of moved file otherwise Git may loose track and history of the file; also used when moving code from one file to another;"
msgid "After tag comes the modified module name. Use the technical name as functional name may change with time. If several modules are modified, list them or use various to tell it is cross-modules. Unless really required or easier avoid modifying code across several modules in the same commit. Understanding module history may become difficult."
msgid "After tag and module name comes a meaningful commit message header. It should be self explanatory and include the reason behind the change. Do not use single words like \"bugfix\" or \"improvements\". Try to limit the header length to about 50 characters for readability."
msgid "Commit message header should make a valid sentence once concatenated with ``if applied, this commit will <header>``. For example ``[IMP] base: prevent to archive users linked to active partners`` is correct as it makes a valid sentence ``if applied, this commit will prevent users to archive...``."
msgid "In the message description specify the part of the code impacted by your changes (module name, lib, transversal object, ...) and a description of the changes."
msgid "First explain WHY you are modifying code. What is important if someone goes back to your commit in about 4 decades (or 3 days) is why you did it. It is the purpose of the change."
msgid "What you did can be found in the commit itself. If there was some technical choices involved it is a good idea to explain it also in the commit message after the why. For Odoo R&D developers \"PO team asked me to do it\" is not a valid why, by the way."
msgid "Please avoid commits which simultaneously impact multiple modules. Try to split into different commits where impacted modules are different. It will be helpful if we need to revert changes in a given module separately."
msgid "Don't hesitate to be a bit verbose. Most people will only see your commit message and judge everything you did in your life just based on those few sentences. No pressure at all."
msgid "**You spend several hours, days or weeks working on meaningful features. Take some time to calm down and write clear and understandable commit messages.**"
msgid "If you are an Odoo R&D developer the WHY should be the purpose of the task you are working on. Full specifications make the core of the commit message. **If you are working on a task that lacks purpose and specifications please consider making them clear before continuing.**"
msgid "This introductory guide will help you acquire the tools and knowledge you need to write documentation, whether you plan to make a minor content change or document an application from scratch."
msgid "Read the :ref:`introduction to the reStructuredText language <contributing/documentation/rst-intro>` if you are not familiar with it. Then, you have two courses of action to start contributing to the documentation, depending on whether you want to propose minor changes to existing content or you instead want to work on significant changes to new and existing content."
msgid "**For minor changes**, for example, adding a paragraph or fixing a typo, we recommend **using the GitHub interface**. This is the easiest and fastest way to submit your changes, and it is suitable for non-technical people. Jump directly to the :ref:`contributing/documentation/first-contribution` section to get started."
msgid "**For more complex changes**, it is necessary to **use Git** and work from a local copy of the documentation. Follow the instructions in the :ref:`contributing/documentation/setup` section to first prepare your environment."
msgid "The documentation is written in **reStructuredText** (RST), a `lightweight markup language <https://en.wikipedia.org/wiki/Lightweight_markup_language>`_ consisting of regular text augmented with markup, which allows including headings, images, notes, and so on. This might seem a bit abstract, but there is no need to worry; :abbr:`RST (reStructuredText)` is not hard to learn, especially if you intend to make minor changes to the content."
msgid "If you need to learn about a specific markup, head over to our :doc:`cheat sheet for RST <documentation/rst_cheat_sheet>`; it contains all the information you should ever need for the documentation of Odoo."
msgid "We kindly ask you to observe a set of :doc:`content <documentation/content_guidelines>` and :doc:`RST <documentation/rst_guidelines>` guidelines as you write documentation. This ensures that you stay consistent with the rest of the documentation and facilitates the approval of your content changes as the Odoo team reviews them."
msgid "The instructions below help you prepare your environment for making local changes to the documentation and then push them to GitHub. Skip this section and go to :ref:`contributing/documentation/first-contribution` if you have already completed this step or want to make changes from the GitHub interface."
msgid "Go to `github.com/odoo/documentation <https://github.com/odoo/documentation>`_ and click on the :guilabel:`Fork` button in the top right corner to create a fork (:dfn:`your own copy`) of the repository on your account. This creates a copy of the codebase to which you can make changes without affecting the main codebase. Skip this step if you work at Odoo."
msgid "Configure Git to push changes to your fork rather than to the main codebase. In the commands below, replace `<your_github_account>` with the name of the GitHub account on which you created the fork. Skip this step if you work at Odoo."
msgid "Install the latest release of `Python <https://wiki.python.org/moin/BeginnersGuide/Download>`_ and `pip <https://pip.pypa.io/en/stable/installation/>`_ on your machine."
msgid "Follow the `guide to update the PATH variable on Linux and macOS <https://unix.stackexchange.com/a/26059>`_ with the installation path of the Python dependencies (by default :file:`~/.local/bin`)."
msgid "Follow the `guide to update the PATH variable on Windows <https://www.howtogeek.com/118594/how-to-edit-your-system-path-for-easy-command-line-access/>`_ with the installation path of the Python dependencies."
msgid "Verify that you are browsing the documentation in the version that you intend to change. The version can be selected from the dropdown in the top menu."
msgid "Click on the :guilabel:`Fork this repository` button to create a fork (:dfn:`your own copy`) of the repository on your account. This creates a copy of the codebase to which you can make changes without affecting the main codebase. Skip this step if you work at Odoo."
msgid "Make the desired changes while taking care of following the :doc:`content <documentation/content_guidelines>` and :doc:`RST <documentation/rst_guidelines>` guidelines."
msgid "Click on the :guilabel:`Preview changes` button to review your contribution in a more human-readable format. Be aware that the preview is not able to handle all markups correctly. Notes and tips, for instance, are shown as plain text."
msgid "Scroll to the bottom of the page and fill out the small form to propose your changes. In the first text box, write a very short summary of your changes. For instance, \"Fix a typo\" or \"Add documentation for invoicing of sales orders.\" In the second text box, explain *why* you are proposing these changes. Then, click on the :guilabel:`Propose changes` button."
msgid "Now that your environment is set up, you can start contributing to the documentation. In a terminal, navigate to the directory where you cloned the sources and follow the guide below."
msgid "Choose the version of the documentation to which you want to make changes. Keep in mind that contributions targeting an :doc:`unsupported version of Odoo </administration/supported_versions>` are not accepted. This guide assumes that the changes target the documentation of Odoo 17, which corresponds to branch `17.0`."
msgid "Build the documentation with :command:`make`. Then, open :file:`_build/index.html` in your web browser to browse the documentation with your changes."
msgid "Select **<your_github_account>/odoo** for the head repository. Replace `<your_github_account>` with the name of the GitHub account on which you created the fork. Skip this step if you work at Odoo."
msgid "To give the community the best documentation possible, we listed here a few guidelines, tips and tricks that will make your content shine at its brightest! While we encourage you to adopt your own writing style, some rules still apply to give the reader more clarity and comprehension."
msgid "We strongly recommend contributors to carefully read the other documents related to this section of the documentation. Good knowledge of the ins and outs of **RST writing** is required to write and submit your contribution. Note that it also affects your writing style itself."
msgid "**Writing for documentation** isn't the same as writing for a blog or another medium. Readers are more likely to skim read until they've found the information they are looking for. Keep in mind that the user documentation is a place to inform and describe, not to convince and promote."
msgid "Make sure that your writing style remains **consistent**. If you modify an existing text, try to match the existing tone and presentation, or rewrite it to match your own style."
msgid "In English, descriptions and instructions require the use of a **Present Tense**, while a *future tense* is appropriate only when a specific event is to happen ulteriorly. This logic might be different in other languages."
msgid "In English, a new idea implies a new paragraph, rather than having a *line break* as it is common to do in some other languages. *Line breaks* are useful for layout purposes but shouldn't be used as a grammatical way of separating ideas."
msgid "Use different **heading levels** to organize your text by sections and sub-sections. Your headings are not only displayed in the document but also on the navigation menu (only the H1) and on the \"On this page\" sidebar (all H2 to H6)."
msgid "The *content* in this section describes the upcoming content from a **business point of view**, and shouldn't put the emphasis on Odoo, as this is documentation and not marketing."
msgid "Start first with a **lead paragraph**, which helps the reader make sure that they've found the right page, then explain the **business aspects of this topic** in the following paragraphs."
msgid "This first H2 section is about the configuration of the feature, or the prerequisites to achieve a specific goal. To add a path, make sure you use the ``:menuselection:`` specialized directive (see link below)."
msgid "Create as many main sections as you have actions or features to distinguish. The title can start with a verb, but try to avoid using \"Create ...\"."
msgid "For most topics, a single page should do the job. Place it in the appropriate section of the documentation (e.g., content related to the CRM app go under :menuselection:`Applications -> Sales -> CRM`) and follow the :ref:`document structure <contributing/document-structure>` guidelines."
msgid "For more complex topics, you may need several pages to cover all their aspects. Usually, you will find yourself adding documentation to a topic that is already partially covered. In that case, either create a new page and place it at the same level as other related pages or add new sections to an existing page. If you are documenting a complex topic from scratch, organize your content between one parent page (the :abbr:`TOC (Tree Of Contents)` page) and several child pages. Whenever possible, write content on the parent page and not only on the child pages. Make the parent page accessible from the navigation menu by using the :ref:`show-content <contributing/document-metadata>` metadata directive."
msgid "Adding a few images to illustrate your text helps the readers to understand and memorize your content. However, avoid adding too many images: it isn't necessary to illustrate all steps and features, and it may overload your page."
msgid "Screenshots are automatically resized to fit the content block's width. This implies that screenshots can't be too wide, else they would appear very small on-screen. Therefore, we recommend to avoid to take screenshots of a full screen display of the app, unless it is relevant to do so."
msgid "**Resize** your browser's width, either by *resizing the window* itself or by opening the *browser's developer tools* (press the ``F12`` key) and resizing the width."
msgid "Resizing the window's width is the most important step to do as Odoo's responsive design automatically resizes all fields to match the window's width."
msgid "Previously, image filenames would mostly be named with numbers (e.g., :file:`feature01.png`) and placed in a single ``media`` folder. While it is advised not to name your *new* images in that fashion, it is also essential **not to rename unchanged files**, as doing this would double the weight of renamed image files on the repository. They will eventually all be replaced as the content referencing those images is updated."
msgid "An **ALT tag** is a *text alternative* to an image. This text is displayed if the browser fails to render the image. It is also helpful for users who are visually impaired. Finally, it helps search engines, such as Google, to understand what the image is about and index it correctly, which improves the :abbr:`SEO (Search Engine Optimization)` significantly."
msgid "The symbols used for the formatting are, in fact, not important. Only the order in which they are written matters, as it determines the size of the decorated heading. This means that you may encounter different heading formatting and in a different order, in which case you should follow the formatting in place in the document. In any other case, use the formatting shown below."
msgid "Use the `guilabel` markup to identify any text of the interactive user interface (e.g., button labels, view titles, field names, lists items, ...)."
msgid "A `proof-of-concept <https://en.wikipedia.org/wiki/Proof_of_concept>`_ is a simplified version, a prototype of what is expected to agree on the main lines of expected changes. `PoC <https://en.wikipedia.org/wiki/Proof_of_concept>`_ is a common abbreviation."
msgid "Custom anchors follow the same syntax as external hyperlink aliases but without any URL. Indeed, they are internal. They allow referencing a specific part of a document by using the target as an anchor. When the user clicks on the reference, the documentation scrolls to the part of the page containing the anchor."
msgid "Please refer to `this documentation <https://example.com/doc/accounting/invoices.html>`_ and to `Send a pro-forma invoice <https://example.com/doc/sales/proforma.html>`_."
msgid "The ``download`` markup allows referencing files (that are not necessarily :abbr:`RST (reStructuredText)` documents) within the source tree to be downloaded."
msgid "Add the :code:`:class: o-no-modal` `option <https://docutils.sourceforge.io/docs/ref/rst/directives.html#common-options>`_ to an image to prevent opening it in a modal."
msgid "List tables use two-level bulleted lists to convert data into a table. The first level represents the rows and the second level represents the columns."
msgid "Make use of `this convenient table generator <https://www.tablesgenerator.com/text_tables>`_ to build your tables. Then, copy-paste the generated formatting into your document."
msgid "Basic tabs are useful to split the content into multiple options. The `tabs` markup is used to define sequence of tabs. Each tab is then defined with the `tab` markup followed by a label."
msgid "Group tabs are special tabs that synchronize based on a group label. The last selected group is remembered and automatically selected when the user returns to the page or visits another page with the tabs group. The `group-tab` markup is used to define group tabs."
msgid "Code tabs are essentially :ref:`group tabs <contributing/tabs/group>` that treat the content as a :ref:`code block <contributing/code-blocks>`. The `code-tab` markup is used to define a code tab. Just as for the `code-block` markup, the language defines the syntax highlighting of the tab. If set, the label is used instead of the language for grouping tabs."
msgid "Markup symbols escaped with backslashes (``\\``) are rendered normally. For instance, ``this \\*\\*line of text\\*\\* with \\*markup\\* symbols`` is rendered as “this \\*\\*line of text\\*\\* with \\*markup\\* symbols”."
msgid "When it comes to backticks (`````), which are used in many cases such as :ref:`external hyperlinks <contributing/external-hyperlinks>`, using backslashes for escaping is no longer an option because the outer backticks interpret enclosed backslashes and thus prevent them from escaping inner backticks. For instance, ```\\`this formatting\\```` produces an ``[UNKNOWN NODE title_reference]`` error. Instead, `````this formatting````` should be used to produce the following result: ```this formatting```."
msgid "If you need to reference an internal documentation page or a file that is not sitting in the same directory as your current page, always make use of *relative file paths* rather than *absolute file paths*. An absolute file path indicates the location of the target from the root of its file tree. A relative file path makes use of smart notations (such as ``../`` that redirects to the parent folder) to indicate the location of the target *relative* to that of the source document."
msgid "The relative links are clearly superior in terms of readability and stability: the references survive version updates, folder name changes and file tree restructurations."
msgid "In RST, it is possible to break a line without forcing a line break on the rendered HTML. Make use of this feature to write **lines of maximum 100 characters**. A line break in a sentence results in an additional whitespace in HTML. That means that you do not need to leave a trailing whitespace at the end of a line to separate words."
msgid "You can safely break a line around the separators (``-->``) of ``menuselection`` markups and anywhere in a hyperlink reference. For the ``doc``, ``ref`` and ``download`` markups, this is only true for the label part of the reference."
msgid "Use as many spaces at the beginning of an indented line as needed to align it with the first character of the markup in the line above. This usually implies 3 spaces but you only need 2 for bulleted lists."
msgid "Although chaining characters ``‣`` and menu names works fine to indicate a user which menus to click, it is best to use the ``menuselection`` markup (see :ref:`contributing/menuselection`) for the same result. Indeed, it renders the menus chain consistently with the rest of the documentation and would automatically adapt to the new graphic chart if we were to switch to a new one. This markup is used inline as follows: ``:menuselection:`Sales --> Settings --> Products --> Variants```."
msgid "Prefer the use of ``#.`` in numbered lists instead of ``1.``, ``2.``, etc. This removes the risk of breaking the numbering when adding new elements to the list and is easier to maintain."
msgid "Avoid using implicit hyperlink targets and prefer internal hyperlink targets instead. Referencing the implicit target ``How to print quotations?`` is more prone to break than a reference to the explicit target ``_print_quotation`` which never appears in the rendered HTML and is thus even less likely to be modified."
msgid "As hyperlink targets are visible from the entire documentation when referenced with the ``ref`` markup, it is recommended to prefix the target name with that of the related application. For instance, naming a target ``_amazon/form`` instead of ``_form`` avoids unwanted behaviors and makes the purpose of the target clear."
msgid "When refactoring (improving without adding new content) section headings or hyperlink targets, take care not to break any hyperlink reference to these targets or update them accordingly."
msgid "Although using a double-underscore suffix works most of the time for classic hyperlink references, it is not recommended as double-underscores normally indicate an anonymous hyperlink reference. This is a special kind of hyperlink reference that makes use of nameless hyperlink targets consisting only of two underscore."
