Subject: Re: [PATCH] README.md: add CodingGuidelines and a link for Translators

From: Junio C Hamano <[email-masked]>
Date: Fri, 14 Jan 2022 16:47:28 -0800

Philip Oakley <[email-masked]> writes:

> Unfortunately it `[]` is not working for me for the new additions.
> GitHub magic?

Let's step back a bit.

Is there somebody reading README.md as a more generic MarkDown?  I
do not think our build procedure creates any rendered document from
it.

My recollection was that we moved from README.txt to README.md for
the sole purpose of showing it https://github.com/git/git/ as more
than just a plain text, so it is a hard requirement that GitHub
flavored MarkDown renderer is happy with whatever we write in the
file.

If GitHub flavored MarkDown only supports [] and breaks with (),
then there is no need for further discussion.  We must stick to []
that has been working for us in the file.

On the other hand, if both () and [] work well at GitHub, I am OK to
replace [] to (), so that it shows well at GitHub and also it can be
used with other MarkDown renderers.

I prefer, from the organizational point of view, to see two patches,
in this order, if we were to go that way.

 [PATCH 1/2] README: link to more contributor documents

which uses [] (not ()).  After this, README.md uses only [],
including the two links you add in this step.  And then

 [PATCH 2/2] README: use "()", not "[]", to please more MarkDown processors

which replaces all uses of [] with ().

That would allow us to queue both, try them out, and we can back out
[2/2] if GitHub's renderer does not like the result.