git/Documentation/CodingGuidelines, branch v2.13.2

Merge branch 'ab/c-translators-comment-style' into maint

2017-06-05T00:03:10Z

Update the C style recommendation for notes for translators, as recent versions of gettext tools can work with our style of multi-line comments. * ab/c-translators-comment-style: C style: use standard style for "TRANSLATORS" comments

C style: use standard style for "TRANSLATORS" comments

2017-05-30T23:01:42Z

Change all the "TRANSLATORS: [...]" comments in the C code to use the regular Git coding style, and amend the style guide so that the example there uses that style. This custom style was necessary back in 2010 when the gettext support was initially added, and was subsequently documented in commit cbcfd4e3ea ("i18n: mention "TRANSLATORS:" marker in Documentation/CodingGuidelines", 2014-04-18). GNU xgettext hasn't had the parsing limitation that necessitated this exception for almost 3 years. Since its 0.19 release on 2014-06-02 it's been able to recognize TRANSLATOR comments in the standard Git comment syntax[1]. Usually we'd like to keep compatibility with software that's that young, but in this case literally the only person who needs to be using a gettext newer than 3 years old is Jiang Xin (the only person who runs & commits "make pot" results), so I think in this case we can make an exception. This xgettext parsing feature was added after a thread on the Git mailing list[2] which continued on the bug-gettext[3] list, but we never subsequently changed our style & styleguide, do so. There are already longstanding changes in git that use the standard comment style & have their TRANSLATORS comments extracted properly without getting the literal "*"'s mixed up in the text, as would happen before xgettext 0.19. Commit 7ff2683253 ("builtin-am: implement -i/--interactive", 2015-08-04) added one such comment, which in commit df0617bfa7 ("l10n: git.pot: v2.6.0 round 1 (123 new, 41 removed)", 2015-09-05) got picked up in the po/git.pot file with the right format, showing that Jiang already runs a modern xgettext. The xgettext parser does not handle the sort of non-standard comment style that I'm amending here in sequencer.c, but that isn't standard Git comment syntax anyway. With this change to sequencer.c & "make pot" the comment in the pot file is now correct: #. TRANSLATORS: %s will be "revert", "cherry-pick" or -#. * "rebase -i". +#. "rebase -i". 1. http://git.savannah.gnu.org/cgit/gettext.git/commit/?id=10af7fe6bd 2. <2ce9ec406501d112e032c8208417f8100bed04c6.1397712142.git.worldhello.net@gmail.com> (https://public-inbox.org/git/2ce9ec406501d112e032c8208417f8100bed04c6.1397712142.git.worldhello.net@gmail.com/) 3. https://lists.gnu.org/archive/html/bug-gettext/2014-04/msg00016.html Signed-off-by: Ævar Arnfjörð Bjarmason Acked-by: Jiang Xin Signed-off-by: Junio C Hamano

doc: replace a couple of broken gmane links

2017-05-08T01:29:30Z

Replace a couple of broken links to gmane with links to other archives. See commit 54471fdcc3 ("README: replace gmane link with public-inbox", 2016-12-15) for prior art. With this change there's still 4 references left in the code: $ git grep -E '(article|thread)\.gmane.org' -- |grep -v RelNotes|wc -l 4 I couldn't find alternative links for those. Signed-off-by: Ævar Arnfjörð Bjarmason Signed-off-by: Junio C Hamano

CodingGuidelines: clarify multi-line brace style

2017-01-17T22:32:47Z

There are some "gray areas" around when to omit braces from a conditional or loop body. Since that seems to have resulted in some arguments, let's be a little more clear about our preferred style. Signed-off-by: Jeff King Signed-off-by: Junio C Hamano

CodingGuidelines: formatting HEAD in documentation

2016-06-28T15:36:45Z

The current practice is: git/Documentation$ git grep "'HEAD'" | wc -l 24 git/Documentation$ git grep "\`HEAD\`" | wc -l 66 Let's adopt the majority as a guideline. Signed-off-by: Matthieu Moy Signed-off-by: Junio C Hamano

doc: clearer rule about formatting literals

2016-06-08T19:04:37Z

Make the guideline text that we want for our documentation clearer. Signed-off-by: Tom Russello Signed-off-by: Erwan Mathoniere Signed-off-by: Samuel Groot Signed-off-by: Matthieu Moy Reviewed-by: Matthieu Moy Signed-off-by: Junio C Hamano

add DEVELOPER makefile knob to check for acknowledged warnings

2016-02-25T20:49:45Z

We assume Git developers have a reasonably modern compiler and recommend them to enable the DEVELOPER makefile knob to ensure their patches are clear of all compiler warnings the Git core project cares about. Enable the DEVELOPER makefile knob in the Travis-CI build. Suggested-by: Jeff King Signed-off-by: Lars Schneider Signed-off-by: Junio C Hamano

Merge branch 'jg/cguide-we-cannot-count'

2015-04-14T16:55:29Z

* jg/cguide-we-cannot-count: CodingGuidelines: update 'rough' rule count

CodingGuidelines: update 'rough' rule count

2015-04-14T16:50:31Z

Changed inaccurate count of "rough rules" from three to the more generic 'a few'. Signed-off-by: Julian Gindi Reviewed-by: Eric Sunshine Reviewed-by: Jonathan Nieder Signed-off-by: Junio C Hamano

*config.txt: stick to camelCase naming convention

2015-03-14T05:13:46Z

This should improve readability. Compare "thislongname" and "thisLongName". The following keys are left in unchanged. We can decide what to do with them later. - am.keepcr - core.autocrlf .safecrlf .trustctime - diff.dirstat .noprefix - gitcvs.usecrlfattr - gui.blamehistoryctx .trustmtime - pull.twohead - receive.autogc - sendemail.signedoffbycc .smtpsslcertpath .suppresscc Helped-by: Eric Sunshine Signed-off-by: Nguyễn Thái Ngọc Duy Signed-off-by: Eric Sunshine Signed-off-by: Junio C Hamano