git/Documentation/CodingGuidelines, branch gitk-resize-error

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

doc: clarify "do not capitalize the first word" rule

2021-04-15T06:41:00Z

The same "do not capitalize the first word" rule is applied to both our patch titles and error messages, but the existing description was fuzzy in two aspects. * For error messages, it was not said that this was only about the first word that begins the sentence. * For both, it was not clear when a capital letter there was not an error. We avoid capitalizing the first word when the only reason you would capitalize it is because it happens to be the first word in the sentence. If a proper noun, which is usually spelled in capital letters, happens to come at the beginning of the sentence, it should be kept in capital letters. Signed-off-by: Junio C Hamano

Merge branch 'dl/python-2.7-is-the-floor-version'

2020-06-18T04:54:05Z

Document that we do not support Python 2.6 or older. * dl/python-2.7-is-the-floor-version: CodingGuidelines: specify Python 2.7 is the oldest version

CodingGuidelines: specify Python 2.7 is the oldest version

2020-06-08T17:32:42Z

In 0b4396f068 (git-p4: make python2.7 the oldest supported version, 2019-12-13), git-p4 was updated to only support 2.7 and newer. Since Python 2.6 is pretty much ancient history, update CodingGuidelines to show that 2.7 is the oldest version supported. Signed-off-by: Denton Liu Signed-off-by: Junio C Hamano

Merge branch 'jc/codingstyle-compare-with-null'

2020-05-14T21:39:42Z

Doc update. * jc/codingstyle-compare-with-null: CodingGuidelines: do not ==/!= compare with 0 or '\0' or NULL

Merge branch 'jk/arith-expansion-coding-guidelines'

2020-05-08T21:25:07Z

The coding guideline for shell scripts instructed to refer to a variable with dollar-sign inside arithmetic expansion to work around a bug in old versions of dash, which is a thing of the past. Now we are not forbidden from writing $((var+1)). * jk/arith-expansion-coding-guidelines: CodingGuidelines: drop arithmetic expansion advice to use "$x"