Hi Ihor,
That sounds like a sensible approach. Perhaps another way to make large
changes easier to review would be to split them into smaller,
self-contained patches where possible, with an indication of each
patch's type and estimated risk.
In my own workflow, I combine the AngularJS commit convention [1] with an
adaptation of Arlo's Commit Notation [2]. I replaced the risk symbols with
numbers:
| Risk Number | Risk Level | Meaning |
Correctness Guarantees |
|-------------+---------------------+---------------------------------------+------------------------------------------------------|
| 0 | *Known safe* | Addresses all known and unknown risks.|
Intended Change, Known Invariants, Unknown Invariants|
| 1 | *Validated* | Addresses all known risks. |
Intended Change, Known Invariants |
| 2 | *Risky* | Some known risks remain unverified. |
Intended Change |
| 3 | *(Probably) Broken* | No risk attestation. |
|
For change types, I use the following list, with [remove] as my own addition:
| Type | Meaning
|
|------------+-------------------------------------------------------------------------------------------------------------------|
| [feat] | A new feature
|
| [fix] | A bug fix
|
| [docs] | Documentation-only changes
|
| [style] | Changes that do not affect the meaning of the code, such as
whitespace, formatting, missing semicolons, and so on |
| [refactor] | A code change that neither fixes a bug nor adds a feature
|
| [perf] | A code change that improves performance
|
| [test] | Changes that add missing tests
|
| [chore] | Changes to the build process or auxiliary tools and libraries,
such as documentation generation |
| [remove] | A modifier placed before another type, for example [remove]
[feat] |
My commit format is risk-number type-of-change where what, to give
concrete examples, here are some of my org-colview changes already on
main, rewritten using this notation. The risk numbers are illustrative
assessments, not part of the original commits:
0 [remove] [docs] org-colview - Drop redundant agenda comment
(487180e33)
0 [test] org-colview - Document summary depth limit
(8a13d1fef)
0 [refactor] org-colview - Extract dynamic block data capture
(9aae2ea53)
1 [perf] org-colview - Capture column view without rendering overlays
(293bc2eae)
0 [feat] org-colview - Add quick help for column view
(07c6db9bc)
0 [fix] org-colview - Fix multi-digit completed cookies in "X/" summary
(397c198a4)
The risk level represents the author's assessment, ideally accompanied
by a brief explanation of what was tested and what remains
uncertain. Together with smaller patches, this could help reviewers
identify which changes need the most attention.
For Org, this could be optional information in the patch-series
description, without changing the existing commit-message conventions.
To be clear, I am not proposing any formal changes here, as that would
be quite a shift. I am merely sharing this as food for thought in case
any part of it proves inspiring.
Best,
--
Slawomir Grochowski
[1] https://github.com/angular/angular.js/blob/master/CONTRIBUTING.md#commit
[2] https://corgibytes.com/blog/2021/01/12/arlos-commit-notation/
