Archives
Contributors
-
Re: "The plan" to help non technical to contribute documentation on OCA modules
We've attempted to go this route ourselves, but have struggled to make our less technical users self-sufficient in tour creation. Is recording tours a new feature of a recent version of Odoo?On Wed, Dec 18, 2024 at 6:13 AM Graeme Gellatly <notifications@odoo-community.org> wrote:For me the fastest way to document most OCA modules AND have them apply across versions AND have them always current is to use tours which can now simply be recorded, exported, played and could apply per version, I am asking my team to do that for everything now. It not only has the benefit of allowing the user a guided how to of how to use the module, but it also becomes a test across versions and actually makes reviewing PR's easier. IOW, your documentation (tour in this case) becomes part of your test suite. Your test suite becomes part of documentation. Because every version would have its own tour, then you just need to click the version in whatever service/website. You can link whatever version to runboat to try the tour.
by Adam Heinz - 02:15 - 18 Dec 2024 -
Re: "The plan" to help non technical to contribute documentation on OCA modules
Thoughts on Documentation and Contribution Challenges
Hello everyone,
As a newcomer to this community, I wanted to share a bit of my perspective based on recent experiences. I’ve noticed that many Odoo CE instances are running offline (at least in my country), which makes relying on documentation hosted on a website less practical. While the current documentation has room for improvement, I’m concerned that "the plan" (if I understand it correctly) might make it even harder for developers to effectively work with the docs.
For example, I recently came across some really powerful modules (e.g., *_secondary_unit), but the lack of proper documentation significantly limits their potential audience. Features and constraints are introduced without much mention, which adds unnecessary hurdles for developers and users alike.
I also watched the video about contributing directly to OCA Documentation, and I have to admit it feels overly complicated for functional people. While reviewing the MVP, I could see that the pain points were identified correctly:
- Better addon discovery
- Better addon documentation
- Easier contribution to documentation
As someone who has recently submitted my first PRs (none merged yet, unfortunately 🙁), I have to say that the process is not very straightforward. Coding typically takes me 1-2 hours, but documenting often takes twice that time. That said, I’ve come to appreciate documentation because it helps me notice things I hadn’t considered initially.
I completely agree that we need to involve functional people in the process, but it feels like we might inadvertently be making it harder for the contributors we already have.
Thanks for listening, and I’m eager to hear your thoughts or advice!
Warm regards,
\rrebollo
---
On 12/17/24 10:58, Virginie Dewulf wrote:Hello everyone,
I wanted to share some news on this topic. As I asked in my latest email, some of you (Pedro and Jordi in particular) checked the plan and gave their feedback on Github on this specific task/issue (https://github.com/OCA/docs/issues/7). Thanks for taking the time to do so!
As the propose plan and its implications are being discussed and have a broad impact, I would like to bring back this discussion in this mailing list ("it is only fools who don't change their mind" ^^).
I would like to get more feedback from the community on this strategic topic. Many people got involved to make a minimum viable product, define the architecture of the plan, test the prototypes, etc. Let's make it work, together!
Here is the gathering of the current debate. Please, share with us what you think of this, identify what's missing and let's think of a way to proceed. Thanks!
Reminder: Goal of the project1. Allow consultants to update the documentation in a user-friendly tool2. Have a beautiful website with a good search features to find and read the OCA modules documentation, in order to share the values brought by the OCA modules, in the end having more contributors to maintain and create new OCA features.
Constraint of the project:
- being practical for consultant/functional profiles
- not adding too much burden to the current contributors (even though a bit of change might be required to make some space to the new profiles)- being reasonably easy to implement (in human-time and cost)
- being easy to maintain on the long run, as our usual infrastructure maintainers (mainly Stéphane Bidoul) have very little time available for that
- ideally, if new tools are added, other tools must go (cf. previous point), hence the idea of getting rid of the Odoo App Store on the OCA website
Proposed (technical) plan: see https://github.com/OCA/docs/issues/5 for the full picture.
Controversial points:A. the documentation of all the OCA modules will be visible on a dedicated website, that will in the end of the transition replace the current OCA App Store. The documentation itself will be stored in a dedicated Doc repository (https://github.com/OCA/docs) and be removed from the readmes of the modules (where a link to the dedicated website will be displayed).
B. there will be only one documentation page for all the versions of one module.
Current discussion regarding point A (move the doc from the readme to the Doc repo)Pros* unique source of truth in the Doc repo
* no synchronisation needed to maintain the doc updated in the readmes and in the Doc repo (syncs are very complex to implement and maintain because of the scale of the OCA infrastructure)
* this option makes point B possible: The README in a module is bound to the Odoo version it's built on. However, the docs site would have just a single version of the usage instructions. Counter-argument: create a synchronization mechanism between both systems (like with Weblate), not to strip out the contents in the source code
Cons
* Modules must be self-contained, and don't require to go to an external site (supposing you have public Internet connection and the site is up, which both are not guaranteed), to look for a basic module documentation.Counter argument: self-contained can perfectly mean that they contain a link to their docs site. For example, we already do that with license. We don't include it, but we put a link to it (in the modules; in repos we do copy it).
Current discussion regarding point B (one documentation across all the modules version)Pros* easier to manage for functional contributors* help people find and use OCA modules more easily (having one documentation with all the information is easier for that)
* From several consultant's experience, even if we actually have one Readme per version for a module now, the Readme is not updated from version to version. It is the same (most of the time) for all versions.Side Note: if a module has changes in the behavior in a version, the documentation should explain it. So you will have a section in the documentation (Context / Usage / Configuration) where you will explain from version x to version y, ... from version z ... The idea is to find everything at the same place and not having to go and compare versions to see the changes.
Cons* "active" versions of OCA modules are spanning about 4 versions (meaning: you can have someone employing v14 and someone on v18 at the same time), and it's very much possible some of these modules have gone through extensive refactoring in the meanwhile. How to provide accurate documentation for all versions, or prevent an "edit war" where both users are in the right? Counter-argument: we haven't seen any edit war to improve the modules documentation so far. If it's happen, it's a good sign. If the refactoring is important, the module will probably be renamed.
* Even Odoo doesn't do that with their documentation, which is "more controlled".* Risk of errors on the documentation that will confuse readers more than helping them.* "This is undoable. Each Odoo version has its own UI, colors, fields distribution... and the most important things: its features. Each OCA module, depending on the Odoo version, will behave different. But not only that, each OCA module version will have their different features depending how it evolves on each branch (normally, the latest version having more features than the previous ones, but that's not guaranteed). Having only one version of the docs for all is worst than the current situation." Counter-argument: if it's undoable in one unique document, why would this be doable in all readme for each versions? We know it's not the case right now so it won't be worst with the new plan.
* Risk of making the developer/semi-functional people's life worst with all these troubles
Attention point:
The 2 paths that we could see from here (sticking to the initial plan versus having one doc/version with a synchro) are not equivalent at all in term of feasibility and impact. Having a synchronisation for the doc cannot be done exactly as it is the case with Weblate because the synchro is one-way only (Weblate is the master of the translations). Here the synchro that is mentioned would require a synchro in both ways (from the PR's on the module's repo triggered by the technical contributors AND from the PR's on the Doc repo, triggered by the user-friendly tool to edit the doc for the consultants).
Last but not least:
Curious to see the current MVP in action?* the website with only one test module for now: https://oca-docs.netlify.app/* the CMS Decap access (login with your Github account): https://oca-docs.netlify.app/admin/* Florencia explains how to get started in this video: https://drive.google.com/file/d/1ZfBcicNdrssOnAWx7AKaYnM_tYIes4ID/view?usp=drive_link
Hoping to get more feedback, I wish you a happy end of the 2024 year!
Le mar. 10 déc. 2024 à 14:24, Virginie Dewulf <virginie@odoo-community.org> a écrit :
Hello,
This is a followup email for this email thread:
During the 2024 OCA Days, the OCA Consultants working group presented the status of the Documentation project: how to document OCA modules right now (using the Github workflow) with Julie and Florencia (video here: https://youtu.be/Kw0V_PdBUPg?feature=shared).
In parallel, a prototype of a new tool and process to easily document OCA modules has been proposed by Jairo Llopis, after discussion with Stéphane Bidoul to take into account the full picture of OCA infrastructure.
The goal of this new way of managing the documentation is two-fold:1. Allow consultants to update the documentation in a user-friendly tool2. Have a beautiful website with a good search features to find and read the OCA modules documentation
This will impact the way the documentation is managed in the OCA modules. In summary, the documentation of all the OCA modules will be visible on a dedicated website, that will in the end of the transition replace the current OCA App Store. The documentation itself will be stored in a dedicated Doc repository (https://github.com/OCA/docs) and be removed from the readmes of the modules (where a link to the dedicated website will be displayed). Finally, there will be only one documentation page for all the versions of one module.
The next steps are gathered in an issue on Github, called "the plan". Here it is:
To get more information about this, please check the link above. You can also read the latest meeting notes of the Consultants meeting held in November here: https://docs.google.com/document/d/1v23TwOwm9I7w3MNFZo-iCWQxVKedwoVzN9nEyflJVd8/edit?usp=sharing
If you want to share your feedback on this topic, I propose to keep it in the related issue on Github:
Thanks a lot to the consultants working group and especially to Jairo and Stéphane for their help! As you'll see in the plan, there are many "todo"s and help is always welcome.
All the best,
_______________________________________________
Mailing-List: https://odoo-community.org/groups/contributors-15
Post to: mailto:contributors@odoo-community.org
Unsubscribe: https://odoo-community.org/groups?unsubscribe
by Ing. Rolando Pérez Rebollo - 12:21 - 18 Dec 2024 -
Re: "The plan" to help non technical to contribute documentation on OCA modules
For me the fastest way to document most OCA modules AND have them apply across versions AND have them always current is to use tours which can now simply be recorded, exported, played and could apply per version, I am asking my team to do that for everything now. It not only has the benefit of allowing the user a guided how to of how to use the module, but it also becomes a test across versions and actually makes reviewing PR's easier. IOW, your documentation (tour in this case) becomes part of your test suite. Your test suite becomes part of documentation. Because every version would have its own tour, then you just need to click the version in whatever service/website. You can link whatever version to runboat to try the tour.In general, yes big changes do happen to modules, not often enough for me, but for the most part the problem they solve doesn't really change. In fact that is probably the bigger issue is when the problem they solve either no longer exists (qweb_mail_templates comes to mind, or product_variant_multi or numerous others) or now only exists in community.Obviously there is a technical jump from recording to exporting/committing/testing but it is fairly scriptable. I don't know, but I imagine because they are text based, they might also be translatable. Anyway I don't much care for the detail of where it is hosted etc for end users to access, but I really think tours are quick and will help keep documentation in sync with modules, and also help review.On Wed, Dec 18, 2024 at 2:42 PM Yoshi Tashiro <notifications@odoo-community.org> wrote:I find it hard to imagine that having one document per module would work nicely. For example, we split the sale_commission module into commission, account_commission and sale_commission modules as we did the migration from 14.0 to 15.0. Organizing the content coherently for before and after in one place for this case would be quite tricky.
What I imagine might work is to implement a non-technical process to let individuals who are not familiar with markdown editing or git create issues for improving the README with contents and images, and let whoever is familiar with markdown and git create corresponding pull requests.
For example:
- A non-technical person creates an issue with a title like "[README][15.0/16.0/17.0] web_responsive", and describes contents to be added/improved.
- A bot links the issue to the open PRs of web_responsive for the corresponding versions as a reminder.
- Contributors of the open PRs should try to incorporate the suggestions of the issue as appropriate.
- Otherwise, someone with the right skills creates a pull request to address the issue, using its contents.
I suppose this approach is user-friendly enough for consultants, and may work with proper guidelines. I am not sure about the implications for the goal of having a beautiful website, though.Best regards,--Yoshi TashiroOn Wed, Dec 18, 2024 at 12:58 AM Virginie Dewulf <virginie@odoo-community.org> wrote:Hello everyone,I wanted to share some news on this topic. As I asked in my latest email, some of you (Pedro and Jordi in particular) checked the plan and gave their feedback on Github on this specific task/issue (https://github.com/OCA/docs/issues/7). Thanks for taking the time to do so!As the propose plan and its implications are being discussed and have a broad impact, I would like to bring back this discussion in this mailing list ("it is only fools who don't change their mind" ^^).I would like to get more feedback from the community on this strategic topic. Many people got involved to make a minimum viable product, define the architecture of the plan, test the prototypes, etc. Let's make it work, together!Here is the gathering of the current debate. Please, share with us what you think of this, identify what's missing and let's think of a way to proceed. Thanks!Reminder: Goal of the project1. Allow consultants to update the documentation in a user-friendly tool2. Have a beautiful website with a good search features to find and read the OCA modules documentation, in order to share the values brought by the OCA modules, in the end having more contributors to maintain and create new OCA features.Constraint of the project:- being practical for consultant/functional profiles- not adding too much burden to the current contributors (even though a bit of change might be required to make some space to the new profiles)- being reasonably easy to implement (in human-time and cost)- being easy to maintain on the long run, as our usual infrastructure maintainers (mainly Stéphane Bidoul) have very little time available for that- ideally, if new tools are added, other tools must go (cf. previous point), hence the idea of getting rid of the Odoo App Store on the OCA websiteProposed (technical) plan: see https://github.com/OCA/docs/issues/5 for the full picture.Controversial points:A. the documentation of all the OCA modules will be visible on a dedicated website, that will in the end of the transition replace the current OCA App Store. The documentation itself will be stored in a dedicated Doc repository (https://github.com/OCA/docs) and be removed from the readmes of the modules (where a link to the dedicated website will be displayed).B. there will be only one documentation page for all the versions of one module.Current discussion regarding point A (move the doc from the readme to the Doc repo)Pros* unique source of truth in the Doc repo* no synchronisation needed to maintain the doc updated in the readmes and in the Doc repo (syncs are very complex to implement and maintain because of the scale of the OCA infrastructure)* this option makes point B possible: The README in a module is bound to the Odoo version it's built on. However, the docs site would have just a single version of the usage instructions. Counter-argument: create a synchronization mechanism between both systems (like with Weblate), not to strip out the contents in the source codeCons* Modules must be self-contained, and don't require to go to an external site (supposing you have public Internet connection and the site is up, which both are not guaranteed), to look for a basic module documentation.Counter argument: self-contained can perfectly mean that they contain a link to their docs site. For example, we already do that with license. We don't include it, but we put a link to it (in the modules; in repos we do copy it).Current discussion regarding point B (one documentation across all the modules version)Pros* easier to manage for functional contributors* help people find and use OCA modules more easily (having one documentation with all the information is easier for that)* From several consultant's experience, even if we actually have one Readme per version for a module now, the Readme is not updated from version to version. It is the same (most of the time) for all versions.Side Note: if a module has changes in the behavior in a version, the documentation should explain it. So you will have a section in the documentation (Context / Usage / Configuration) where you will explain from version x to version y, ... from version z ... The idea is to find everything at the same place and not having to go and compare versions to see the changes.Cons* "active" versions of OCA modules are spanning about 4 versions (meaning: you can have someone employing v14 and someone on v18 at the same time), and it's very much possible some of these modules have gone through extensive refactoring in the meanwhile. How to provide accurate documentation for all versions, or prevent an "edit war" where both users are in the right? Counter-argument: we haven't seen any edit war to improve the modules documentation so far. If it's happen, it's a good sign. If the refactoring is important, the module will probably be renamed.* Even Odoo doesn't do that with their documentation, which is "more controlled".* Risk of errors on the documentation that will confuse readers more than helping them.* "This is undoable. Each Odoo version has its own UI, colors, fields distribution... and the most important things: its features. Each OCA module, depending on the Odoo version, will behave different. But not only that, each OCA module version will have their different features depending how it evolves on each branch (normally, the latest version having more features than the previous ones, but that's not guaranteed). Having only one version of the docs for all is worst than the current situation." Counter-argument: if it's undoable in one unique document, why would this be doable in all readme for each versions? We know it's not the case right now so it won't be worst with the new plan.* Risk of making the developer/semi-functional people's life worst with all these troublesAttention point:
The 2 paths that we could see from here (sticking to the initial plan versus having one doc/version with a synchro) are not equivalent at all in term of feasibility and impact. Having a synchronisation for the doc cannot be done exactly as it is the case with Weblate because the synchro is one-way only (Weblate is the master of the translations). Here the synchro that is mentioned would require a synchro in both ways (from the PR's on the module's repo triggered by the technical contributors AND from the PR's on the Doc repo, triggered by the user-friendly tool to edit the doc for the consultants).
Last but not least:Curious to see the current MVP in action?* the website with only one test module for now: https://oca-docs.netlify.app/* the CMS Decap access (login with your Github account): https://oca-docs.netlify.app/admin/* Florencia explains how to get started in this video: https://drive.google.com/file/d/1ZfBcicNdrssOnAWx7AKaYnM_tYIes4ID/view?usp=drive_linkHoping to get more feedback, I wish you a happy end of the 2024 year!Le mar. 10 déc. 2024 à 14:24, Virginie Dewulf <virginie@odoo-community.org> a écrit :Hello,This is a followup email for this email thread:During the 2024 OCA Days, the OCA Consultants working group presented the status of the Documentation project: how to document OCA modules right now (using the Github workflow) with Julie and Florencia (video here: https://youtu.be/Kw0V_PdBUPg?feature=shared).In parallel, a prototype of a new tool and process to easily document OCA modules has been proposed by Jairo Llopis, after discussion with Stéphane Bidoul to take into account the full picture of OCA infrastructure.The goal of this new way of managing the documentation is two-fold:1. Allow consultants to update the documentation in a user-friendly tool2. Have a beautiful website with a good search features to find and read the OCA modules documentationThis will impact the way the documentation is managed in the OCA modules. In summary, the documentation of all the OCA modules will be visible on a dedicated website, that will in the end of the transition replace the current OCA App Store. The documentation itself will be stored in a dedicated Doc repository (https://github.com/OCA/docs) and be removed from the readmes of the modules (where a link to the dedicated website will be displayed). Finally, there will be only one documentation page for all the versions of one module.The next steps are gathered in an issue on Github, called "the plan". Here it is:To get more information about this, please check the link above. You can also read the latest meeting notes of the Consultants meeting held in November here: https://docs.google.com/document/d/1v23TwOwm9I7w3MNFZo-iCWQxVKedwoVzN9nEyflJVd8/edit?usp=sharingIf you want to share your feedback on this topic, I propose to keep it in the related issue on Github:Thanks a lot to the consultants working group and especially to Jairo and Stéphane for their help! As you'll see in the plan, there are many "todo"s and help is always welcome.All the best,_______________________________________________
Mailing-List: https://odoo-community.org/groups/contributors-15
Post to: mailto:contributors@odoo-community.org
Unsubscribe: https://odoo-community.org/groups?unsubscribe
_______________________________________________
Mailing-List: https://odoo-community.org/groups/contributors-15
Post to: mailto:contributors@odoo-community.org
Unsubscribe: https://odoo-community.org/groups?unsubscribe
by Graeme Gellatly - 12:11 - 18 Dec 2024 -
Re: "The plan" to help non technical to contribute documentation on OCA modules
On 12/17/24 18:07, Stefan Rijnhart wrote: > Keeping the module as a standalone entity is the gist for me too. +1 I think the right way to go here would be keep the single source of truth "with the module", and treat this the way we do translations: they are managed using an external UI and can bypass the regular process of PR's. This way, both technical and functional people can be happy. There just needs to be an alternate review process on the new-UI-side where people check if indeed the new documentation proposed is valid for all versions and people don't just blindly push new documentation to all versions.
by Tom Blauwendraat - 12:10 - 18 Dec 2024 -
Re: "The plan" to help non technical to contribute documentation on OCA modules
I find it hard to imagine that having one document per module would work nicely. For example, we split the sale_commission module into commission, account_commission and sale_commission modules as we did the migration from 14.0 to 15.0. Organizing the content coherently for before and after in one place for this case would be quite tricky.
What I imagine might work is to implement a non-technical process to let individuals who are not familiar with markdown editing or git create issues for improving the README with contents and images, and let whoever is familiar with markdown and git create corresponding pull requests.
For example:
- A non-technical person creates an issue with a title like "[README][15.0/16.0/17.0] web_responsive", and describes contents to be added/improved.
- A bot links the issue to the open PRs of web_responsive for the corresponding versions as a reminder.
- Contributors of the open PRs should try to incorporate the suggestions of the issue as appropriate.
- Otherwise, someone with the right skills creates a pull request to address the issue, using its contents.
I suppose this approach is user-friendly enough for consultants, and may work with proper guidelines. I am not sure about the implications for the goal of having a beautiful website, though.Best regards,--Yoshi TashiroOn Wed, Dec 18, 2024 at 12:58 AM Virginie Dewulf <virginie@odoo-community.org> wrote:Hello everyone,I wanted to share some news on this topic. As I asked in my latest email, some of you (Pedro and Jordi in particular) checked the plan and gave their feedback on Github on this specific task/issue (https://github.com/OCA/docs/issues/7). Thanks for taking the time to do so!As the propose plan and its implications are being discussed and have a broad impact, I would like to bring back this discussion in this mailing list ("it is only fools who don't change their mind" ^^).I would like to get more feedback from the community on this strategic topic. Many people got involved to make a minimum viable product, define the architecture of the plan, test the prototypes, etc. Let's make it work, together!Here is the gathering of the current debate. Please, share with us what you think of this, identify what's missing and let's think of a way to proceed. Thanks!Reminder: Goal of the project1. Allow consultants to update the documentation in a user-friendly tool2. Have a beautiful website with a good search features to find and read the OCA modules documentation, in order to share the values brought by the OCA modules, in the end having more contributors to maintain and create new OCA features.Constraint of the project:- being practical for consultant/functional profiles- not adding too much burden to the current contributors (even though a bit of change might be required to make some space to the new profiles)- being reasonably easy to implement (in human-time and cost)- being easy to maintain on the long run, as our usual infrastructure maintainers (mainly Stéphane Bidoul) have very little time available for that- ideally, if new tools are added, other tools must go (cf. previous point), hence the idea of getting rid of the Odoo App Store on the OCA websiteProposed (technical) plan: see https://github.com/OCA/docs/issues/5 for the full picture.Controversial points:A. the documentation of all the OCA modules will be visible on a dedicated website, that will in the end of the transition replace the current OCA App Store. The documentation itself will be stored in a dedicated Doc repository (https://github.com/OCA/docs) and be removed from the readmes of the modules (where a link to the dedicated website will be displayed).B. there will be only one documentation page for all the versions of one module.Current discussion regarding point A (move the doc from the readme to the Doc repo)Pros* unique source of truth in the Doc repo* no synchronisation needed to maintain the doc updated in the readmes and in the Doc repo (syncs are very complex to implement and maintain because of the scale of the OCA infrastructure)* this option makes point B possible: The README in a module is bound to the Odoo version it's built on. However, the docs site would have just a single version of the usage instructions. Counter-argument: create a synchronization mechanism between both systems (like with Weblate), not to strip out the contents in the source codeCons* Modules must be self-contained, and don't require to go to an external site (supposing you have public Internet connection and the site is up, which both are not guaranteed), to look for a basic module documentation.Counter argument: self-contained can perfectly mean that they contain a link to their docs site. For example, we already do that with license. We don't include it, but we put a link to it (in the modules; in repos we do copy it).Current discussion regarding point B (one documentation across all the modules version)Pros* easier to manage for functional contributors* help people find and use OCA modules more easily (having one documentation with all the information is easier for that)* From several consultant's experience, even if we actually have one Readme per version for a module now, the Readme is not updated from version to version. It is the same (most of the time) for all versions.Side Note: if a module has changes in the behavior in a version, the documentation should explain it. So you will have a section in the documentation (Context / Usage / Configuration) where you will explain from version x to version y, ... from version z ... The idea is to find everything at the same place and not having to go and compare versions to see the changes.Cons* "active" versions of OCA modules are spanning about 4 versions (meaning: you can have someone employing v14 and someone on v18 at the same time), and it's very much possible some of these modules have gone through extensive refactoring in the meanwhile. How to provide accurate documentation for all versions, or prevent an "edit war" where both users are in the right? Counter-argument: we haven't seen any edit war to improve the modules documentation so far. If it's happen, it's a good sign. If the refactoring is important, the module will probably be renamed.* Even Odoo doesn't do that with their documentation, which is "more controlled".* Risk of errors on the documentation that will confuse readers more than helping them.* "This is undoable. Each Odoo version has its own UI, colors, fields distribution... and the most important things: its features. Each OCA module, depending on the Odoo version, will behave different. But not only that, each OCA module version will have their different features depending how it evolves on each branch (normally, the latest version having more features than the previous ones, but that's not guaranteed). Having only one version of the docs for all is worst than the current situation." Counter-argument: if it's undoable in one unique document, why would this be doable in all readme for each versions? We know it's not the case right now so it won't be worst with the new plan.* Risk of making the developer/semi-functional people's life worst with all these troublesAttention point:
The 2 paths that we could see from here (sticking to the initial plan versus having one doc/version with a synchro) are not equivalent at all in term of feasibility and impact. Having a synchronisation for the doc cannot be done exactly as it is the case with Weblate because the synchro is one-way only (Weblate is the master of the translations). Here the synchro that is mentioned would require a synchro in both ways (from the PR's on the module's repo triggered by the technical contributors AND from the PR's on the Doc repo, triggered by the user-friendly tool to edit the doc for the consultants).
Last but not least:Curious to see the current MVP in action?* the website with only one test module for now: https://oca-docs.netlify.app/* the CMS Decap access (login with your Github account): https://oca-docs.netlify.app/admin/* Florencia explains how to get started in this video: https://drive.google.com/file/d/1ZfBcicNdrssOnAWx7AKaYnM_tYIes4ID/view?usp=drive_linkHoping to get more feedback, I wish you a happy end of the 2024 year!Le mar. 10 déc. 2024 à 14:24, Virginie Dewulf <virginie@odoo-community.org> a écrit :Hello,This is a followup email for this email thread:During the 2024 OCA Days, the OCA Consultants working group presented the status of the Documentation project: how to document OCA modules right now (using the Github workflow) with Julie and Florencia (video here: https://youtu.be/Kw0V_PdBUPg?feature=shared).In parallel, a prototype of a new tool and process to easily document OCA modules has been proposed by Jairo Llopis, after discussion with Stéphane Bidoul to take into account the full picture of OCA infrastructure.The goal of this new way of managing the documentation is two-fold:1. Allow consultants to update the documentation in a user-friendly tool2. Have a beautiful website with a good search features to find and read the OCA modules documentationThis will impact the way the documentation is managed in the OCA modules. In summary, the documentation of all the OCA modules will be visible on a dedicated website, that will in the end of the transition replace the current OCA App Store. The documentation itself will be stored in a dedicated Doc repository (https://github.com/OCA/docs) and be removed from the readmes of the modules (where a link to the dedicated website will be displayed). Finally, there will be only one documentation page for all the versions of one module.The next steps are gathered in an issue on Github, called "the plan". Here it is:To get more information about this, please check the link above. You can also read the latest meeting notes of the Consultants meeting held in November here: https://docs.google.com/document/d/1v23TwOwm9I7w3MNFZo-iCWQxVKedwoVzN9nEyflJVd8/edit?usp=sharingIf you want to share your feedback on this topic, I propose to keep it in the related issue on Github:Thanks a lot to the consultants working group and especially to Jairo and Stéphane for their help! As you'll see in the plan, there are many "todo"s and help is always welcome.All the best,_______________________________________________
Mailing-List: https://odoo-community.org/groups/contributors-15
Post to: mailto:contributors@odoo-community.org
Unsubscribe: https://odoo-community.org/groups?unsubscribe
by Yoshi Tashiro. - 02:41 - 18 Dec 2024 -
Re: [SPAM] Sync odoo's calendar smartphones without Google nor Outlook
Thanks Xavier--------------------------------
Cyril VINH-TUNG
INVITU
Computer & Network Engineering
BP 32 - 98713 Papeete - French Polynesia
Tél: +689 40 46 11 99
contact@invitu.com
www.invitu.comLe mar. 17 déc. 2024, 02:07, Xavier Brochard <notifications@odoo-community.org> a écrit :Hello Cyril There is an easy solution with vdirsyncer and a caldav/carddav server (like Nextcloud Agenda for instance). It's a bit «hacky» but works very well for me and my few employees. See https://vdirsyncer.pimutils.org/ The sync is as follow Odoo <=> Google/Outlook <=> vdirsyncer <=> Caldav server <=> any client If you need more details, just ask (je parle français). Another solution is to use a fake or compatible free/libre Outlook server (at least one exist). Xavier Le mardi 17 décembre 2024, 10:32:50 CET hugues de keyzer a écrit : > Le 2024-12-14 à 20:39, Cyril VINH-TUNG > Does anybody manage to sync odoo's calendar > without Google/outlook ? > > Actually I tried Myodoo that has bugs and I'm > going to try the old z-push odoo's backend > https://github.com/funbaker/odoozpush [8]
_______________________________________________
Mailing-List: https://odoo-community.org/groups/contributors-15
Post to: mailto:contributors@odoo-community.org
Unsubscribe: https://odoo-community.org/groups?unsubscribe
by Cyril VINH-TUNG - 06:26 - 17 Dec 2024 -
Re: [SPAM] Sync odoo's calendar smartphones without Google nor Outlook
Thanks Hugues--------------------------------
Cyril VINH-TUNG
INVITU
Computer & Network Engineering
BP 32 - 98713 Papeete - French Polynesia
Tél: +689 40 46 11 99
contact@invitu.com
www.invitu.comLe lun. 16 déc. 2024, 23:32, hugues de keyzer <notifications@odoo-community.org> a écrit :hello,
you might take a look at the base_dav and calendar_dav modules, which provide caldav access to odoo’s calendar. unfortunately, the last available version is for odoo 11, because the migration has been blocked by the discussion whether to update the radicale library (on which base_dav depends) or not.
some links:
- 12.0 mig base_dav #141
- [12.0][MIG] base_dav: migration to 12.0 #226
- base_dav dead? #254
- [MIG] base_dav: Migration to 17.0 #269
- [MIG] base_dav: Migration to 17.0 #276
feel free to help move this forward, that would be useful.
kind regards,
hugues
Le 2024-12-14 à 20:39, Cyril VINH-TUNG a écrit :
Dear all
Does anybody manage to sync odoo's calendar without Google/outlook ?
Actually I tried Myodoo that has bugs and I'm going to try the old z-push odoo's backend https://github.com/funbaker/odoozpush
Thanks and have a great weekend
--------------------------------
Cyril VINH-TUNG
INVITU
Computer & Network Engineering
BP 32 - 98713 Papeete - French Polynesia
Tél: +689 40 46 11 99
contact@invitu.com
www.invitu.com_______________________________________________
Mailing-List: https://odoo-community.org/groups/contributors-15
Post to: mailto:contributors@odoo-community.org
Unsubscribe: https://odoo-community.org/groups?unsubscribe
_______________________________________________
Mailing-List: https://odoo-community.org/groups/contributors-15
Post to: mailto:contributors@odoo-community.org
Unsubscribe: https://odoo-community.org/groups?unsubscribe
by Cyril VINH-TUNG - 06:21 - 17 Dec 2024 -
Re: "The plan" to help non technical to contribute documentation on OCA modules
Hi,
Keeping the module as a standalone entity is the gist for me too. The modules are not going to look very good on the Odoo apps store with only a non clickable link instead of the full docs. Not being able to add the documentation in the original PR, like other people already said, is going to lead to missing documentation for new modules. Also, I personally appreciate that documentation when I review a PR for a new module, and I might not be the only one so it might interfere with the review process as well.
Cheers,
Stefan
On 17-12-2024 16:58, Virginie Dewulf wrote:
Hello everyone,
I wanted to share some news on this topic. As I asked in my latest email, some of you (Pedro and Jordi in particular) checked the plan and gave their feedback on Github on this specific task/issue (https://github.com/OCA/docs/issues/7). Thanks for taking the time to do so!
As the propose plan and its implications are being discussed and have a broad impact, I would like to bring back this discussion in this mailing list ("it is only fools who don't change their mind" ^^).
I would like to get more feedback from the community on this strategic topic. Many people got involved to make a minimum viable product, define the architecture of the plan, test the prototypes, etc. Let's make it work, together!
Here is the gathering of the current debate. Please, share with us what you think of this, identify what's missing and let's think of a way to proceed. Thanks!
Reminder: Goal of the project1. Allow consultants to update the documentation in a user-friendly tool2. Have a beautiful website with a good search features to find and read the OCA modules documentation, in order to share the values brought by the OCA modules, in the end having more contributors to maintain and create new OCA features.
Constraint of the project:
- being practical for consultant/functional profiles
- not adding too much burden to the current contributors (even though a bit of change might be required to make some space to the new profiles)- being reasonably easy to implement (in human-time and cost)
- being easy to maintain on the long run, as our usual infrastructure maintainers (mainly Stéphane Bidoul) have very little time available for that
- ideally, if new tools are added, other tools must go (cf. previous point), hence the idea of getting rid of the Odoo App Store on the OCA website
Proposed (technical) plan: see https://github.com/OCA/docs/issues/5 for the full picture.
Controversial points:A. the documentation of all the OCA modules will be visible on a dedicated website, that will in the end of the transition replace the current OCA App Store. The documentation itself will be stored in a dedicated Doc repository (https://github.com/OCA/docs) and be removed from the readmes of the modules (where a link to the dedicated website will be displayed).
B. there will be only one documentation page for all the versions of one module.
Current discussion regarding point A (move the doc from the readme to the Doc repo)Pros* unique source of truth in the Doc repo
* no synchronisation needed to maintain the doc updated in the readmes and in the Doc repo (syncs are very complex to implement and maintain because of the scale of the OCA infrastructure)
* this option makes point B possible: The README in a module is bound to the Odoo version it's built on. However, the docs site would have just a single version of the usage instructions. Counter-argument: create a synchronization mechanism between both systems (like with Weblate), not to strip out the contents in the source code
Cons
* Modules must be self-contained, and don't require to go to an external site (supposing you have public Internet connection and the site is up, which both are not guaranteed), to look for a basic module documentation.Counter argument: self-contained can perfectly mean that they contain a link to their docs site. For example, we already do that with license. We don't include it, but we put a link to it (in the modules; in repos we do copy it).
Current discussion regarding point B (one documentation across all the modules version)Pros* easier to manage for functional contributors* help people find and use OCA modules more easily (having one documentation with all the information is easier for that)
* From several consultant's experience, even if we actually have one Readme per version for a module now, the Readme is not updated from version to version. It is the same (most of the time) for all versions.Side Note: if a module has changes in the behavior in a version, the documentation should explain it. So you will have a section in the documentation (Context / Usage / Configuration) where you will explain from version x to version y, ... from version z ... The idea is to find everything at the same place and not having to go and compare versions to see the changes.
Cons* "active" versions of OCA modules are spanning about 4 versions (meaning: you can have someone employing v14 and someone on v18 at the same time), and it's very much possible some of these modules have gone through extensive refactoring in the meanwhile. How to provide accurate documentation for all versions, or prevent an "edit war" where both users are in the right? Counter-argument: we haven't seen any edit war to improve the modules documentation so far. If it's happen, it's a good sign. If the refactoring is important, the module will probably be renamed.
* Even Odoo doesn't do that with their documentation, which is "more controlled".* Risk of errors on the documentation that will confuse readers more than helping them.* "This is undoable. Each Odoo version has its own UI, colors, fields distribution... and the most important things: its features. Each OCA module, depending on the Odoo version, will behave different. But not only that, each OCA module version will have their different features depending how it evolves on each branch (normally, the latest version having more features than the previous ones, but that's not guaranteed). Having only one version of the docs for all is worst than the current situation." Counter-argument: if it's undoable in one unique document, why would this be doable in all readme for each versions? We know it's not the case right now so it won't be worst with the new plan.
* Risk of making the developer/semi-functional people's life worst with all these troubles
Attention point:
The 2 paths that we could see from here (sticking to the initial plan versus having one doc/version with a synchro) are not equivalent at all in term of feasibility and impact. Having a synchronisation for the doc cannot be done exactly as it is the case with Weblate because the synchro is one-way only (Weblate is the master of the translations). Here the synchro that is mentioned would require a synchro in both ways (from the PR's on the module's repo triggered by the technical contributors AND from the PR's on the Doc repo, triggered by the user-friendly tool to edit the doc for the consultants).
Last but not least:
Curious to see the current MVP in action?* the website with only one test module for now: https://oca-docs.netlify.app/* the CMS Decap access (login with your Github account): https://oca-docs.netlify.app/admin/* Florencia explains how to get started in this video: https://drive.google.com/file/d/1ZfBcicNdrssOnAWx7AKaYnM_tYIes4ID/view?usp=drive_link
Hoping to get more feedback, I wish you a happy end of the 2024 year!
Le mar. 10 déc. 2024 à 14:24, Virginie Dewulf <virginie@odoo-community.org> a écrit :
Hello,
This is a followup email for this email thread:
During the 2024 OCA Days, the OCA Consultants working group presented the status of the Documentation project: how to document OCA modules right now (using the Github workflow) with Julie and Florencia (video here: https://youtu.be/Kw0V_PdBUPg?feature=shared).
In parallel, a prototype of a new tool and process to easily document OCA modules has been proposed by Jairo Llopis, after discussion with Stéphane Bidoul to take into account the full picture of OCA infrastructure.
The goal of this new way of managing the documentation is two-fold:1. Allow consultants to update the documentation in a user-friendly tool2. Have a beautiful website with a good search features to find and read the OCA modules documentation
This will impact the way the documentation is managed in the OCA modules. In summary, the documentation of all the OCA modules will be visible on a dedicated website, that will in the end of the transition replace the current OCA App Store. The documentation itself will be stored in a dedicated Doc repository (https://github.com/OCA/docs) and be removed from the readmes of the modules (where a link to the dedicated website will be displayed). Finally, there will be only one documentation page for all the versions of one module.
The next steps are gathered in an issue on Github, called "the plan". Here it is:
To get more information about this, please check the link above. You can also read the latest meeting notes of the Consultants meeting held in November here: https://docs.google.com/document/d/1v23TwOwm9I7w3MNFZo-iCWQxVKedwoVzN9nEyflJVd8/edit?usp=sharing
If you want to share your feedback on this topic, I propose to keep it in the related issue on Github:
Thanks a lot to the consultants working group and especially to Jairo and Stéphane for their help! As you'll see in the plan, there are many "todo"s and help is always welcome.
All the best,
_______________________________________________
Mailing-List: https://odoo-community.org/groups/contributors-15
Post to: mailto:contributors@odoo-community.org
Unsubscribe: https://odoo-community.org/groups?unsubscribe
-- Opener B.V. - Business solutions driven by open source collaboration Stefan Rijnhart - Consultant/developer mail: stefan@opener.amsterdam tel: +31 (0) 6 1447 8606 web: https://opener.amsterdam
by Stefan Rijnhart - 06:06 - 17 Dec 2024 -
Re: "The plan" to help non technical to contribute documentation on OCA modules
Hi,
For me ignoring the odoo version doesn't look like a good idea, it may be Ok for 90% of the modules in a range of 2 versions (let's say 16-18), but as the range expands and more changes are applied to more core applications (imagine 16-25), maybe it is only a good idea for 30% of the modules that luckily were almost unchanged during all these versions. I don't see how a document with a lot of notes like "do this in versions from 16 to 17 and this other thing from 18 to 21 and then do this other thing from 22" will benefit anyone in the long term.From my PoV, Odoo itself did it right with the version selector at the top right of the documentation website. We all know that some of the pages are pushed to the next version and not fully updated to be aligned with the new version, but at least the big changes are reflected and I can look at a specific version documentation with no noise.Also, having to do two pull requests to update code and another to update documentation (yes, many technical people update documentation) can lead to the second one (documentation one) being avoided. What I mean is that we would probably need a good mechanism to reinforce the documentation update linked to a feature change if we go that path...My 2 cents.Kind regards,On Tue, Dec 17, 2024 at 4:58 PM Virginie Dewulf <virginie@odoo-community.org> wrote:Hello everyone,I wanted to share some news on this topic. As I asked in my latest email, some of you (Pedro and Jordi in particular) checked the plan and gave their feedback on Github on this specific task/issue (https://github.com/OCA/docs/issues/7). Thanks for taking the time to do so!As the propose plan and its implications are being discussed and have a broad impact, I would like to bring back this discussion in this mailing list ("it is only fools who don't change their mind" ^^).I would like to get more feedback from the community on this strategic topic. Many people got involved to make a minimum viable product, define the architecture of the plan, test the prototypes, etc. Let's make it work, together!Here is the gathering of the current debate. Please, share with us what you think of this, identify what's missing and let's think of a way to proceed. Thanks!Reminder: Goal of the project1. Allow consultants to update the documentation in a user-friendly tool2. Have a beautiful website with a good search features to find and read the OCA modules documentation, in order to share the values brought by the OCA modules, in the end having more contributors to maintain and create new OCA features.Constraint of the project:- being practical for consultant/functional profiles- not adding too much burden to the current contributors (even though a bit of change might be required to make some space to the new profiles)- being reasonably easy to implement (in human-time and cost)- being easy to maintain on the long run, as our usual infrastructure maintainers (mainly Stéphane Bidoul) have very little time available for that- ideally, if new tools are added, other tools must go (cf. previous point), hence the idea of getting rid of the Odoo App Store on the OCA websiteProposed (technical) plan: see https://github.com/OCA/docs/issues/5 for the full picture.Controversial points:A. the documentation of all the OCA modules will be visible on a dedicated website, that will in the end of the transition replace the current OCA App Store. The documentation itself will be stored in a dedicated Doc repository (https://github.com/OCA/docs) and be removed from the readmes of the modules (where a link to the dedicated website will be displayed).B. there will be only one documentation page for all the versions of one module.Current discussion regarding point A (move the doc from the readme to the Doc repo)Pros* unique source of truth in the Doc repo* no synchronisation needed to maintain the doc updated in the readmes and in the Doc repo (syncs are very complex to implement and maintain because of the scale of the OCA infrastructure)* this option makes point B possible: The README in a module is bound to the Odoo version it's built on. However, the docs site would have just a single version of the usage instructions. Counter-argument: create a synchronization mechanism between both systems (like with Weblate), not to strip out the contents in the source codeCons* Modules must be self-contained, and don't require to go to an external site (supposing you have public Internet connection and the site is up, which both are not guaranteed), to look for a basic module documentation.Counter argument: self-contained can perfectly mean that they contain a link to their docs site. For example, we already do that with license. We don't include it, but we put a link to it (in the modules; in repos we do copy it).Current discussion regarding point B (one documentation across all the modules version)Pros* easier to manage for functional contributors* help people find and use OCA modules more easily (having one documentation with all the information is easier for that)* From several consultant's experience, even if we actually have one Readme per version for a module now, the Readme is not updated from version to version. It is the same (most of the time) for all versions.Side Note: if a module has changes in the behavior in a version, the documentation should explain it. So you will have a section in the documentation (Context / Usage / Configuration) where you will explain from version x to version y, ... from version z ... The idea is to find everything at the same place and not having to go and compare versions to see the changes.Cons* "active" versions of OCA modules are spanning about 4 versions (meaning: you can have someone employing v14 and someone on v18 at the same time), and it's very much possible some of these modules have gone through extensive refactoring in the meanwhile. How to provide accurate documentation for all versions, or prevent an "edit war" where both users are in the right? Counter-argument: we haven't seen any edit war to improve the modules documentation so far. If it's happen, it's a good sign. If the refactoring is important, the module will probably be renamed.* Even Odoo doesn't do that with their documentation, which is "more controlled".* Risk of errors on the documentation that will confuse readers more than helping them.* "This is undoable. Each Odoo version has its own UI, colors, fields distribution... and the most important things: its features. Each OCA module, depending on the Odoo version, will behave different. But not only that, each OCA module version will have their different features depending how it evolves on each branch (normally, the latest version having more features than the previous ones, but that's not guaranteed). Having only one version of the docs for all is worst than the current situation." Counter-argument: if it's undoable in one unique document, why would this be doable in all readme for each versions? We know it's not the case right now so it won't be worst with the new plan.* Risk of making the developer/semi-functional people's life worst with all these troublesAttention point:
The 2 paths that we could see from here (sticking to the initial plan versus having one doc/version with a synchro) are not equivalent at all in term of feasibility and impact. Having a synchronisation for the doc cannot be done exactly as it is the case with Weblate because the synchro is one-way only (Weblate is the master of the translations). Here the synchro that is mentioned would require a synchro in both ways (from the PR's on the module's repo triggered by the technical contributors AND from the PR's on the Doc repo, triggered by the user-friendly tool to edit the doc for the consultants).
Last but not least:Curious to see the current MVP in action?* the website with only one test module for now: https://oca-docs.netlify.app/* the CMS Decap access (login with your Github account): https://oca-docs.netlify.app/admin/* Florencia explains how to get started in this video: https://drive.google.com/file/d/1ZfBcicNdrssOnAWx7AKaYnM_tYIes4ID/view?usp=drive_linkHoping to get more feedback, I wish you a happy end of the 2024 year!Le mar. 10 déc. 2024 à 14:24, Virginie Dewulf <virginie@odoo-community.org> a écrit :Hello,This is a followup email for this email thread:During the 2024 OCA Days, the OCA Consultants working group presented the status of the Documentation project: how to document OCA modules right now (using the Github workflow) with Julie and Florencia (video here: https://youtu.be/Kw0V_PdBUPg?feature=shared).In parallel, a prototype of a new tool and process to easily document OCA modules has been proposed by Jairo Llopis, after discussion with Stéphane Bidoul to take into account the full picture of OCA infrastructure.The goal of this new way of managing the documentation is two-fold:1. Allow consultants to update the documentation in a user-friendly tool2. Have a beautiful website with a good search features to find and read the OCA modules documentationThis will impact the way the documentation is managed in the OCA modules. In summary, the documentation of all the OCA modules will be visible on a dedicated website, that will in the end of the transition replace the current OCA App Store. The documentation itself will be stored in a dedicated Doc repository (https://github.com/OCA/docs) and be removed from the readmes of the modules (where a link to the dedicated website will be displayed). Finally, there will be only one documentation page for all the versions of one module.The next steps are gathered in an issue on Github, called "the plan". Here it is:To get more information about this, please check the link above. You can also read the latest meeting notes of the Consultants meeting held in November here: https://docs.google.com/document/d/1v23TwOwm9I7w3MNFZo-iCWQxVKedwoVzN9nEyflJVd8/edit?usp=sharingIf you want to share your feedback on this topic, I propose to keep it in the related issue on Github:Thanks a lot to the consultants working group and especially to Jairo and Stéphane for their help! As you'll see in the plan, there are many "todo"s and help is always welcome.All the best,_______________________________________________
Mailing-List: https://odoo-community.org/groups/contributors-15
Post to: mailto:contributors@odoo-community.org
Unsubscribe: https://odoo-community.org/groups?unsubscribe
--Lois Rilo AnteloERP Consultant Manager at ForgeFlow S.L.
by Lois Rilo Antelo - 05:46 - 17 Dec 2024 -
Re: "The plan" to help non technical to contribute documentation on OCA modules
Hello everyone,I wanted to share some news on this topic. As I asked in my latest email, some of you (Pedro and Jordi in particular) checked the plan and gave their feedback on Github on this specific task/issue (https://github.com/OCA/docs/issues/7). Thanks for taking the time to do so!As the propose plan and its implications are being discussed and have a broad impact, I would like to bring back this discussion in this mailing list ("it is only fools who don't change their mind" ^^).I would like to get more feedback from the community on this strategic topic. Many people got involved to make a minimum viable product, define the architecture of the plan, test the prototypes, etc. Let's make it work, together!Here is the gathering of the current debate. Please, share with us what you think of this, identify what's missing and let's think of a way to proceed. Thanks!Reminder: Goal of the project1. Allow consultants to update the documentation in a user-friendly tool2. Have a beautiful website with a good search features to find and read the OCA modules documentation, in order to share the values brought by the OCA modules, in the end having more contributors to maintain and create new OCA features.Constraint of the project:- being practical for consultant/functional profiles- not adding too much burden to the current contributors (even though a bit of change might be required to make some space to the new profiles)- being reasonably easy to implement (in human-time and cost)- being easy to maintain on the long run, as our usual infrastructure maintainers (mainly Stéphane Bidoul) have very little time available for that- ideally, if new tools are added, other tools must go (cf. previous point), hence the idea of getting rid of the Odoo App Store on the OCA websiteProposed (technical) plan: see https://github.com/OCA/docs/issues/5 for the full picture.Controversial points:A. the documentation of all the OCA modules will be visible on a dedicated website, that will in the end of the transition replace the current OCA App Store. The documentation itself will be stored in a dedicated Doc repository (https://github.com/OCA/docs) and be removed from the readmes of the modules (where a link to the dedicated website will be displayed).B. there will be only one documentation page for all the versions of one module.Current discussion regarding point A (move the doc from the readme to the Doc repo)Pros* unique source of truth in the Doc repo* no synchronisation needed to maintain the doc updated in the readmes and in the Doc repo (syncs are very complex to implement and maintain because of the scale of the OCA infrastructure)* this option makes point B possible: The README in a module is bound to the Odoo version it's built on. However, the docs site would have just a single version of the usage instructions. Counter-argument: create a synchronization mechanism between both systems (like with Weblate), not to strip out the contents in the source codeCons* Modules must be self-contained, and don't require to go to an external site (supposing you have public Internet connection and the site is up, which both are not guaranteed), to look for a basic module documentation.Counter argument: self-contained can perfectly mean that they contain a link to their docs site. For example, we already do that with license. We don't include it, but we put a link to it (in the modules; in repos we do copy it).Current discussion regarding point B (one documentation across all the modules version)Pros* easier to manage for functional contributors* help people find and use OCA modules more easily (having one documentation with all the information is easier for that)* From several consultant's experience, even if we actually have one Readme per version for a module now, the Readme is not updated from version to version. It is the same (most of the time) for all versions.Side Note: if a module has changes in the behavior in a version, the documentation should explain it. So you will have a section in the documentation (Context / Usage / Configuration) where you will explain from version x to version y, ... from version z ... The idea is to find everything at the same place and not having to go and compare versions to see the changes.Cons* "active" versions of OCA modules are spanning about 4 versions (meaning: you can have someone employing v14 and someone on v18 at the same time), and it's very much possible some of these modules have gone through extensive refactoring in the meanwhile. How to provide accurate documentation for all versions, or prevent an "edit war" where both users are in the right? Counter-argument: we haven't seen any edit war to improve the modules documentation so far. If it's happen, it's a good sign. If the refactoring is important, the module will probably be renamed.* Even Odoo doesn't do that with their documentation, which is "more controlled".* Risk of errors on the documentation that will confuse readers more than helping them.* "This is undoable. Each Odoo version has its own UI, colors, fields distribution... and the most important things: its features. Each OCA module, depending on the Odoo version, will behave different. But not only that, each OCA module version will have their different features depending how it evolves on each branch (normally, the latest version having more features than the previous ones, but that's not guaranteed). Having only one version of the docs for all is worst than the current situation." Counter-argument: if it's undoable in one unique document, why would this be doable in all readme for each versions? We know it's not the case right now so it won't be worst with the new plan.* Risk of making the developer/semi-functional people's life worst with all these troublesAttention point:
The 2 paths that we could see from here (sticking to the initial plan versus having one doc/version with a synchro) are not equivalent at all in term of feasibility and impact. Having a synchronisation for the doc cannot be done exactly as it is the case with Weblate because the synchro is one-way only (Weblate is the master of the translations). Here the synchro that is mentioned would require a synchro in both ways (from the PR's on the module's repo triggered by the technical contributors AND from the PR's on the Doc repo, triggered by the user-friendly tool to edit the doc for the consultants).
Last but not least:Curious to see the current MVP in action?* the website with only one test module for now: https://oca-docs.netlify.app/* the CMS Decap access (login with your Github account): https://oca-docs.netlify.app/admin/* Florencia explains how to get started in this video: https://drive.google.com/file/d/1ZfBcicNdrssOnAWx7AKaYnM_tYIes4ID/view?usp=drive_linkHoping to get more feedback, I wish you a happy end of the 2024 year!Le mar. 10 déc. 2024 à 14:24, Virginie Dewulf <virginie@odoo-community.org> a écrit :Hello,This is a followup email for this email thread:During the 2024 OCA Days, the OCA Consultants working group presented the status of the Documentation project: how to document OCA modules right now (using the Github workflow) with Julie and Florencia (video here: https://youtu.be/Kw0V_PdBUPg?feature=shared).In parallel, a prototype of a new tool and process to easily document OCA modules has been proposed by Jairo Llopis, after discussion with Stéphane Bidoul to take into account the full picture of OCA infrastructure.The goal of this new way of managing the documentation is two-fold:1. Allow consultants to update the documentation in a user-friendly tool2. Have a beautiful website with a good search features to find and read the OCA modules documentationThis will impact the way the documentation is managed in the OCA modules. In summary, the documentation of all the OCA modules will be visible on a dedicated website, that will in the end of the transition replace the current OCA App Store. The documentation itself will be stored in a dedicated Doc repository (https://github.com/OCA/docs) and be removed from the readmes of the modules (where a link to the dedicated website will be displayed). Finally, there will be only one documentation page for all the versions of one module.The next steps are gathered in an issue on Github, called "the plan". Here it is:To get more information about this, please check the link above. You can also read the latest meeting notes of the Consultants meeting held in November here: https://docs.google.com/document/d/1v23TwOwm9I7w3MNFZo-iCWQxVKedwoVzN9nEyflJVd8/edit?usp=sharingIf you want to share your feedback on this topic, I propose to keep it in the related issue on Github:Thanks a lot to the consultants working group and especially to Jairo and Stéphane for their help! As you'll see in the plan, there are many "todo"s and help is always welcome.All the best,
by Virginie Dewulf - 04:57 - 17 Dec 2024 -
Re: OCA rub-boat error
I preferred to use a PR no need to be merged
On Tue, Dec 17, 2024, 14:24 mohamed alkobrosly <alkobroslymohamed@gmail.com> wrote:it is there in version 17.0
On Tue, Dec 17, 2024, 14:17 Rolando Pérez Rebollo <notifications@odoo-community.org> wrote:auth_jwt hasn't been migrated to v17, maybe you can PR to v16 and port it to v17 later.
https://odoo-community.org/shop/auth-jwt-6626
\rrebollo
On 12/17/24 04:17, mohamed alkobrosly wrote:
Hello dear community, I have been fixing an issue with a module and this module showed me two errors and the cause is the same, I suspect I should have add my fix to version 16.0 instead of version 17.0 due to that error.
Any guidance, please?
Downloading graphql-server-3.0.0b7.tar.gz (48 kB)56 Preparing metadata (setup.py): started57 Preparing metadata (setup.py): finished with status 'done'58ERROR: Could not find a version that satisfies the requirement odoo-addon-auth_jwt<17.1dev,>=17.0dev (from versions: 16.0.1.0.0.3, 16.0.1.1.0, 16.0.1.1.0.2, 16.0.1.1.0.3, 16.0.1.1.0.6, 16.0.1.1.0.7)59ERROR: No matching distribution found for odoo-addon-auth_jwt<17.1dev,>=17.0dev60Error: Process completed with exit code 1.
0s
_______________________________________________
Mailing-List: https://odoo-community.org/groups/contributors-15
Post to: mailto:contributors@odoo-community.org
Unsubscribe: https://odoo-community.org/groups?unsubscribe
_______________________________________________
Mailing-List: https://odoo-community.org/groups/contributors-15
Post to: mailto:contributors@odoo-community.org
Unsubscribe: https://odoo-community.org/groups?unsubscribe
by Mohamed Alkobrosly - 12:30 - 17 Dec 2024 -
Re: OCA rub-boat error
it is there in version 17.0
On Tue, Dec 17, 2024, 14:17 Rolando Pérez Rebollo <notifications@odoo-community.org> wrote:auth_jwt hasn't been migrated to v17, maybe you can PR to v16 and port it to v17 later.
https://odoo-community.org/shop/auth-jwt-6626
\rrebollo
On 12/17/24 04:17, mohamed alkobrosly wrote:
Hello dear community, I have been fixing an issue with a module and this module showed me two errors and the cause is the same, I suspect I should have add my fix to version 16.0 instead of version 17.0 due to that error.
Any guidance, please?
Downloading graphql-server-3.0.0b7.tar.gz (48 kB)56 Preparing metadata (setup.py): started57 Preparing metadata (setup.py): finished with status 'done'58ERROR: Could not find a version that satisfies the requirement odoo-addon-auth_jwt<17.1dev,>=17.0dev (from versions: 16.0.1.0.0.3, 16.0.1.1.0, 16.0.1.1.0.2, 16.0.1.1.0.3, 16.0.1.1.0.6, 16.0.1.1.0.7)59ERROR: No matching distribution found for odoo-addon-auth_jwt<17.1dev,>=17.0dev60Error: Process completed with exit code 1.
0s
_______________________________________________
Mailing-List: https://odoo-community.org/groups/contributors-15
Post to: mailto:contributors@odoo-community.org
Unsubscribe: https://odoo-community.org/groups?unsubscribe
_______________________________________________
Mailing-List: https://odoo-community.org/groups/contributors-15
Post to: mailto:contributors@odoo-community.org
Unsubscribe: https://odoo-community.org/groups?unsubscribe
by Mohamed Alkobrosly - 12:25 - 17 Dec 2024 -
Re: OCA rub-boat error
auth_jwt hasn't been migrated to v17, maybe you can PR to v16 and port it to v17 later.
https://odoo-community.org/shop/auth-jwt-6626
\rrebollo
On 12/17/24 04:17, mohamed alkobrosly wrote:
Hello dear community, I have been fixing an issue with a module and this module showed me two errors and the cause is the same, I suspect I should have add my fix to version 16.0 instead of version 17.0 due to that error.
Any guidance, please?
Downloading graphql-server-3.0.0b7.tar.gz (48 kB)56 Preparing metadata (setup.py): started57 Preparing metadata (setup.py): finished with status 'done'58ERROR: Could not find a version that satisfies the requirement odoo-addon-auth_jwt<17.1dev,>=17.0dev (from versions: 16.0.1.0.0.3, 16.0.1.1.0, 16.0.1.1.0.2, 16.0.1.1.0.3, 16.0.1.1.0.6, 16.0.1.1.0.7)59ERROR: No matching distribution found for odoo-addon-auth_jwt<17.1dev,>=17.0dev60Error: Process completed with exit code 1.
0s
_______________________________________________
Mailing-List: https://odoo-community.org/groups/contributors-15
Post to: mailto:contributors@odoo-community.org
Unsubscribe: https://odoo-community.org/groups?unsubscribe
by Ing. Rolando Pérez Rebollo - 12:15 - 17 Dec 2024 -
Re: Sync odoo's calendar smartphones without Google nor Outlook
> because > the migration has been blocked by the discussion whether to update > the radicale library (on which base_dav depends) or not. I don't see how this can be a discussion. Releasing new software that pretty much by necessity is internet accessible built on a deprecated library that hasn't received updates for 5 years simply is grossly negligent. Especially if there's a maintained version readily available and it would just take a bit of effort to adopt the existing code to that. -- Your partner for the hard Odoo problems https://hunki-enterprises.com
by Holger Brunn - 11:06 - 17 Dec 2024 -
OCA rub-boat error
Hello dear community, I have been fixing an issue with a module and this module showed me two errors and the cause is the same, I suspect I should have add my fix to version 16.0 instead of version 17.0 due to that error.Any guidance, please?Downloading graphql-server-3.0.0b7.tar.gz (48 kB)56 Preparing metadata (setup.py): started57 Preparing metadata (setup.py): finished with status 'done'58ERROR: Could not find a version that satisfies the requirement odoo-addon-auth_jwt<17.1dev,>=17.0dev (from versions: 16.0.1.0.0.3, 16.0.1.1.0, 16.0.1.1.0.2, 16.0.1.1.0.3, 16.0.1.1.0.6, 16.0.1.1.0.7)59ERROR: No matching distribution found for odoo-addon-auth_jwt<17.1dev,>=17.0dev60Error: Process completed with exit code 1.0s
by Mohamed Alkobrosly - 10:16 - 17 Dec 2024 -
Re: [18.0] Project Task Git integration
Hi Janik, thank you so much for sharing! I took a look at the connector, and from what I can see, it allows to sync repositories in your local environment by providing terminal access directly within the Odoo interface, along with some useful shortcuts and pre-configured commands. It's an interesting approach, and I might draw some inspiration from it.For this task in particular I was especially interested in automatizing commit and pull requests behaviour by using git webhooks, and today I succeded setting up an environment to debug and extend the PR posted by Alan. It took me a while since I had to find a way to test webhooks with a localhost (never did it before), I finally succeded with a pretty simple Ngrok tunneling configuration.I take the opportunity to keep you update, at the moment my "roadmap" is:with the module webhook_gitlab that Alan provided in https://github.com/OCA/project/pull/13901 - setting up a developement environment in order to be able to debug, test, analyze code, extend the module on the version it was designed for (17.0) -- Done2 - extend "webhook_gitlab" module to incorporate desired behaviour, which is at least a sync of the commit history (and maybe pull requests) linked to a task providing a list with links to the task related commits.I'll share some notes on this step: as a general idea a commit should automatically be linked to the project task (when "push event webhook" triggers) if the commit message contains the name of any "project.task" from the Odoo Project linked with the repo where the push event triggered.E.g. I have Odoo Project named "Project X" linked to https://github.com/MyOrganization/ProjectX GitHub repo. When I push a commit into ProjectX GitHub repository I will notify Odoo server by setting a webhook that calls webhook processing controller . We should add a structured push processing method (at the moment only merging is processed I think) that compare every "project.task" name related to ProjectX and check if "project.task" name is found in the commit message. In that case the commit ID should be stored in a git.commit (new) model related to the project task and will be used to build a clickable url which is probably stored in a computed field. There should probably also be a commit resync button. -- TODO, doesn't seem too hard, but will require some time to be done.3 - when the functionality will be working on 17.0 I will migrate it on the 18.0 version (which is the version I need to work with this feature). The migration should not be hard in this case since most of the code will be methods to process github webhook requests and simply store some data in models, there shouldn't be huge changes in the code -- TODOI plan to proceed with these steps over the next few weeks. If you have any recommendations, please feel free to share them. I believe the hardest part for me will be writing tests, as I'm not very familiar with it. Thankfully, I think I’ll find substantial help in https://github.com/OCA/interface-github/tree/16.0/github_connectorIl giorno gio 12 dic 2024 alle ore 10:18 Janik von Rotz <notifications@odoo-community.org> ha scritto:
Hi Francesco, I have developed a module to manage git repositories: https://github.com/Mint-System/Odoo-Apps-Connector/tree/16.0/git_base And here are the docs: https://www.odoo-wiki.org/git-base.html I will eventually develop a "project_git" module that connects projects with git repos and supports creating feature branches from tasks. All Mint System modules live up to the OCA standards. Cheers, Janik On 12/6/24 6:48 PM, Francesco Ballerini wrote: > Hi, > > we're looking for an Odoo 18 project task git integration. > > Specifically we need the feature that allows linking PR and commits to > the task by branch name/commit name containing the name of the task, > basically like Atlassian/Jira git integration. > > If you have any open source resource to provide as example we we might > try to migrate it to version 18.0. > > Thanks > > --Francesco Ballerini > > _______________________________________________ > Mailing-List: https://odoo-community.org/groups/contributors-15 > Post to: mailto:contributors@odoo-community.org > Unsubscribe: https://odoo-community.org/groups?unsubscribe > -- We are hiring: https://www.mint-system.ch/jobs Send application to: jobs@mint-system.ch CTO Mint System GmbH Tel: +41 44 244 7222
_______________________________________________
Mailing-List: https://odoo-community.org/groups/contributors-15
Post to: mailto:contributors@odoo-community.org
Unsubscribe: https://odoo-community.org/groups?unsubscribe
by Francesco Ballerini - 08:38 - 15 Dec 2024