git/Documentation/CodingGuidelines, branch v2.37.2

Documentation/ToolsForGit.txt: Tools for developing Git

2022-04-21T16:50:25Z

This document gathers tips, scripts and configuration file to help people working on Git’s codebase use their favorite tools while following Git’s coding style. Move the part about Emacs configuration from CodingGuidelines to ToolsForGit.txt because it's the purpose of the new file centralize the information about tools. But, add a mention to Documentation/ToolsForGit.txt in CodingGuidelines because there is also information about the coding style in it. Helped-by: Matthieu Moy Helped-by: Junio C Hamano Signed-off-by: COGONI Guillaume Signed-off-by: Junio C Hamano

Merge branch 'jc/coding-guidelines-decl-in-for-loop'

2022-04-04T17:56:24Z

Coding Guidelines clarification. * jc/coding-guidelines-decl-in-for-loop: CodingGuidelines: give deadline for "for (int i = 0; ..."

CodingGuidelines: give deadline for "for (int i = 0; ..."

2022-03-31T20:12:26Z

We raised the weather balloon to see if we can allow the construct in 44ba10d6 (revision: use C99 declaration of variable in for() loop, 2021-11-14), which was shipped as a part of Git v2.35. Document that fact in the coding guidelines, and more importantly, give ourselves a deadline to revisit and update. Let's declare that we will officially adopt the variable declaration in the initializaiton part of "for ()" statement this winter, unless we find that a platform we care about does not grok it. Signed-off-by: Junio C Hamano

C99: remove hardcoded-out !HAVE_VARIADIC_MACROS code

2022-02-22T03:14:19Z

Remove the "else" branches of the HAVE_VARIADIC_MACROS macro, which have been unconditionally omitted since 765dc168882 (git-compat-util: always enable variadic macros, 2021-01-28). Since were always omitted, anyone trying to use a compiler without variadic macro support to compile a git since version git v2.31.0 or later would have had a compilation error. 10 months across a few releases since then should have been enough time for anyone who cared to run into that and report the issue. In addition to that, for anyone unsetting HAVE_VARIADIC_MACROS we've been emitting extremely verbose warnings since at least ee4512ed481 (trace2: create new combined trace facility, 2019-02-22). That's because there is no such thing as a "region_enter_printf" or "region_leave_printf" format, so at least under GCC and Clang everything that includes trace.h (almost every file) emits a couple of warnings about that. There's a large benefit to being able to have a hard dependency rely on variadic macros, the code surrounding usage.c is hard to maintain if we need to write two implementations of everything, and by relying on "__FILE__" and "__LINE__" along with "__VA_ARGS__" we can in the future make error(), die() etc. log where they were called from. We've also recently merged d67fc4bf0ba (Merge branch 'bc/require-c99', 2021-12-10) which further cements our hard dependency on C99. So let's delete the fallback code, and update our CodingGuidelines to note that we depend on this. The added bullet-point starts with lower-case for consistency with other bullet-points in that section. The diff in "trace.h" is relatively hard to read, since we need to retain the existing API docs, which were comments on the code used if HAVE_VARIADIC_MACROS was not defined. Signed-off-by: Ævar Arnfjörð Bjarmason Signed-off-by: Junio C Hamano

CodingGuidelines: hint why we value clearly written log messages

2022-01-28T01:50:04Z

Signed-off-by: Junio C Hamano

CodingGuidelines: document which output goes to stdout vs. stderr

2021-12-05T01:26:41Z

It has long been practice on this project for a command to emit its primary output to stdout so that it can be captured to a file or sent down a pipe, and to emit "chatty" messages (such as those reporting progress) to stderr so that they don't interfere with the primary output. However, this practice is not necessarily universal; another common practice is to send only error messages to stderr, and all other messages to stdout. Therefore, help newcomers out by documenting how stdout and stderr are used on this project. Signed-off-by: Eric Sunshine Acked-by: Jeff King Signed-off-by: Junio C Hamano

Merge branch 'ds/gender-neutral-doc-guidelines'

2021-07-28T20:18:02Z

A guideline for gender neutral documentation has been added. * ds/gender-neutral-doc-guidelines: CodingGuidelines: recommend gender-neutral description

CodingGuidelines: recommend gender-neutral description

2021-07-16T18:35:46Z

Technical writing seeks to convey information with minimal friction. One way that a reader can experience friction is if they encounter a description of "a user" that is later simplified using a gendered pronoun. If the reader does not consider that pronoun to apply to them, then they can experience cognitive dissonance that removes focus from the information. Give some basic tips to guide us avoid unnecessary uses of gendered description. Using a gendered pronoun is appropriate when referring to a specific person. There are acceptable existing uses of gendered pronouns within the Git codebase, such as: * References to real people (e.g. Linus Torvalds, "the Git maintainer"). Do not misgender real people. If there is any doubt to the gender of a person, then avoid using pronouns. * References to fictional people with clear genders (e.g. Alice and Bob). * Sample text used in test cases (e.g t3702, t6432). * The official text of the GPL license contains uses of "he or she", but using singular "they" (or modifying the text in some other way) is not within the scope of the Git project. * Literal email messages in Documentation/howto/ should not be edited for grammatical concerns such as this, unless we update the entire document to fit the standard documentation format. If such an effort is taken on, then the authorship would change and no longer refer to the exact mail message. * External projects consumed in contrib/ should not deviate solely for style reasons. Recommended edits should be contributed to those projects directly. Other cases within the Git project were cleaned up by the previous changes. Co-authored-by: Junio C Hamano Signed-off-by: Derrick Stolee Signed-off-by: Junio C Hamano

Merge branch 'jc/test-allows-local'

2021-05-11T06:27:22Z

Document that our test can use "local" keyword. * jc/test-allows-local: CodingGuidelines: explicitly allow "local" for test scripts

CodingGuidelines: explicitly allow "local" for test scripts

2021-05-03T05:24:11Z

01d3a526 (t0000: check whether the shell supports the "local" keyword, 2017-10-26) raised a test balloon to see if those who build and test Git use a platform with a shell that lacks support for the "local" keyword. After two years, 7f0b5908 (t0000: reword comments for "local" test, 2019-08-08) documented that "local" keyword, even though is outside POSIX, is allowed in our test scripts. Let's write it in the CodingGuidelines, too. It might be tempting to allow it in scripted Porcelains (we have avoided getting them contaminiated by "local" so far), but they are on their way out and getting rewritten in C. Signed-off-by: Junio C Hamano