From 4d1b29313ace5b26687f75fb132c04f91cc1edcb Mon Sep 17 00:00:00 2001 From: Tomas Vanek Date: Tue, 9 Nov 2021 19:22:29 +0100 Subject: [PATCH] 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 Reviewed-on: https://review.openocd.org/c/openocd/+/6683 Reviewed-by: Antonio Borneo Tested-by: Paul Fertser --- HACKING | 36 +++++++++++++++++++++++++++++++----- 1 file changed, 31 insertions(+), 5 deletions(-) diff --git a/HACKING b/HACKING index cf3f58906..96b05f2d6 100644 --- a/HACKING +++ b/HACKING @@ -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 'specify touched area' + should identify the main part or subsystem the patch touches. +@code{.unparsed} +specify touched area: short comment 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... 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 +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: