git/Documentation/CodingGuidelines, branch v2.45.2

Merge branch 'jc/local-extern-shell-rules'

2024-04-16T21:50:27Z

Document and apply workaround for a buggy version of dash that mishandles "local var=val" construct. * jc/local-extern-shell-rules: t1016: local VAR="VAL" fix t0610: local VAR="VAL" fix t: teach lint that RHS of 'local VAR=VAL' needs to be quoted t: local VAR="VAL" (quote ${magic-reference}) t: local VAR="VAL" (quote command substitution) t: local VAR="VAL" (quote positional parameters) CodingGuidelines: quote assigned value in 'local var=$val' CodingGuidelines: describe "export VAR=VAL" rule

CodingGuidelines: quote assigned value in 'local var=$val'

2024-04-06T05:50:05Z

Dash bug https://bugs.launchpad.net/ubuntu/+source/dash/+bug/139097 lets the shell erroneously perform field splitting on the expansion of a command substitution during declaration of a local or an extern variable. The explanation was stolen from ebee5580 (parallel-checkout: avoid dash local bug in tests, 2021-06-06). Signed-off-by: Junio C Hamano

CodingGuidelines: describe "export VAR=VAL" rule

2024-04-06T05:48:12Z

https://lore.kernel.org/git/201307081121.22769.tboegi@web.de/ resulted in 9968ffff (test-lint: detect 'export FOO=bar', 2013-07-08) to add a rule to t/check-non-portable-shell.pl script to reject export VAR=VAL and suggest us to instead write it as two statements, i.e., VAR=VAL export VAR This however was not spelled out in the CodingGuidelines document. We may want to re-evaluate the rule since it is from ages ago, but for now, let's make the written rule and what the automation enforces consistent. Signed-off-by: Junio C Hamano

doc: rework CodingGuidelines with new formatting rules

2024-03-29T17:57:40Z

Literal and placeholder formatting is more heavily enforced, with some asciidoc magic. Basically, the markup is preserved everywhere. Signed-off-by: Jean-Noël Avila Signed-off-by: Junio C Hamano

Merge branch 'jc/doc-compat-util'

2024-03-05T17:44:43Z

Clarify wording in the CodingGuidelines that requires to be the first header file. * jc/doc-compat-util: doc: clarify the wording on requirement

Merge branch 'ja/doc-placeholders-markup-rules' into HEAD

2024-03-01T22:38:55Z

The way placeholders are to be marked-up in documentation have been specified; use "__" to typeset the word inside a pair of emphasized. * ja/doc-placeholders-markup-rules: doc: clarify the format of placeholders

doc: clarify the wording on requirement

2024-02-27T16:53:32Z

The reason why we require the file to be the first header file to be included is because it insulates other header files and source files from platform differences, like which system header files must be included in what order, and what C preprocessor feature macros must be defined to trigger certain features we want out of the system. We tried to clarify the rule in the coding guidelines document, but the wording was a bit fuzzy that can lead to misinterpretations like you can include only to avoid having to include even if you have nothing to do with the xdiff implementation, for example. "You do not have to include more than one of these" was also misleading and would have been puzzling if you _needed_ to depend on more than one of these approved headers (answer: you are allowed to include them all if you need the declarations in them for reasons other than that you want to avoid including compat-util yourself). Instead of using the phrase "approved headers", enumerate them as exceptions, each labeled with its intended audiences, to avoid such misinterpretations. The structure also makes it easier to add new exceptions, so add the description of "t/unit-tests/test-lib.h" being an exception only for the unit tests implementation as an example. Signed-off-by: Junio C Hamano Acked-by: Kyle Lippincott Acked-by: Elijah Newren

doc: clarify the format of placeholders

2024-02-21T22:01:46Z

Add the new format rule when using placeholders in the description of commands and options. Signed-off-by: Jean-Noël Avila Signed-off-by: Junio C Hamano

Merge branch 'js/contributor-docs-updates' into maint-2.43

2024-02-09T00:22:11Z

Doc update. * js/contributor-docs-updates: SubmittingPatches: hyphenate non-ASCII SubmittingPatches: clarify GitHub artifact format SubmittingPatches: clarify GitHub visual SubmittingPatches: provide tag naming advice SubmittingPatches: update extra tags list SubmittingPatches: discourage new trailers SubmittingPatches: drop ref to "What's in git.git" CodingGuidelines: write punctuation marks CodingGuidelines: move period inside parentheses

Merge branch 'js/update-urls-in-doc-and-comment' into maint-2.43

2024-02-09T00:22:01Z

Stale URLs have been updated to their current counterparts (or archive.org) and HTTP links are replaced with working HTTPS links. * js/update-urls-in-doc-and-comment: doc: refer to internet archive doc: update links for andre-simon.de doc: switch links to https doc: update links to current pages