From 62ea0f02b9b533a512290d776da1d1bf27bffbcf Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jan=20Pokorn=C3=BD?= Date: Tue, 16 Aug 2016 15:48:14 +0200 Subject: [PATCH] Doc: Development/FAQ: be more strict about line lengths+bug reports Changes + justification: 1. commit line lengths, lowering the limit from 80 to 70-75: - commit summary is actually actively encouraged to fit into the 50 characters limit if possible so there is still quite a space provided on top of that: GIT-COMMIT(1), GITTUTORIAL(7) - it makes sense for the rest to follow lenght limit as recommended in the Internet Message Form (RFC 2822, note that sending the patch to ML is offered as an alternative), which is 78, with line-wrap limit in MUAs traditionally preset at 72 that also falls into the proposed limit of 70-75, and such line length is also automatically enforced with native "gitcommit" filetype plugin in vim (to state another source of de facto standard) - 70-75 range is not made up but adapted from Linux kernel guidelines: http://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/tree/Documentation/SubmittingPatches?h=v4.7&id=523d939ef98fd712632d93a5a2b588e477a7565e#n655 - overall tone is slightly shifted from a recommendation to a rule 2. bug report references are welcome, but only if they are publicly viewable - it's of no use for the wide audience otherwise, hence private bug mapping should be tracked *privately* by those who would make a use of that directly and not clutter public logs of a free software project 3. one occurrence of "explanation" turned into "description" as the former was a bit overloaded in two various contexts --- doc/Pacemaker_Development/en-US/Ch-FAQ.txt | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/doc/Pacemaker_Development/en-US/Ch-FAQ.txt b/doc/Pacemaker_Development/en-US/Ch-FAQ.txt index 4fd3c3ada98..14da5aef30f 100644 --- a/doc/Pacemaker_Development/en-US/Ch-FAQ.txt +++ b/doc/Pacemaker_Development/en-US/Ch-FAQ.txt @@ -58,10 +58,12 @@ How should I format my Git commit messages?:: change log for the next release. The +affected-code+ is the name of the component(s) being changed, for example, +crmd+ or +libcrmcommon+ (it's more free-form, so don't sweat getting it exact). The +explanation+ briefly - describes the change (ideally, the entire summary line will stay under 80 - characters, but it's OK if more is needed to be clear). For most commits, the - first line should be followed by a blank line and then a longer explanation of - 'why' the change was made (referencing any relevant bug reports). + describes the change (ideally, the entire summary line as well as the lines + forming additional paragraphs will stay under 70-75 characters, but + exceptions are tolerated if more is needed to be clear). For most commits, + the first line should be followed by a blank line and then a longer + description of 'why' the change was made (referencing any relevant bug + reports if they are publicly viewable). How can I test my changes?:: Most importantly, Pacemaker has regression tests for most major components;