git/Documentation/CodingGuidelines, branch v2.48.2

Merge branch 'ps/build'

2024-12-16T01:54:33Z

Build procedure update plus introduction of Meson based builds. * ps/build: (24 commits) Introduce support for the Meson build system Documentation: add comparison of build systems t: allow overriding build dir t: better support for out-of-tree builds Documentation: extract script to generate a list of mergetools Documentation: teach "cmd-list.perl" about out-of-tree builds Documentation: allow sourcing generated includes from separate dir Makefile: simplify building of templates Makefile: write absolute program path into bin-wrappers Makefile: allow "bin-wrappers/" directory to exist Makefile: refactor generators to be PWD-independent Makefile: extract script to generate gitweb.js Makefile: extract script to generate gitweb.cgi Makefile: extract script to massage Python scripts Makefile: extract script to massage Shell scripts Makefile: use "generate-perl.sh" to massage Perl library Makefile: extract script to massage Perl scripts Makefile: consistently use PERL_PATH Makefile: generate doc versions via GIT-VERSION-GEN Makefile: generate "git.rc" via GIT-VERSION-GEN ...

Merge branch 'jc/doc-error-message-guidelines'

2024-12-13T15:33:37Z

Developer documentation update. * jc/doc-error-message-guidelines: CodingGuidelines: a handful of error message guidelines

Makefile: allow "bin-wrappers/" directory to exist

2024-12-06T22:52:11Z

The "bin-wrappers/" directory gets created by our build system and is populated with one script for each of our binaries. There isn't anything inherently wrong with the current layout, but it is somewhat hard to adapt for out-of-tree build systems. Adapt the layout such that our "bin-wrappers/" directory always exists and contains our "wrap-for-bin.sh" script to make things a little bit easier for subsequent steps. Signed-off-by: Patrick Steinhardt Signed-off-by: Junio C Hamano

CodingGuidelines: a handful of error message guidelines

2024-11-29T01:36:06Z

It is more efficient to have something in the coding guidelines document to point at, when we want to review and comment on a new message in the codebase to make sure it "fits" in the set of existing messages. Let's write down established best practice we are aware of. Helped-by: Eric Sunshine Signed-off-by: Junio C Hamano

CodingGuidelines: discourage arbitrary suffixes in function names

2024-10-24T16:51:30Z

We often name functions with arbitrary suffixes like `_1` as an extension of another existing function. This creates confusion and doesn't provide good clarity into the functions purpose. Let's document good function naming etiquette in our CodingGuidelines. Signed-off-by: Karthik Nayak Signed-off-by: Taylor Blau

Merge branch 'ja/doc-synopsis-markup'

2024-10-10T21:22:24Z

The way AsciiDoc is used for SYNOPSIS part of the manual pages has been revamped. The sources, at least for the simple cases, got vastly pleasant to work with. * ja/doc-synopsis-markup: doc: apply synopsis simplification on git-clone and git-init doc: update the guidelines to reflect the current formatting rules doc: introduce a synopsis typesetting

doc: update the guidelines to reflect the current formatting rules

2024-09-24T17:20:25Z

Signed-off-by: Jean-Noël Avila Signed-off-by: Junio C Hamano

CodingGuidelines: also mention MAYBE_UNUSED

2024-08-29T18:28:07Z

A function that uses a parameter in one build may lose all uses of the parameter in another build, depending on the configuration. A workaround for such a case, MAYBE_UNUSED, should also be mentioned when we recommend the use of UNUSED to our developers. Keep the addition to the guideline short and document the criteria to choose between UNUSED and MAYBE_UNUSED near their definition. Signed-off-by: Junio C Hamano

CodingGuidelines: mention -Wunused-parameter and UNUSED

2024-08-28T16:51:25Z

Now that -Wunused-parameter is on by default for DEVELOPER=1 builds, people may trigger it, blocking their build. When it's a mistake for the parameter to exist, the path forward is obvious: remove it. But sometimes you need to suppress the warning, and the "UNUSED" mechanism for that is specific to our project, so people may not know about it. Let's put some advice in CodingGuidelines, including an example warning message. That should help people who grep for the warning text after seeing it from the compiler. Signed-off-by: Jeff King Signed-off-by: Junio C Hamano

Merge branch 'jc/coding-style-c-operator-with-spaces'

2024-08-26T18:32:24Z

Write down whitespacing rules around C opeators. * jc/coding-style-c-operator-with-spaces: CodingGuidelines: spaces around C operators