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

From: Junio C Hamano <gitster@pobox.com>
To: Philip Oakley <philipoakley@iee.email>
Cc: Philip Oakley via GitGitGadget <gitgitgadget@gmail.com>,
	git@vger.kernel.org
Subject: Re: [PATCH] README.md: add CodingGuidelines and a link for Translators
Date: Fri, 14 Jan 2022 16:47:28 -0800	[thread overview]
Message-ID: <xmqqv8yl6d0f.fsf@gitster.g> (raw)
In-Reply-To: <6b626f9d-05d6-1903-0b38-e3566e357472@iee.email> (Philip Oakley's message of "Sat, 15 Jan 2022 00:08:05 +0000")

Philip Oakley <philipoakley@iee.email> 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.