Target Methodology

this section details the optimal workflow and structure for managing the modules and customer deployments.

Module Managment

Most modules will be treated as a part of a Package such as "bzb-core" or "bzb-accounting-base". 
A package will contain a small collection of modules and is treated as one unit, meaning that the package is both priced, versioned and developed together.

bzb-core-17
bzb-core-18
bzb-core-19
bzb-accounting-base-17
...

The Package

Each package repo is an addons root containing multiple Odoo modules with the following tructure:

bzb-core-18/
  README.md
  bzb_module_a/
    __manifest__.py
    models/
    views/
    security/
    tests/
    README.md
  bzb_module_b/
      ...

the README will have to be properly maintained containing details about each module, the package itself, how it should be deployed, if there are any Odoo configurations required with this package etc...

The Package will have one main branch always called "main" and as few as possible development branches. but this will be addressed at the workflows section.

Deployment Methodology

The Packages will be deployed in the customer repo (odoo.sh repo) as a git submodule with a release references.
Meaning no more copy-paste modules and no more "soft" version control. 

CustomerA/
  addons/
    bzb-core-18/               # git submodule → bzb-core-18 repo -> reference release "18.0.2026.01.1"
    bzb-accounting-base-18/    # git submodule → bzb-accounting-base-18 repo (optional) -> reference release "18.0.2026.05.1"
    customer_specific/         # small customer-only modules (no shared logic here)
  README.md

by using git submodules which explicitly reference a version release in the main branch we gain a few major benefits:

1. Single source of truth- every module will only exist at one place (per Odoo version) which is the main branch of the package repo.
2. Certainty regarding version - there will no longer be any question like "is the latest version of PCN report deployed on customer B?" since we can always just look at the reference version and see if it is the latest
3. No automatic updates- even when a new version of bzb-base-19 is realsed on the main branch. this will not effect any customer until we manually "bump" the referenced release in the customer repo to the latest.
4. Easy Rollback- if we find out that a certain package release has bugs after we deployed it to a customer, we can simply "rollback" the package by undoying the release reference bump. 

Development Flow

In general there a 3 types of development tickets:

Package Feature/Bug (regular ticket)

Regular feature requests and non-urgent bug reports regarding a specific module (and package) should make up the overwhelming majority of the development.
In essence those are coding tasks which are not urgent enough so they can be properly developed on a local env and a dev branch of the package repo, then tested on staging and at the end merged into main branch and set as a new release.

Regarding Odoo versions, since every package will have several replicas (17, 18, 19) the development will be stricktly forward-first, 
meaning all development will be made on the latest Odoo version (currently 19) and afterwards backported (migrated) into the previous versions.

The development process will resemble the following:

1. create new dev branch from main (latest release)
2. 1. maybe use branch name format: "DEV-<date>-<ticket id>" to easily connect branches to individual tickets
3. implement fixes or develop features
4. test locally
5. create new staging branch on suitable pilot customer env which is currently using the latest relase of the package
6. replace the submodule reference from a release specific to a floating branch reference of the package dev branch
7. test in staging
8. 1. fixes can be made on the package dev branch and redeployed to staging by re-triggering the build process
9. merge the changes into main with full documentation and as a new release
10. 1. possibly with PR and review?
11. bump version in pilot customer production branch
12. rollout version bumps to all customer using this package
13. 1. possibly after waiting a few days to check if everything is okay
14. backport changes to other Odoo versions (possibly start at step 6.)

Hotfix

Hotfixes are critical and urgent bugs which cannot wait for the regular dev flow and must be fixed ASAP. Hotfixes should be extremely rare.

there are several ways to approach a hotfix depending on the situation and should be approched with:

1. move submodule reference from main release to floating dev branch.
   this is ideal in most cases since it allows full tracking of required changes and still being fast to dev and deploy but could be difficult if the customer is not using the latest release of the package.
2. localize module instead of submodule - meaning temporeraly replace the submodule reference with a copy-pasted version of the package and make the fixes localy (like we do today)
3. local module patch - it is also possible to create a patch module on the customer repo which inherits and fixes the error from the original module. this is not ideal because it adds deployment complexity but it has the advantage of clearly showing what the changes are so they can later be reproduced on the real package.

The most important thing about Hotfixes is that they are an extreme scenario and all the solutions above are strictly temporary.
Once a developer is assigned to a hotfix they should not only drop everything they are doing, but they should also work on nothing else until the hotfix i both temporarily fixed AND the fix has been implemented into the real package, rolled out as a release and the temporary solution removed. leaving the temporary fix in place and moving on to another ticket should absolutly never happen.

the workflow on a hotfix should be as follows:

1. investigate bug and choose most suitable fix option from above
2. 1. first make sure the customer isnt simply using an outdated package release and the bug wasnt fixed already in a newer release
3. implement temporary fix 
   (now pressure is partly off)
4. create new dev branch from main in package
5. implement the same fix
6. merge and release new version
7. undo the temporary fix on the customer and instead return to a submodule with a reference to the new release
8. rollout to all customers

Customer Specific customization

those are modules and code changes that are customized only to one customer and are not part of any bzb package.
they should be handled as regular module which is located directly on the customer repo. 
This can also include permanent patches to bzb packages for the customer.

Pre-Transition testing and POC

Run these checks before migrating all customers, to validate the approach end-to-end.

odoo.sh Submodule Checkout Validation

For each target Odoo major (17/18/19), create a pilot customer repo that includes a submodule:

• Verify odoo.sh fetches submodule contents during build
• Verify module folders are visible in:
  • runtime build environment
  • the odoo.sh editor (including the notebook editor, if used)
    test changes to modules done with Jupyter
• confirm odoo.sh can access private submodules (deploy key / permissions)
• confirm key rotation process exists

Addons Path Discovery Test

Validate that Odoo detects modules located at:

• addons/bzb-core-18/(module folders)
• addons/bzb-pos-18/(module folders)

Success criteria:

• All expected modules appear in Apps after update
• Dependency resolution across group repos works (module in pos depends on module in core)

If addons_path cannot be configured to include these directories cleanly, adjust structure (e.g., include addons/ inside each group repo and point addons_path to that).

Dependency & Installability Matrix

Create an “install matrix” for each group repo:

• install each module on a clean database
• confirm no missing dependencies / broken data files

At minimum, cover:

• highest-risk modules
• modules used by the largest number of customers

Rollback Drill

Simulate:

• a bad release tag
• rollback customer repo by moving submodule pointer back one tag

Questions & Answers