From 0979659fd31216a6a5cebd691a136d023ea253f8 Mon Sep 17 00:00:00 2001 From: Don Kendall Date: Wed, 27 May 2026 18:28:05 -0400 Subject: [PATCH 1/2] [DOC] 090_contribute: per-line inline annotation markers MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The current guide says lines can be reordered and grouped into a "logical" block with a single consolidated comment. Recent reviewer feedback consistently asks the opposite — each analysis line gets its own inline marker, no consolidated author-blocks above multi-line groups. Update the Note to describe the inline-per-line convention and add a short example showing the expected shape. --- docsource/090_contribute.rst | 28 ++++++++++++++++++++++++++-- 1 file changed, 26 insertions(+), 2 deletions(-) diff --git a/docsource/090_contribute.rst b/docsource/090_contribute.rst index 926ffce1aba6..47d35dc94bae 100644 --- a/docsource/090_contribute.rst +++ b/docsource/090_contribute.rst @@ -58,8 +58,32 @@ For example, the sale_stock migration script may fail, if the stock migration sc * ``TODO``: This shouldn't be usually done. **Note:** -You can reorder lines and group them together for including all of them in a "logical" block for putting only one comment. -Examples: all the noupdate=0 new and del ir* records, or the NEW and DEL lines for a field that is renamed. +Place each marker **inline, on its own line, immediately following the +specific analysis line it annotates**. Don't consolidate multiple adjacent +analysis lines under a single grouped comment, even when the lines are +conceptually related — each gets its own one-line marker. + +Empty section headers (e.g. ``---Models in module 'X'---`` with no +content below) still receive a single marker. + +Markers are terse — typically ``# DONE: `` or +``# NOTHING TO DO``. The "why" belongs in the commit message body or +PR description, not in the work file. + +Example: + +.. code-block:: text + + ---Fields in module 'X'--- + X / account.tax / l10n_in_is_lut (boolean): NEW + # DONE: add_fields in pre-migration. + X / account.tax / l10n_in_tax_type (selection): is now stored + # DONE: add_fields in pre-migration; map_values for legacy selection set. + X / res.partner / l10n_in_pan (char): DEL + # NOTHING TO DO: new field name differs; update_db preserves old column as legacy. + + ---XML records in module 'X'--- + # NOTHING TO DO * Write ``pre-migration.py`` and / or ``post-migration.py`` scripts in the same folder. From b1e14c35033e64206d49a6c3708d725294c0d6d4 Mon Sep 17 00:00:00 2001 From: Don Kendall Date: Sat, 30 May 2026 11:35:05 -0400 Subject: [PATCH 2/2] [DOC] 090_contribute: empty sections get no marker (hbrunn #5647) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Align the annotation guidance with hbrunn's review on #5647 ('don't add this for empty lists') — empty work-file sections are left blank; only populated sections get an inline # DONE / # NOTHING TO DO marker. --- docsource/090_contribute.rst | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/docsource/090_contribute.rst b/docsource/090_contribute.rst index 47d35dc94bae..c038f8b4344c 100644 --- a/docsource/090_contribute.rst +++ b/docsource/090_contribute.rst @@ -64,7 +64,10 @@ analysis lines under a single grouped comment, even when the lines are conceptually related — each gets its own one-line marker. Empty section headers (e.g. ``---Models in module 'X'---`` with no -content below) still receive a single marker. +analysis lines below) get **no** marker — leave them blank. Only +sections with content are annotated; a whole module with nothing to do +is recorded in the coverage matrix (column 2), not by marking an empty +work-file section. Markers are terse — typically ``# DONE: `` or ``# NOTHING TO DO``. The "why" belongs in the commit message body or