[DOC] Follow-up of the redesign of the documentation

[legalsylvain]

this issue lists the changes made to the documentation. If you are interested by the documentation, please review issue / PRs that are marked as "To review".

CC @etobella, @bguillot, @hbrunn, @StefanRijnhart, @pedrobaeza

Note :

• the up to date documentation is available here
• a backup of the OCA documentation before refactoring is available here.

Already reviewed and merged

(Click to expand)

• January 25 : discussion about the interest of having a branch dedicated to documentation #3702 and validation. (April 28)

• April 29 : Issue about the broken documentation following the switch to the 16.0 branch : #3836

• April 30 : Initialization of the 'documentation' branch. #3837

• april, 30 : [FIX] Missing API references, for specific methods for openupgrade 12.0, 13.0 and 16.0 #3838

• May, 1st : [REF] Switch to sphinx_rtd_theme #3841

• May, 1st : [REF] Refactor files that describes the branch and add text that indicates how to develop the documentation locally #3840

• May, 3 : [FIX] Do not ignore output path. (Fix 'View page source ' broken links) #3849

• May, 7 : [REF] Remove docs folder and docsource folders (except coverage file) and related CI. + Update readme file in the recent openupgrade branches. (14.0, 15.0, 16.0). (see @pedrobaeza comment) + Update documentation when coverage files changed in "main" branches, for the branches :

  • 16.0 : #3853 + #3855
  • 15.0 : #3859
  • 14.0 : #3860

• May, 16 : [REF] Move openupgradelib API Section in openupgradelib documentation (and make openupgradelib documentation up to date, the last update was in 2015).

  • openupgrade PR : https://github.com/OCA/OpenUpgrade/pull/3863
  • openupgradelib PR : https://github.com/OCA/openupgradelib/pull/318 + https://github.com/OCA/openupgradelib/pull/324

• June, 1: Preliminary work : clean the intro part. #3902

• June, 1 : [REF] Documentation remove obsolete files #3903

• June, 21 :

  • [FIX] [10.0] modules coverage : remove title #3921
  • [12.0] modules coverage : remove title #3922
  • [13.0] modules coverage : remove title #3923

• June, 26 : [IMP] Refactor Introduction #3924

• August, 2 : [REF] Refactor of the structure #4103

• November, 7 : [ADD] required knowledge section #4217

• Write use Cases

  • July 29 (2022) : field renaming. #3493
  • May, 2 [ADD] An XML id was renamed #3844
  • May, 2: [ADD] mapping values #3845
  • May, 9: [ADD] A noupdate XML entry was updated, and the update must be loaded during the migration. (AND The updated field is translatable) #3864
  • May, 16: [ADD] A new stored, computed field needs to be populated using SQL to prevent a performance bottleneck. #3873
  • June, 1: [ADD] A model was renamed #3901
  • May, 15: [ADD] A module was renamed (in Odoo or in the OCA) #3872
  • June, 13 : [ADD] A model has a new table #3914
  • June, 13 : [ADD] A sql constraint has been deleted. #3915
  • July, 3 : [ADD] new use case "module merging" #4016
  • July, 30 [ADD] new use case "format of values changed" #4102

• Skipped Use Cases

  • A module has been split. See https://github.com/OCA/OpenUpgrade/pull/3874#issuecomment-1572925472
  • Two models were merged (e.g. invoice lines / move lines in Odoo 13) : Too complex, quite rare.
  • A model has been split (e.g. hr.leave.allocation in Odoo 12) : very rare case.

Done, to review / Pending work

• November, 9 : [ADD] Describe how to propose a migration script to the community #4227

[pedrobaeza]

You can remove in 16.0:

• The CI for building documentation.
• The doc folder.
• The documentation CI banner in the README.

[hussain]

Hopefully I'm part of this! I was preparing a group of documentation (draft) to be proposed and this subject is hot now in openupgrade, nice.

Just to check before I create a PR to documentation branch, are the attached files content is the expectation? any comments?

openupgrade_analysis.md verde_cleaning.md verde_upgrade.md env.txt

I believe many people want to contribute to OpenUpgrade, but they face hard learning curve. It is possible to increase contributions by providing quick starters, this is the intention of documentation revamp right? I myself took the journey to be in current state (intermediate in openupgrade) and contributors did help here and there, but it was not easy journey.

I would suggest having these areas in documentation:

• How to Setup Upgrade Environment This relates to good portion of reported issues.
• How to do Database Cleaning & Checks before Upgrade This is main reason for most reported issues (data issue, not openupgrade issue).
• Important Notes for each version post-upgrade activity i.e. successful upgrad to v14, set default_cash_difference_... in company before starting v15 upgrade.
• Common Issues List This can be list of common errors (version specific if true) either related to upgrade environment or data issue i.e.

  File "/usr/local/lib/python3.7/dist-packages/psycopg2/extensions.py", line 119, in getquoted
    return b'(' + b', '.join(qobjs) + b')'
MemoryError

this is related to python not having access to enough ram. ensure memory limits are good.

[legalsylvain]

hello Hussain, thank you for your interest in openupgrade and the documentation.

I believe many people want to contribute to OpenUpgrade, but they face hard learning curve. It is possible to increase contributions by providing quick starters, this is the intention of documentation revamp right?

totally !

For information, the work I am currently doing is part of an RFQ issued by the OCA in December.

So there is a list of tasks to do, mainly writing use cases, then other explanatory points, then, at the end, a reorganization of the documentation. (table of contents, general structure). This work is led by @etobella and @bguillot, in the OCA board. In this context, I would be of the opinion that I advance on this list of task, and once the work carried out (in 1 / 2 months), that we see if there are missing elements that you quoted and which are not covered. What do you think about it? In the meantime, feel free to read the opened PR (see first comment) and to review it.

Thank you!

[legalsylvain]

Off topic:

Maybe I should slow down the documentation refactors, I've been spotted. ;-)

[hussain]

For information, the work I am currently doing is part of an RFQ issued by the OCA in December.

Actually I landed somehow at that RFQ when I was roaming once the theme got changed, theme got me excited. So the RFQ is rewarded? I did not see any details in rewarded section, just my curiosity.

In this context, I would be of the opinion that I advance on this list of task, and once the work carried out (in 1 / 2 months), that we see if there are missing elements that you quoted and which are not covered. What do you think about it? In the meantime, feel free to read the opened PR (see first comment) and to review it.

Sound great. I checked with my team and management, we will be able to contribute one way or another in openupgrade, documentation is a key area that will allow us to do more.

[legalsylvain]

Actually I landed somehow at that RFQ when I was roaming once the theme got changed, theme got me excited. So the RFQ is rewarded? I did not see any details in rewarded section, just my curiosity.

Indeed, this page is not up to date. CC : @vdewulf

[vdewulf]

Hi, I asked Rebecca to take care of this update on the website. @legalsylvain

[rjg-odoonz]

Thanks for catching this team. All updated. We did share in our first newsletter/blog for the year as well: https://odoo-community.org/blog/news-updates-1/oca-newsletter-1-2023-136.