[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 Documentation Branch #3702 and validation. (April 28)

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

• April 30 : Initialization of the 'documentation' branch. [INIT] Initialize documentation branch #3837

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

• May, 1st : [REF] Switch to sphinx_rtd_theme [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 [REF] Refactor files that describes the branch. #3840

• May, 3 : [FIX] Do not ignore output path. (Fix 'View page source ' broken links) [DOC][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 : [REF] Remove docs from 16.0 branch #3853 + [ADD][16.0] New documentation workflow to update documentation website if the coverage changed #3855
  • 15.0 : 15.0 rem documentation #3859
  • 14.0 : [14.0][REM] documentation #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 : [REF] Remove openupgradelib API from the OpenUpgrade documentation #3863
  • openupgradelib PR : [FIX+ADD] openupgradelib documentation  openupgradelib#318 + [DOC] turn CI into red, if there are warning in sphinx call openupgradelib#324

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

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

• June, 21 :

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

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

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

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

• Write use Cases

  • July 29 (2022) : field renaming. [DOC] Add simple use case 'field renaming' #3493
  • May, 2 [ADD] An XML id was renamed [DOC-ADD] Use Case : XML_ID renaming #3844
  • May, 2: [ADD] mapping values [DOC-ADD] Use Case : 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) [ADD] Use Case : noupdate_xml_change #3864
  • May, 16: [ADD] A new stored, computed field needs to be populated using SQL to prevent a performance bottleneck. [DOC] Use case : field fast precomputation #3873
  • June, 1: [ADD] A model was renamed [DOC-ADD] Use Case : Model renaming #3901
  • May, 15: [ADD] A module was renamed (in Odoo or in the OCA) [DOC] use case : module renaming #3872
  • June, 13 : [ADD] A model has a new table [ADD] documentation : use case 'table renaming' #3914
  • June, 13 : [ADD] A sql constraint has been deleted. [ADD] documentation : Use case SQL Constraint deleted #3915
  • July, 3 : [ADD] new use case "module merging" [ADD] documentation : new use case "module merging" #4016
  • July, 30 [ADD] new use case "format of values changed" [ADD] Documentation use case format value changed #4102

• Skipped Use Cases

  • A module has been split. See [WIP][DOC] Use Case : add module splitted #3874 (comment)
  • 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 [DOC] 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.