doc: prevent writing "topic:" to commit message

First time contributors surprisingly often write "topic:"
instead of "the main part or subsystem the patch touches" as requested
in patchguide.html

To prevent them doing so:
Use longer self-explaing "specify touched area" instead of "topic"
Give some examples in addition to recommended looking at "git log"

Change-Id: I1c307b460d7a79ba3c9918af8dbc9e9f827e1fb9
Signed-off-by: Tomas Vanek <vanekt@fbl.cz>
Reviewed-on: https://review.openocd.org/c/openocd/+/6683
Reviewed-by: Antonio Borneo <borneo.antonio@gmail.com>
Tested-by: Paul Fertser <fercerpav@gmail.com>
This commit is contained in:
Tomas Vanek 2021-11-09 19:22:29 +01:00
parent 830d70bfc6
commit 4d1b29313a
1 changed files with 31 additions and 5 deletions

36
HACKING
View File

@ -171,11 +171,11 @@ while(!done) {
@endcode
\note use "git add ." before commit to add new files.
Comment template, notice the short first line w/topic. The topic field
should identify the main part or subsystem the patch touches. Check
git log for examples.
@code
topic: Short comment
Commit message template, notice the short first line.
The field '<c>specify touched area</c>'
should identify the main part or subsystem the patch touches.
@code{.unparsed}
specify touched area: short comment
<blank line>
Longer comments over several lines, explaining (where applicable) the
reason for the patch and the general idea the solution is based on,
@ -183,6 +183,32 @@ any major design decisions, etc...
<blank line>
Signed-off-by: ...
@endcode
Examples:
@code{.unparsed}
flash/nor/atsame5: add SAME59 support
Add new device ID
@endcode
@code{.unparsed}
flash/nor: flash driver for XYZ123
Add new flash driver for internal flash of ...
@endcode
@code{.unparsed}
target/cortex_m: fix segmentation fault in cmd 'soft_reset_halt'
soft_reset_halt command failed reproducibly under following conditions: ...
Test for NULL pointer and return error ...
Reported-by: John Reporter <rep9876@gmail.com>
Fixes: 123456789abc ("target: the commit where the problem started")
BugLink: https://sourceforge.net/p/openocd/tickets/999/
@endcode
@code{.unparsed}
doc: fix typos
@endcode
See "git log" for more examples.
-# Next you need to make sure that your patches
are on top of the latest stuff on the server and
that there are no conflicts: