1. Mailing Lists
  2. Contributors
  3. Re: Discover the OCA priorities for 2021 proposed by the board

Contributors mailing list archives

contributors@odoo-community.org

Browse archives

Re: Discover the OCA priorities for 2021 proposed by the board

Avatar

Re: Discover the OCA priorities for 2021 proposed by the board

by
Tecnativa. S. L., Jairo Llopis
- 25/05/2021 11:17:04
I don't know but I feel like any standard solution won't work for us.

In a normal software project, you just have 1 branch (maybe 2: devel/stable). Then you add sphinx/mkdocs on a separate folder and docs live happily with your source code. Besides, those tools analyze your docstrings and autogenerate docs. Each repo contains 1 package, which has a single evolving version that follows a standard schema such as PEP 400, semver, calver, etc.

OCA has a workflow that is very alien to general github workflow:
  1. Code is spread across different repos.
  2. Each repo has different modules which can be tightly or loosely related among themselves and among modules that might exist in other repos.
  3. Each module has its own version. Which, BTW, means nothing in reality and follows a different schema imposed by Odoo and some OCA members.
  4. Each repo has multiple maintained versions of each module, one (or zero) per branch.
I think this is a deeply rooted problem across the whole OCA that hinders contributions and makes any move hard to achieve. I've tried to fix that in the past without success, so I don't care anymore. It's the OCA we have and I have to accept that.

So, having all that said, I think that the only way this could work is stick as it is: one README per module/version pair.

Odoo docs situation is today less crazy, so in case we have some functional stuff to document, if possible, the place to do it would be https://github.com/odoo/documentation

IMHO user docs should be avoided and, instead, modules should be self-explained within the UI. That goes through having friendly empty pages, tours, help tooltips, self-explained dialogs, res.config.settings dialogs, etc. Just make the module obvious and save documentation.

For other kind of cross-module, cross-repo, deployment, etc, kind of docs, possibly a single mkdocs repo could be deployed. As it wouldn't be coupled with any specific repo, odoo version or module, it wouldn't need any versioning or branching: just one main branch and build on each commit.

Reference