Subject: [PATCH] CodingGuidelines: document test balloons in flight

From: Junio C Hamano <[email-masked]>
Date: Wed, 23 Jul 2025 12:31:26 -0700

Due to portability concerns, we do not blindly say "It is in [[this
standard]], so we will make liberal use of it" for many features,
and use of C99 language features follow this same principle.  When
we contemplate adopting a language feature that we haven't used in
our codebase, we typically first raise a test balloon, which

 - is a piece of code that exercises the language feature we are
   trying to see if it is OK to adopt

 - is in a small section of code that we know everybody who cares
   about having a working Git must be compiling

 - is in a fairly stable part of the code, to allow reverting it
   easily if some platforms do not understand it yet.

After a few years, with no breakage report from the community, we'd
declare that the feature is now safe to use in our codebase.  Before
that, we forbid the use of the language construct except for the
designated test balloon code site.

The CodingGuidelines document lists these selected features that we
already have determined that they are safe, and also those features
that we know some platforms had trouble with.

Let's also start listing ongoing test balloons and expected timeline
for adoption.

Helped-by: Phillip Wood <[email-masked]>
Signed-off-by: Junio C Hamano <[email-masked]>
---
 Documentation/CodingGuidelines | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines
index c1046abfb7..0776d15a95 100644
--- a/Documentation/CodingGuidelines
+++ b/Documentation/CodingGuidelines
@@ -298,6 +298,14 @@ For C programs:
    . since late 2021 with 44ba10d6, we have had variables declared in
      the for loop "for (int i = 0; i < 10; i++)".
 
+   C99 features we have test balloons for:
+
+   . since late 2024 with v2.48.0-rc0~20, we have test balloons for
+     compound literal syntax, e.g., (struct foo){ .member = value };
+     our hope is that no platforms we care about have trouble using
+     them, and officially adopt its wider use in mid 2026.  Do not add
+     more use of the syntax until that happens.
+
    New C99 features that we cannot use yet:
 
    . %z and %zu as a printf() argument for a size_t (the %z being for
-- 
2.50.1-521-gf11ee0bd80