This is the documentation for older versions of Odoo (formerly OpenERP).

See the new Odoo user documentation.

See the new Odoo technical documentation.

Рекомендации по участию

Отчёты об ошибках

Все подробности, касающиеся отчётов об ошибках и их обработки, расположены в разделе Отчёты об ошибках и работа с ними.

Предложения слияния и заплатки

Довольно легко выполнить заплатку и предложить включить её во все проекты OpenERP. Однако следование некоторым рекомендациям ощутимо поможет увеличить шансы включения вашей заплатки в код быстро.

However, in order to tremendously increase the chances of getting your patch noticed and merged, you should pay attention to the Merge Proposal Acceptance Policy and then carefully follow the Merge Proposal Guidelines.

Merge Proposal Acceptance Policy

OpenERP's R&D expects to receive merge proposals from the Community in these areas:

  • patches to correct a bug in an official addons

  • patches to improve an existing official addon, such as extending a feature or adding one

OpenERP's R&D does not expect to receive merge proposals from the Community in these areas:

  • addition of an extra feature to an official addons, when the feature should really provided by a separate (new) module

  • addition of a new module to the official addons

For these last cases, it is better to put the feature into new modules entirely maintained by their authors in their own Launchpad repository, and published on OpenERP Apps, to be visible by the whole Community. This is totally unrelated to the quality of the proposition: there are tons of great community modules on OpenERP Apps, some of them already downloaded thousands of times!

However, including a module in the official release is a big commitment in terms of review maintenance, support, etc. In addition, it would quickly bloat the OpenERP core if done too often, compromising its agility and maintainability, and thus the future of the product. On the other hand, by progressively integrating OpenERP Apps better in the product, we should reach the same visibility for Community modules, without incurring these risks.

Therefore the process of including a community module into the official addons is entirely driven by OpenERP R&D based on the product strategy. In addition to features selected by OpenERP Product Managers, features that are considered REQUIRED to use OpenERP in a certain market/domain will also be considered for inclusion. Deciding whether a feature is REQUIRED is quite subjective, but the following hints are useful:

  • if most established competitors on the given market/domain implement this feature, and this domain is normally addressed by official OpenERP addons, then it's likely REQUIRED.

  • on the other hand, if no established software competitors on the given market/domain implement this feature, then it's probably NOT REQUIRED.

This certainly doesn't mean we don't want to innovate (that's the part where Product Managers choose new features!), this is only for deciding that a module is REQUIRED and thus it is necessary to include it in the default installations.

Of course, on top of the above, a merge proposal needs to pass the functional and technical review by OpenERP's R&D, and even though we do our best to process them in a timely fashion, there is no guarantee it will be accepted, nor when.

Merge Proposal Guidelines

В основном процедура состоит из следующего:

  1. Register on Launchpad if not done yet

  2. Если вы хотите без проблем публиковать свои изменения, настройте пару ключей для SSH и зарегистрируйте ваш публичный ключ на странице профиля Launchpad. Затем используйте команду, чтобы предоставить Bazaar свою учётную запись на Launchpad:

    $ bzr launchpad-login <your-launchpad-login>
    
  3. Создайте локальную копию ветви, для которой планируется заплатка, например для версии OpenERP-сервера для разработчиков это будет:

    $ bzr branch lp:openobject-server
    
    ..note:: If you want to avoid downloading many times the large history

    of OpenERP's source code, you may want to create a proper shared repository.

  4. Работайте с локальной ветвью, фиксируйте изменения, не забывая оставлять содержательные сообщения о фиксации. Помните про параметр --fixes, если ваша работа затрагивает конкретную указанную на LaunchPad ошибку:

    $ ... patch the code ...
    $ bzr ci --fixes lp:12345 -m '[FIX] fixed formatting of date field'
    
  5. Отправьте проделанную работу обратно на Launchpad в виде отдельной ветви в персональном пространстве или в пространстве любой другой команды, участником которой вы являетесь (например, openerp-community):

    $ bzr push lp:~openerp-community/openobject-server/trunk-bugfix-12345
    
  6. Наконец, перейдите на страницу вашей ветви на Launchpad, нажмите на ссылку Propose for merging, выберите соответствующий проект и ветвь и предоставьте полноценное описание своей работы. URL новой ветви будет иметь вид:

    https://code.launchpad.net/~openerp-community/openobject-server/trunk-bugfix-12345
    

Следующие советы и рекомендации не менее полезны при публикации заплатки:

  1. Внимательно выбирайте соответствующую ветвь для вашей заплатки. Например, если ваша заплатка вносит улучшение, но технически не исправляет ошибку, не стоит предлагать вносить её в стабильную ветвь. Стабильная ветвь принимает только исправления ошибок, так что предложите внести ваш код в ветвь trunk. См. также определение ошибки.

  2. Очевидно, стоит обратить внимание на Coding Guidelines.

  3. При следовании рекомендациям по программированию, не будьте фанатичны. Если существующий код не соответствует рекомендациям — чинить стоит лишь те строки, которые вы изменяете, а не все остальные. Иначе вы быстро обнаружите, что меняете слишком многое, и ваше исправление будет отклонено.

  4. Пожалуйста проверьте ваши изменения перед их фиксацией, чтобы избежать ненужного шума в предложении слияния, вроде дополнительных пустых строк и тому подобного. Используйте команды bzr status, затем bzr diff и bzr cdiff, чтобы чётко представлять, что вы изменили, перед тем как фиксировать изменения.

  5. Не стесняйтесь откатить плохую версию. Самое время сделать это перед тем, как предложите свою ветвь к объединению. Команда bzr uncommit полезна при локальной работе.

  6. Каждый раз работайте над отдельной функцией/ошибкой/чем-то ещё. Не смешивайте множество изменений в одном предложении слияния, так как будет сложно рецензировать это предложение, и оно будет отклонено.

  7. Создавайте отдельные ветви и предложения слияния для отдельных изменений.

  8. Чем меньше и чище предложение слияния, тем более вероятно, что оно будет принято.

  9. Избегайте любого вида автоматического форматирования, как то преобразования пустых строк или перегруппировка. Даже если оригинальный код уродлив, это сделает рецензирование, возможно, более проблематичным. Если вы действительно хотите этим заняться — делайте это в отдельной ветви и с отдельным предложением слияния, и чётко объясните зачем вам это понадобилось.

  10. Будьте точны и честны при описании своего исправления и в сообщениях о фиксации изменений. Не предлагайте к слиянию исправление, в описании которого сказано "некоторые улучшения поведения", а внутри содержатся новые функции или вновь добавленные поля и т.д. Фактически, вы должны безусловно предупредить рецензентов обо всём этом, особенно если вы не можете разделить эти изменения на несколько предложений слияния. Если изменения в поведении могут быть рецензированы простой проверкой обновлённых видов, то любые изменения в коде на python требуют тщательной проверки и никогда не должны проходить незамеченными.

  11. Если ваша заплатка очень длинная (допустим, более 100 строк), советуем разделить её на множество атомарных заплаток, которые будет проще изучить. Вы можете совершить множество успешных предложений слияния, зависящих друг от друга. Это также полезно когда работа проделана с несколькими проектами (например, заплатка для проекта addons, которая требует заплатки для server).

  12. Если для вашего исправления всё ещё нужно вносить изменения в множество строк сразу в основной ветси (не похоже, чтобы на это была серьёзная причина), и если разделение на отдельные части невозможно (например, предложить рефакторинг, затем функциональное изменение, потом изменения поведения и т.д.), тогда безусловно стоит предложить для него отдельные тесты. Эти тесты должны подтвержать корректность работы системы после применения ваших изменений и проверять, что ваша заплатка не ломает существующих функций.

  13. Ещё раз о правильном размере: старайтесь делать предложения слияния малыми насколько это возможно. Это нормально, если вы сможете удержать весь текст предложения в голове в момент, когда начнёте писать код.

Using shared repositories to speed up branch management

Bazaar is a distributed version control system, and this means that every time you copy, upload or download a bazaar branch, you are carrying around a complete repository. OpenERP's repositories now contain several hundred megabytes of history, and this may represent a fair bit of bandwidth and time whenever you transfer a branch over the network (for example when you want to create a merge proposal).

There are ways to avoid this overhead if you learn to master the concepts of shared repositories and stacked branches of Bazaar and Launchpad.

Shared Repositories

A "shared repository" allows several branches to be stored under an umbrella repository that centralizes the history of the branches, avoiding duplication of the revisions. Importing a new branch in such a shared repo will only require the download of the history delta: the revisions in the new branch that are not yet known in the shared repository. It works in your local copy of the branches as long as you make sure to branch/pull inside a relevant shared repository.

A shared repository is created using the bzr init-repo command. For mode details have a look at the shared repository tutorial: http://wiki.bazaar.canonical.com/SharedRepositoryTutorial

Stacked branches

As described in the official Bazaar documentation, a stacked branch is a branch that knows how to find revisions in another branch (the stacked-on branch). Stacked branches store just the unique revisions that are not in the stacked-on branch, making them faster to create and more storage efficient.

Launchpad will automatically try to stack new branches you push onto the trunk branch. This means that whenever you execute a bzr push lp:... command, it will only need to upload the revisions that are not present in the latest trunk. You can also manually specify the branch to stack on using the --stacked-on parameter. This may be useful if you are pushing branches that have significant deltas with the trunk, such as older stable branches.

For more details on stacked branches, see also the official Bazaar documentation.

In a nutshell

Practically, here is how you can use shared repositories and stacked branches to speed up day-to-day branch management.

Downstream

To initialize a proper shared repository you do the following:

# create an empty repo for addons
$ bzr init-repo addons
$ cd addons
# grab trunk addons -> full download!
$ bzr branch lp:openobject-addons trunk

The first download in the repository will be the only full one, because it starts empty. If you have a local copy of some addons branch somewhere, you can branch from the local path instead of the lp: URL, it will be much faster.

From then on, you can download any remote or local addons branch inside this shared repo, bzr will automatically detect the shared repo and only download the revisions that were not know yet in it (the delta). For example:

# grab 6.1 addons -> delta only
$ bzr branch lp:openobject-addons/6.1
# grab 6.0 addons -> delta only
$ bzr branch lp:openobject-addons/6.0

Примечание

the OpenERP 6.1 Release Notes mention a a script that is used by OpenERP developers to initialize a development environment. It can automate the creation of the share repository structure. You can use it as follows:

$ bzr cat -d lp:~openerp-dev/openerp-tools/trunk setup.sh | sh
$ make help          # << Read the available commands
$ make init-trunk    # << Fetch the trunk projects in a shared repo
$ make server        # << Start OpenERP Server with embedded Web

Upstream

It's a little bit different when you push a branch: there is no shared repository, but Launchpad will automatically use stacked branches. Have a look at the metadata of the 6.1 addons branch on Launchpad here: https://code.launchpad.net/~openerp/openobject-addons/6.1

You'll see mentioned at the bottom: Stacked on: lp:openobject-addons. It means that the 6.1 branch is stacked on the trunk branch.

This happens transparently whenever you push a branch in a LP project: bazaar will automatically stack it on the trunk branch. But you can specify the stacking branch yourself if you prefer, which is useful sometimes (see below).

Let's say I write a bugfix following the merge_proposals_guidelines . When I do the push this is what I will see:

$ bzr push lp:~openerp-community/openobject-addons/trunk-bug-123456
Using default stacking branch /+branch-id/243984 at chroot-71245584:///~openerp-community/openobject-addons/
(...)

This cryptic message means my branch was stacked on trunk, so only the revisions that are not present in trunk will need to be uploaded. As a result, pushing a bugfix branch on trunk usually only takes a few seconds.

Now if you're working on a stable branch rather than trunk, there may still be a large delta to upload because there are many revisions that were added to in stable after it was forked off trunk (the largest ones being the translations!) In that case you can manually tell bzr to stack on the 6.1 branch rather than trunk, as follows:

$ bzr push lp:~openerp-community/openobject-addons/6.1-bug-123456 --stacked-on bzr+ssh://bazaar.launchpad.net/~openerp/openobject-addons/6.1

There are a couple of caveats with this stacking mechanism:

  • the --stacked-on parameter must use the full bzr+ssh://bazaar.launchpad.net protocol prefix, the usual lp: shortcut does not work (yet?)

  • the stacking cannot be modified on remote branches, so if you get it wrong the first time (or it simply fails) you must go on the branch URL on Launchpad (https://code.launchpad.net/full_name_of_branch) and delete it, then push again.

This certainly takes a bit of getting used to, but once you understand the key ideas you will almost never need full branch uploads/downloads anymore.