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

Philip Oakley <philipoakley@iee.email> writes:

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.