[RFC] updating documentation with new 14 design

[legalsylvain]

Hi all.

following that thread #2440 and the PoC available here https://github.com/grap/openupgrade-framework/tree/14.0 and OCA/server-tools#1941, part of the documentation are missing in the new design AND should be updated.

Current documentation (until V13)

• documentation is available in the Openupgrade project in a subdirectory odoo/openupgrade/doc/source/. link
• when documentation is updated on github, this website is updated https://doc.therp.nl/openupgrade/
• AFAIK, the reason why the website is hosted by therp is historical, because before being an OCA project, Openupgrade was initiated in 2011, by the company Therp in which @StefanRijnhart worked. (Bazaar history)

Remarks

with the current refactoring, part of the documentation is obsolete, and should be written again. In the meantime, it is still valid for the previous version (until migration from 12.0 to 13.0).

I see two strategies :

A) Same logic :

• copy the doc folder into the new Openupgrade 14.0 branch and maintain documentation.
• make website pointing on the new 14.0 folder.
• in that case, we should on several pages write some "For Openupgrade 13 (or less) " / "For Openupgrade 14+", regarding settings and how to run the upgrade. Also for the openupgrade_records moved and renamed into OCA/server-tools/upgrade_analysis. I'm afraid this will make the documentation confusing.

B) refactor the documentation :

• move some parts of the documentation into the upgrade_analysis readme files, all the part regarding "How to run your own analysis".
• move other parts of the documentation into the openupgrade_framework readme files
• move other parts of the documentation in the readme file of the Openupgrade repository. (specially generic information, how to support the project, and how to contribute to it.)
• remove obsolete section, describing old Openupgrade behaviour.
• regarding the coverage of the migration (13.0 to 14.0), set the content as a file in openupgrade_scripts/readme/roadmap.rst because in reality it corresponds exactly to a roadmap of this module, and it will be displayed everywhere. (stores, pipy) that is important, in my opinion.

regarding the website,

• keep the website pointing on the 13.0 revision and assume that the website describes the "old design".
• add a simple banner that mention "For openupgrade 14.0+, please see the documentation available https://github.com/OCA/Openupgrade."

I'm more in favour of the solution B but I'm maybe wrong, and it will create another branch named 14.0-doc-pocalypse, maybe it's too much !
So just a proposal.

@OCA/openupgrade-maintainers point of view welcome. (also people working in Therp. @NL66278 ?)

thanks.

[yajo]

There are a few facts to keep in mind:

1. The docs for a module should always refer to a module, and not to a migration process.
2. The modules used to prepare OpenUpgrade are not commonly used by OU users that "just" migrate a DB or open some PR.
3. Sometimes you need to know some quirks found in openupgradelib itself.
4. To migrate a DB you usually need info from at least 2 Odoo versions.

Thus, I suggest that we have a specific OCA/openupgrade-docs repo, and docs go to the master branch.

When doing a migration, you might be migrating several versions at once. The setup should be the same across versions (at least 14+). Having docs for all of them at a glance would help. Version-specific stuff can be stored in folders named with those versions, or can be marked with https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-versionadded or https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-deprecated.

A github action can deploy it to GH pages, or we can use readthedocs.org, where you can even enable a PR check that builds a temporary browsable version of the altered docs in PRs.

It'd be nice to use mkdocs also, but maybe that's just too much. 😄

[StefanRijnhart]

Can't we just have gitbot that executes https://github.com/OCA/OpenUpgrade/blob/14.0/doc/fetch_coverage.sh? Then we can keep on updating the module status in the PR that adds the migration scripts.

[flotho]

Hi,
AFAICS, the latest documentation https://github.com/OCA/OpenUpgrade/blob/14.0/docsource/development.rst#learn-from-existing-migration-scrips don't reference correct folder.
In this repo openupgrade-framework and openupgrade_scripts ar located at the same level. Am I correct ? should I propose a correction?
Regards

[StefanRijnhart]

@flotho ah yes please do!

[flotho]

#2784

[tmotyl]

Any decision here? Is what @yajo proposed a way to go?

[StefanRijnhart]

Also here, I think most of the discussion is obsoleted by #2765, but correct me if I'm wrong @legalsylvain

[tmotyl]

thanks @StefanRijnhart