Skip to content

meaning of Summary #616

Open
Open

Description

@jans23

Currently the field Summary is in section Revision so from this layout I understand that for each change users should give that change a Name and a Summary.

Image

The issues I see:

  • To describe a change two fields are unusual and IMO a single field would be sufficient
  • While editing the document content, both fields are not cleared so in practice you end up not updating those which renders the history useless (think of git would use a default commit message if you don't change it explicitly). This is the main issue I experience.
  • The history shows the Summary but not the Name. So what is the Name good for?
  • In the search for a document the default field is Summary. IMO this doesn't make sense if the Summary is specific per revision while the user is typically searching for a document
Image Image

I suggest the following solution:

  • Move Summary out of section Revision.
  • So we use Name for Revisions only and ideally rename that field to Changes
  • Show Name/Changes in the History instead of Summary
  • Change the UI so that user must enter a Name/Changes when changing a document revision and can not simply keep its content of the previous revision (likely an additional window)

What do you think?

Activity

  1. jans23 commented on Jul 10, 2026

    @jans23
    Author

    @etobella @diggy128 looking at your discussion in #565 this issue may be of relevance. Any opinion?

  2. diggy128 commented on Jul 11, 2026

    @diggy128
    Contributor
    • To describe a change two fields are unusual and IMO a single field would be sufficient

    Actually no.
    The name field should identify the revision (think of it as version number).

    The second should briefly describe the changes made without having to go through the diff (think of it as commit summary).

    Each serves a different purpose.

    • While editing the document content, both fields are not cleared so in practice you end up not updating those which renders the history useless (think of git would use a default commit message if you don't change it explicitly). This is the main issue I experience.

    That was exactly my point.

    • The history shows the Summary but not the Name. So what is the Name good for?

    Indeed it is missing from the list view.

    • In the search for a document the default field is Summary. IMO this doesn't make sense if the Summary is specific per revision while the user is typically searching for a document

    Also true. Best case would be the first filter to have a domain and search all of document name, document content and revision summary. Specific filters should follow.

    I suggest the following solution:

    • Move Summary out of section Revision.

    As pointed out above both fields are part of the revision handling, so it would be disorienting for the user to have them at separate places.

    • So we use Name for Revisions only and ideally rename that field to Changes
    • Show Name/Changes in the History instead of Summary

    Ideally name (revision number) should be visible in list view and summary with optional=show (so current users can see it, but allow to be hidden).

    • Change the UI so that user must enter a Name/Changes when changing a document revision and can not simply keep its content of the previous revision (likely an additional window)

    This is what @etobella suggested at #565 (comment)

    However we should first settle on how those two fields should work.

    I've also opened #614 in an effort to generalize handling the revisions and align to a common workflow (aka base_revision) across all odoo modules (another candidate would be mrp_bom_version).

  3. jans23 commented on Jul 11, 2026

    @jans23
    Author

    The name field should identify the revision (think of it as version number).

    There is a technical ID shown in the history already. So I don't see the point of another number which has to be incremented manually.

    The second should briefly describe the changes made without having to go through the diff (think of it as commit summary).

    Other than git these are documents in human language which show the diff for each revision easily accessible just two clicks away.

    Also the knowledge module in Odoo Enterprise doesn't have any revision name or summary at all. This would be ok for me as well.

    Move Summary out of section Revision.

    As pointed out above both fields are part of the revision handling, so it would be disorienting for the user to have them at separate places.

    My suggestion is to have the summary a general field, not specific to each revision.

  4. diggy128 commented on Jul 11, 2026

    @diggy128
    Contributor

    There is a technical ID shown in the history already. So I don't see the point of another number which has to be incremented manually.

    This is the ID field in the database. This should not have been used as it can change at any time (especially after an update / upgrade or migration).
    This could lead to a printed document having e.g. revision 1268 while odoo has changed that to 1275

    Imo this a problematic implementation.

    Other than git these are documents in human language which show the diff for each revision easily accessible just two clicks away.

    Take the case of a 120 page quality manual, that you need to update because you have changed the quality manager role to quality assurance officer.
    A user will have to go through a diff of 120 pages to conclude that the change is all about a role change.
    Having a summary field that reads "Changed quality manager role to quality assurance officer" would not only save time but it will also provide clear identification of changes. Especially when reviewing a document for approval. This is a document control requirement.

    This is not a git concept that is used in document management. It is a document control detail that git embedded in its core.

    Also the knowledge module in Odoo Enterprise doesn't have any revision name or summary at all. This would be ok for me as well.

    I don't know the specifics of knowledge in Enterprise but I think it's main use is more a knowledge / faq module not a controlled documentation (aka SOP, etc) module.

  5. jans23 commented on Jul 11, 2026

    @jans23
    Author

    So you suggest to introduce a version field which is not editable and does automatically increment with each revision?

    Take the case of a 120 page quality manual, that you need to update...

    Ok for a one change summary field. But you agree that we don't need an additional name field.

    Odoo Enterprise's Knowledge is document-centric and not a FAQ database. But indeed I don't see permission and approval settings.

  6. diggy128 commented on Jul 11, 2026

    @diggy128
    Contributor

    So you suggest to introduce a version field which is not editable and does automatically increment with each revision?

    Ok for a one change summary field. But you agree that we don't need an additional name field.

    Actually I think that the field name is poorly worded. It should be revision number or something similar.

    That same field not being editable and incrementing with each revision is something we've been using since v8 (an internally developed module).

    Both points above are what made me open #416.

    Keep the same concept and implementation of base_revision across any module / model in Odoo.

    As is, name as a free string, i.m.o. is definitely not needed.

    Odoo Enterprise's Knowledge is document-centric and not a FAQ database. But indeed I don't see permission and approval settings.

    The approval workflow is at document_page_aprroval as a separate module.

    I think at this point the PSC responsible for the knowledge modules should chime in and provide a direction OR open a thread for discussion on further development.

  7. jans23 commented on Jul 11, 2026

    @jans23
    Author

    Yes, who is the knowledge PSC?

  8. diggy128 commented on Jul 11, 2026

    @diggy128
    Contributor

    @OCA/document-maintainers

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions