Subject: Re: [PATCH] Add a comment to .clang-format about the meaning of the file

From: Junio C Hamano <[email-masked]>
Date: Sun, 01 Oct 2017 11:45:21 +0900

Stephan Beyer <[email-masked]> writes:

> Having a .clang-format file in a project can be understood in a way that code
> has to be in the style defined by the .clang-format file, i.e., you just have
> to run clang-format over all code and you are set. This is not the case in the
> Git project, which is now reflected by an comment in the beginning of the file.
>
> Additionally, the working clang-format version is mentioned because the config
> directives change from time to time (in a compatibility-breaking way).
>
> Signed-off-by: Stephan Beyer <[email-masked]>
> ---
>
> Notes:
>     On 09/30/2017 12:45 AM, Jonathan Nieder wrote:
>     > Sounds good to me.  Care to send it as a patch? :)
>     
>     Like this? :)
>
>  .clang-format | 6 +++++-
>  1 file changed, 5 insertions(+), 1 deletion(-)
>
> diff --git a/.clang-format b/.clang-format
> index 3ede2628d..558fc7fd8 100644
> --- a/.clang-format
> +++ b/.clang-format
> @@ -1,4 +1,8 @@
> -# Defaults
> +# This file is an example configuration for clang-format 5.0.
> +#
> +# Note that this style definition should only be understood as a hint
> +# for writing new code. Most of Git's codebase does not conform to
> +# this definition.

I think this makes 50%-80% sense.  As we have just seen in the patch
that started this thread, the rules currently in this file is known
not to be perfect (and I do not think the patch was meant to make,
or claimed that it has made, the rules perfect---it was to fix the
most problematic part that was observed and is a good incremental
improvement), so we should treat it as such.  "does not conform to"
does not convey that--it makes as if a random patch to "make it
conform" without thinking if the rules make sense were a welcome
addition, which is absolutely the last signal we would want to send
to the readers.