README.md: add CodingGuidelines and a link for Translators

[PhilipOakley]

Also space out the list joining instructions and clarify the subscription
via the majordomo address.

Signed-off-by: Philip Oakley philipoakley@iee.email

cc: Philip Oakley philipoakley@iee.email
cc: Junio C Hamano gitster@pobox.com
cc: Jiang Xin worldhello.net@gmail.com
cc: Bagas Sanjaya bagasdotme@gmail.com

changes since V2:

• extended the translation 'messages' description
• updated commit message based on Junio's suggestion

changes since v1:

• Used reference style links, rather than lnk style.

• added Jiang as L10 coordinator.

• note: Patch is a response to a user question on the "Git for Human Beings" git-users list
  https://groups.google.com/d/msgid/git-users/aa68b9c8-4cf4-4193-8af3-79d7e3feafbbn%40googlegroups.com

[gitgitgadget]

Welcome to GitGitGadget

Hi @PhilipOakley, and welcome to GitGitGadget, the GitHub App to send patch series to the Git mailing list from GitHub Pull Requests.

Please make sure that your Pull Request has a good description, as it will be used as cover letter.

Also, it is a good idea to review the commit messages one last time, as the Git project expects them in a quite specific form:

• the lines should not exceed 76 columns,
• the first line should be like a header and typically start with a prefix like "tests:" or "revisions:" to state which subsystem the change is about, and
• the commit messages' body should be describing the "why?" of the change.
• Finally, the commit messages should end in a Signed-off-by: line matching the commits' author.

It is in general a good idea to await the automated test ("Checks") in this Pull Request before contributing the patches, e.g. to avoid trivial issues such as unportable code.

Contributing the patches

Before you can contribute the patches, your GitHub username needs to be added to the list of permitted users. Any already-permitted user can do that, by adding a comment to your PR of the form /allow. A good way to find other contributors is to locate recent pull requests where someone has been /allowed:

• Search: is:pr is:open "/allow"

Both the person who commented /allow and the PR author are able to /allow you.

An alternative is the channel #git-devel on the Libera Chat IRC network:

<newcontributor> I've just created my first PR, could someone please /allow me? https://github.com/gitgitgadget/git/pull/12345
<veteran> newcontributor: it is done
<newcontributor> thanks!

Once on the list of permitted usernames, you can contribute the patches to the Git mailing list by adding a PR comment /submit.

If you want to see what email(s) would be sent for a /submit request, add a PR comment /preview to have the email(s) sent to you. You must have a public GitHub email address for this.

After you submit, GitGitGadget will respond with another comment that contains the link to the cover letter mail in the Git mailing list archive. Please make sure to monitor the discussion in that thread and to address comments and suggestions (while the comments and suggestions will be mirrored into the PR by GitGitGadget, you will still want to reply via mail).

If you do not want to subscribe to the Git mailing list just to be able to respond to a mail, you can download the mbox from the Git mailing list archive (click the (raw) link), then import it into your mail program. If you use GMail, you can do this via:

curl -g --user "<EMailAddress>:<Password>" \
    --url "imaps://imap.gmail.com/INBOX" -T /path/to/raw.txt

To iterate on your change, i.e. send a revised patch or patch series, you will first want to (force-)push to the same branch. You probably also want to modify your Pull Request description (or title). It is a good idea to summarize the revision by adding something like this to the cover letter (read: by editing the first comment on the PR, i.e. the PR description):

Changes since v1:
- Fixed a typo in the commit message (found by ...)
- Added a code comment to ... as suggested by ...
...

To send a new iteration, just add another PR comment with the contents: /submit.

Need help?

New contributors who want advice are encouraged to join git-mentoring@googlegroups.com, where volunteers who regularly contribute to Git are willing to answer newbie questions, give advice, or otherwise provide mentoring to interested contributors. You must join in order to post or view messages, but anyone can join.

You may also be able to find help in real time in the developer IRC channel, #git-devel on Libera Chat. Remember that IRC does not support offline messaging, so if you send someone a private message and log out, they cannot respond to you. The scrollback of #git-devel is archived, though.

[dscho]

/allow

[gitgitgadget]

User PhilipOakley is now allowed to use GitGitGadget.

WARNING: PhilipOakley has no public email address set on GitHub

[PhilipOakley]

Is the freebsd_12 job expected to fail for a simple text update to the README.md?

The update came about because of a comment on the git-users list https://groups.google.com/g/git-users/c/IH7p_KGpr0I/m/fKOXAkOJBQAJ

[PhilipOakley]

looks like the freebsd problem is being discussed on the list https://lore.kernel.org/git/YeDUA6NhHuCUkqXf@camp.crustytoothpaste.net

/allow

[PhilipOakley]

/submit

removed the excess verbiage after the sign-off, and used the right action word..

[gitgitgadget]

Error: /submit does not accept arguments ('removed the excess verbiage after the sign-off, and used the right action word..')

[PhilipOakley]

/submit

[gitgitgadget]

Submitted as pull.1115.git.1642182615339.gitgitgadget@gmail.com

To fetch this version into FETCH_HEAD:

git fetch https://github.com/gitgitgadget/git pr-1115/PhilipOakley/Readme-v1

To fetch this version to local tag pr-1115/PhilipOakley/Readme-v1:

git fetch --no-tags https://github.com/gitgitgadget/git tag pr-1115/PhilipOakley/Readme-v1

[gitgitgadget]

On the Git mailing list, Junio C Hamano wrote (reply to this):

"Philip Oakley via GitGitGadget" <gitgitgadget@gmail.com> writes:

> From: Philip Oakley <philipoakley@iee.email>
>
> Also space out the list joining instructions and clarify the subscription

the instructions to join the list?

>  requests, comments and patches to git@vger.kernel.org (read
> -[Documentation/SubmittingPatches][] for instructions on patch submission).
> +[Documentation/SubmittingPatches][] for instructions on patch submission
> +and [Documentation/CodingGuidelines]() ).

Remind me the significance of using [] and () after [File Reference]?

> +Those wishing to help with error message translation (localization L10)
> +should see [po/README.md]()

Same here.

https://docs.github.com/en/github/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#links

seems to indicate () is to enclose URL the text goes to, and if
there is no URL to go to, perhaps it does the right thing, but the
current page (which has "[Documentation/SubmittingPatches][]" and
all other reference into in-tree files with that format) seems to
render correctly with links that work, so...

> +(a `po` file is a portable object file for the translations).
> +
>  To subscribe to the list, send an email with just "subscribe git" in
> -the body to majordomo@vger.kernel.org. The mailing list archives are
> -available at <https://lore.kernel.org/git/>,
> +the body to majordomo@vger.kernel.org (not the list). The mailing list
> +archives are available at <https://lore.kernel.org/git/>,
>  <http://marc.info/?l=git> and other archival sites.
>  
>  Issues which are security relevant should be disclosed privately to
>
> base-commit: 1ffcbaa1a5f10c9f706314d77f88de20a4a498c2

[gitgitgadget]

On the Git mailing list, Philip Oakley wrote (reply to this):

On 14/01/2022 20:54, Junio C Hamano wrote:
> "Philip Oakley via GitGitGadget" <gitgitgadget@gmail.com> writes:
>
>> From: Philip Oakley <philipoakley@iee.email>
>>
>> Also space out the list joining instructions and clarify the subscription
> the instructions to join the list?
Correct.
>
>>  requests, comments and patches to git@vger.kernel.org (read
>> -[Documentation/SubmittingPatches][] for instructions on patch submission).
>> +[Documentation/SubmittingPatches][] for instructions on patch submission
>> +and [Documentation/CodingGuidelines]() ).
> Remind me the significance of using [] and () after [File Reference]?
The [] is the original method used by the unchanged text, while the ()
appears to be the method required now.
 
>
>> +Those wishing to help with error message translation (localization L10)
>> +should see [po/README.md]()
> Same here.
>
> https://docs.github.com/en/github/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#links
>
> seems to indicate () is to enclose URL the text goes to, and if
> there is no URL to go to, perhaps it does the right thing, but the
> current page (which has "[Documentation/SubmittingPatches][]" and
> all other reference into in-tree files with that format) seems to
> render correctly with links that work, so...

Unfortunately it `[]` is not working for me for the new additions.
GitHub magic?
>
>> +(a `po` file is a portable object file for the translations).
>> +
>>  To subscribe to the list, send an email with just "subscribe git" in
>> -the body to majordomo@vger.kernel.org. The mailing list archives are
>> -available at <https://lore.kernel.org/git/>,
>> +the body to majordomo@vger.kernel.org (not the list). The mailing list
>> +archives are available at <https://lore.kernel.org/git/>,
>>  <http://marc.info/?l=git> and other archival sites.
>>  
>>  Issues which are security relevant should be disclosed privately to
>>
>> base-commit: 1ffcbaa1a5f10c9f706314d77f88de20a4a498c2

[gitgitgadget]

User Philip Oakley <philipoakley@iee.email> has been added to the cc: list.

[gitgitgadget]

On the Git mailing list, Junio C Hamano wrote (reply to this):

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.

[PhilipOakley]

On 15/01/2022 00:50, gitgitgadget[bot] wrote: On the Git mailing list ***@***.***>, Junio C Hamano wrote (reply to this <https://github.com/gitgitgadget/gitgitgadget/wiki/ReplyToThis>): Philip Oakley ***@***.***> 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.

GitHub will auto render the README.md at the bottom of the git.git home page, and will render any .md files when they are visited. I just checked GitLab which looks to do the same rendering. I prepared the changes because of a user question on the "Git for Human Beings" git-users list https://groups.google.com/d/msgid/git-users/aa68b9c8-4cf4-4193-8af3-79d7e3feafbbn%40googlegroups.com about some linter issues with C99 and an offer to help. Despite having answered such questions before it still took a while to find the right pointers for the user, hence the proposed clarifications.

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.

Oddly it appears that the [] was only working for the original text, but that () was needed for my new text. I'm not able to explain why, but didn't want too much churn within the patch.

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.

Already been there. GitHub would only render the old text as links when I pushed to my repo and viewed the README.md in my browser, so 2/2 would need to go first, but without any obvious need... I was hoping someone might know why? It feels very screwy to me.

[dscho]

On 15/01/2022 00:50, gitgitgadget[bot] wrote: On the Git mailing list @.>, Junio C Hamano wrote (reply to this https://github.com/gitgitgadget/gitgitgadget/wiki/ReplyToThis): Philip Oakley @.> 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.
GitHub will auto render the README.md at the bottom of the git.git home page, and will render any .md files when they are visited. I just checked GitLab which looks to do the same rendering. I prepared the changes because of a user question on the "Git for Human Beings" git-users list https://groups.google.com/d/msgid/git-users/aa68b9c8-4cf4-4193-8af3-79d7e3feafbbn%40googlegroups.com about some linter issues with C99 and an offer to help. Despite having answered such questions before it still took a while to find the right pointers for the user, hence the proposed clarifications.
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.
Oddly it appears that the [] was only working for the original text, but that () was needed for my new text. I'm not able to explain why, but didn't want too much churn within the patch.
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.
Already been there. GitHub would only render the old text as links when I pushed to my repo and viewed the README.md in my browser, so 2/2 would need to go first, but without any obvious need... I was hoping someone might know why? It feels very screwy to me.

Please reply on list.

[PhilipOakley]

/submit

[gitgitgadget]

Submitted as pull.1115.v2.git.1642349490723.gitgitgadget@gmail.com

To fetch this version into FETCH_HEAD:

git fetch https://github.com/gitgitgadget/git pr-1115/PhilipOakley/Readme-v2

To fetch this version to local tag pr-1115/PhilipOakley/Readme-v2:

git fetch --no-tags https://github.com/gitgitgadget/git tag pr-1115/PhilipOakley/Readme-v2

[gitgitgadget]

On the Git mailing list, Junio C Hamano wrote (reply to this):

"Philip Oakley via GitGitGadget" <gitgitgadget@gmail.com> writes:

> From: Philip Oakley <philipoakley@iee.email>
>
> The README.md does not use the GitHub Markdown URL links [1] of
> [txt](url), rather the reference method [2] of trailing empty square
> brackets. The references themselves are listed at the foot of the
> document. Those footers are not shown by GitHub/GitLab rendering.

Thanks for tracking down the differences.

The above only describes what we could do (i.e. use links instead of
reference), and how the current document is rendered (i.e. footers
are not shown).  No changes come from the above description.

> Also space out the list joining instructions and clarify that
> subscription is via the majordomo address.

So, seeing "Also" immediately after a paragraph that explains the
status quo confused me a lot.

"Spell out the instructions to join the list, and clarify that the
subscription is via the majordomo address" is indeed a part of what
this patch does.  Perhaps we need a separate paragraph _before_ this
"Also".

So taking all together

    Before being told how to submit patches, new contributors need
    to be told how to code for, or how to contribute translation to,
    the project.  Add references to the CodingGuidelines and the
    README document on localization.

    Also, spell out the instructions to join the list and ...
    
    We use GitHub Markdown reference [2] with trailing empty square
    brackets, to match existing text in the file.  On GitHub/GitLab
    pages, these references are not shown on the page, but it is OK
    because they are empty.  We could switch to using [text](url)
    form [1] if we wanted to, but that is not done as part of this
    patch.

would be the presentation order that I would expect to be the most
readable.  I moved the discussion between URL link and reference, as
it is merely a hint for future and not the core thing that needs to
be explained to understand the changes in this commit.

Thanks.


> [1] https://docs.github.com/en/github/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#links
> [2] https://gist.github.com/ChrisTollefson/a3af6d902a74a0afd1c2d79aadc9bb3f#reference-links
>
> Signed-off-by: Philip Oakley <philipoakley@iee.email>
> ---
>     README.md: add CodingGuidelines and a link for Translators
>     
>     Also space out the list joining instructions and clarify the
>     subscription via the majordomo address.
>     
>     
>     Signed-off-by: Philip Oakley philipoakley@iee.email
>     ===================================================
>     
>     cc: Philip Oakley philipoakley@iee.email cc: Junio C Hamano
>     gitster@pobox.com cc: Jiang Xin worldhello.net@gmail.com
>     
>     changes since v1:
>     
>      * Used reference style links, rather than lnk [url] style.
>     
>      * added Jianf as L10 coordinator.
>     
>      * note: Patch is a response to a user question on the "Git for Human
>        Beings" git-users list
>        https://groups.google.com/d/msgid/git-users/aa68b9c8-4cf4-4193-8af3-79d7e3feafbbn%40googlegroups.com
>
> Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-1115%2FPhilipOakley%2FReadme-v2
> Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1115/PhilipOakley/Readme-v2
> Pull-Request: https://github.com/gitgitgadget/git/pull/1115
>
> Range-diff vs v1:
>
>  1:  ac6d0abbdde ! 1:  48cc30b7cc8 README.md: add CodingGuidelines and a link for Translators
>      @@ Metadata
>        ## Commit message ##
>           README.md: add CodingGuidelines and a link for Translators
>       
>      -    Also space out the list joining instructions and clarify the subscription
>      -    via the majordomo address.
>      +    The README.md does not use the GitHub Markdown URL links [1] of
>      +    [txt](url), rather the reference method [2] of trailing empty square
>      +    brackets. The references themselves are listed at the foot of the
>      +    document. Those footers are not shown by GitHub/GitLab rendering.
>      +
>      +    Also space out the list joining instructions and clarify that
>      +    subscription is via the majordomo address.
>      +
>      +    [1] https://docs.github.com/en/github/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#links
>      +    [2] https://gist.github.com/ChrisTollefson/a3af6d902a74a0afd1c2d79aadc9bb3f#reference-links
>       
>           Signed-off-by: Philip Oakley <philipoakley@iee.email>
>       
>      @@ README.md: installed).
>        requests, comments and patches to git@vger.kernel.org (read
>       -[Documentation/SubmittingPatches][] for instructions on patch submission).
>       +[Documentation/SubmittingPatches][] for instructions on patch submission
>      -+and [Documentation/CodingGuidelines]() ).
>      ++and [Documentation/CodingGuidelines][]).
>       +
>       +Those wishing to help with error message translation (localization L10)
>      -+should see [po/README.md]()
>      -+(a `po` file is a portable object file for the translations).
>      ++should see [po/README.md][] (a `po` file is a Portable Object file that
>      ++holds the translations).
>       +
>        To subscribe to the list, send an email with just "subscribe git" in
>       -the body to majordomo@vger.kernel.org. The mailing list archives are
>       -available at <https://lore.kernel.org/git/>,
>      -+the body to majordomo@vger.kernel.org (not the list). The mailing list
>      -+archives are available at <https://lore.kernel.org/git/>,
>      ++the body to majordomo@vger.kernel.org (not the Git list). The mailing
>      ++list archives are available at <https://lore.kernel.org/git/>,
>        <http://marc.info/?l=git> and other archival sites.
>        
>        Issues which are security relevant should be disclosed privately to
>      +@@ README.md: and the name as (depending on your mood):
>      + [Documentation/giteveryday.txt]: Documentation/giteveryday.txt
>      + [Documentation/gitcvs-migration.txt]: Documentation/gitcvs-migration.txt
>      + [Documentation/SubmittingPatches]: Documentation/SubmittingPatches
>      ++[Documentation/CodingGuidelines]: Documentation/CodingGuidelines
>      ++[po/README.md]: po/README.md
>      + \ No newline at end of file
>
>
>  README.md | 14 +++++++++++---
>  1 file changed, 11 insertions(+), 3 deletions(-)
>
> diff --git a/README.md b/README.md
> index f6f43e78deb..d2b061e3998 100644
> --- a/README.md
> +++ b/README.md
> @@ -32,10 +32,16 @@ installed).
>  The user discussion and development of Git take place on the Git
>  mailing list -- everyone is welcome to post bug reports, feature
>  requests, comments and patches to git@vger.kernel.org (read
> -[Documentation/SubmittingPatches][] for instructions on patch submission).
> +[Documentation/SubmittingPatches][] for instructions on patch submission
> +and [Documentation/CodingGuidelines][]).
> +
> +Those wishing to help with error message translation (localization L10)
> +should see [po/README.md][] (a `po` file is a Portable Object file that
> +holds the translations).
> +
>  To subscribe to the list, send an email with just "subscribe git" in
> -the body to majordomo@vger.kernel.org. The mailing list archives are
> -available at <https://lore.kernel.org/git/>,
> +the body to majordomo@vger.kernel.org (not the Git list). The mailing
> +list archives are available at <https://lore.kernel.org/git/>,
>  <http://marc.info/?l=git> and other archival sites.
>  
>  Issues which are security relevant should be disclosed privately to
> @@ -64,3 +70,5 @@ and the name as (depending on your mood):
>  [Documentation/giteveryday.txt]: Documentation/giteveryday.txt
>  [Documentation/gitcvs-migration.txt]: Documentation/gitcvs-migration.txt
>  [Documentation/SubmittingPatches]: Documentation/SubmittingPatches
> +[Documentation/CodingGuidelines]: Documentation/CodingGuidelines
> +[po/README.md]: po/README.md
> \ No newline at end of file
>
> base-commit: 1ffcbaa1a5f10c9f706314d77f88de20a4a498c2

[gitgitgadget]

On the Git mailing list, Bagas Sanjaya wrote (reply to this):

On 16/01/22 23.11, Philip Oakley via GitGitGadget wrote:
> +Those wishing to help with error message translation (localization L10)
> +should see [po/README.md][] (a `po` file is a Portable Object file that
> +holds the translations).
> +

I mean not just error messages are in po/*.po, but also usage and informational
strings. We can say "Those wishing to help translating message strings
(localization or l10n)...".

-- 
An old man doll... just what I always wanted! - Clara

[gitgitgadget]

User Bagas Sanjaya <bagasdotme@gmail.com> has been added to the cc: list.

[gitgitgadget]

On the Git mailing list, Philip Oakley wrote (reply to this):

On 17/01/2022 09:00, Bagas Sanjaya wrote:
> On 16/01/22 23.11, Philip Oakley via GitGitGadget wrote:
>> +Those wishing to help with error message translation (localization L10)
>> +should see [po/README.md][] (a `po` file is a Portable Object file that
>> +holds the translations).
>> +
>
> I mean not just error messages are in po/*.po, but also usage and
> informational
> strings. We can say "Those wishing to help translating message strings
> (localization or l10n)...".
>
Thanks, I've expended the README description.

Philip

[gitgitgadget]

User Philip Oakley <philipoakley@iee.email> has been added to the cc: list.

[gitgitgadget]

On the Git mailing list, Philip Oakley wrote (reply to this):

On 16/01/2022 22:47, Junio C Hamano wrote:
> "Philip Oakley via GitGitGadget" <gitgitgadget@gmail.com> writes:
>
>> From: Philip Oakley <philipoakley@iee.email>
>>
>> The README.md does not use the GitHub Markdown URL links [1] of
>> [txt](url), rather the reference method [2] of trailing empty square
>> brackets. The references themselves are listed at the foot of the
>> document. Those footers are not shown by GitHub/GitLab rendering.
> Thanks for tracking down the differences.
I found an additional GitHub link for the reference method (not easy to
find), which I have added.
>
> The above only describes what we could do (i.e. use links instead of
> reference), and how the current document is rendered (i.e. footers
> are not shown).  No changes come from the above description.
>
>> Also space out the list joining instructions and clarify that
>> subscription is via the majordomo address.
> So, seeing "Also" immediately after a paragraph that explains the
> status quo confused me a lot.
>
> "Spell out the instructions to join the list, and clarify that the
> subscription is via the majordomo address" is indeed a part of what
> this patch does.  Perhaps we need a separate paragraph _before_ this
> "Also".
>
> So taking all together
>
>     Before being told how to submit patches, new contributors need
>     to be told how to code for, or how to contribute translation to,
>     the project.  Add references to the CodingGuidelines and the
>     README document on localization.
>
>     Also, spell out the instructions to join the list and ...
>     
>     We use GitHub Markdown reference [2] with trailing empty square
>     brackets, to match existing text in the file.  On GitHub/GitLab
>     pages, these references are not shown on the page, but it is OK
>     because they are empty.  We could switch to using [text](url)
>     form [1] if we wanted to, but that is not done as part of this
>     patch.
>
> would be the presentation order that I would expect to be the most
> readable.  I moved the discussion between URL link and reference, as
> it is merely a hint for future and not the core thing that needs to
> be explained to understand the changes in this commit.
I've taken your suggestions and added a small clarification about the
awkward empty square bracket links, which are repeated in the README's
footer, but not shown on the Github rendered web page.. I also took
Bagas' text changes for the readme itself

GGG V3 to follow,...

Thank you
>
> Thanks.
>
>
>> [1] https://docs.github.com/en/github/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#links
>> [2] https://gist.github.com/ChrisTollefson/a3af6d902a74a0afd1c2d79aadc9bb3f#reference-links
>>
>> Signed-off-by: Philip Oakley <philipoakley@iee.email>
>> ---
>>     README.md: add CodingGuidelines and a link for Translators
>>     
>>     Also space out the list joining instructions and clarify the
>>     subscription via the majordomo address.
>>     
>>     
>>     Signed-off-by: Philip Oakley philipoakley@iee.email
>>     ===================================================
>>     
>>     cc: Philip Oakley philipoakley@iee.email cc: Junio C Hamano
>>     gitster@pobox.com cc: Jiang Xin worldhello.net@gmail.com
>>     
>>     changes since v1:
>>     
>>      * Used reference style links, rather than lnk [url] style.
>>     
>>      * added Jianf as L10 coordinator.
>>     
>>      * note: Patch is a response to a user question on the "Git for Human
>>        Beings" git-users list
>>        https://groups.google.com/d/msgid/git-users/aa68b9c8-4cf4-4193-8af3-79d7e3feafbbn%40googlegroups.com
>>
>> Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-1115%2FPhilipOakley%2FReadme-v2
>> Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1115/PhilipOakley/Readme-v2
>> Pull-Request: https://github.com/gitgitgadget/git/pull/1115
>>
>> Range-diff vs v1:
>>
>>  1:  ac6d0abbdde ! 1:  48cc30b7cc8 README.md: add CodingGuidelines and a link for Translators
>>      @@ Metadata
>>        ## Commit message ##
>>           README.md: add CodingGuidelines and a link for Translators
>>       
>>      -    Also space out the list joining instructions and clarify the subscription
>>      -    via the majordomo address.
>>      +    The README.md does not use the GitHub Markdown URL links [1] of
>>      +    [txt](url), rather the reference method [2] of trailing empty square
>>      +    brackets. The references themselves are listed at the foot of the
>>      +    document. Those footers are not shown by GitHub/GitLab rendering.
>>      +
>>      +    Also space out the list joining instructions and clarify that
>>      +    subscription is via the majordomo address.
>>      +
>>      +    [1] https://docs.github.com/en/github/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#links
>>      +    [2] https://gist.github.com/ChrisTollefson/a3af6d902a74a0afd1c2d79aadc9bb3f#reference-links
>>       
>>           Signed-off-by: Philip Oakley <philipoakley@iee.email>
>>       
>>      @@ README.md: installed).
>>        requests, comments and patches to git@vger.kernel.org (read
>>       -[Documentation/SubmittingPatches][] for instructions on patch submission).
>>       +[Documentation/SubmittingPatches][] for instructions on patch submission
>>      -+and [Documentation/CodingGuidelines]() ).
>>      ++and [Documentation/CodingGuidelines][]).
>>       +
>>       +Those wishing to help with error message translation (localization L10)
>>      -+should see [po/README.md]()
>>      -+(a `po` file is a portable object file for the translations).
>>      ++should see [po/README.md][] (a `po` file is a Portable Object file that
>>      ++holds the translations).
>>       +
>>        To subscribe to the list, send an email with just "subscribe git" in
>>       -the body to majordomo@vger.kernel.org. The mailing list archives are
>>       -available at <https://lore.kernel.org/git/>,
>>      -+the body to majordomo@vger.kernel.org (not the list). The mailing list
>>      -+archives are available at <https://lore.kernel.org/git/>,
>>      ++the body to majordomo@vger.kernel.org (not the Git list). The mailing
>>      ++list archives are available at <https://lore.kernel.org/git/>,
>>        <http://marc.info/?l=git> and other archival sites.
>>        
>>        Issues which are security relevant should be disclosed privately to
>>      +@@ README.md: and the name as (depending on your mood):
>>      + [Documentation/giteveryday.txt]: Documentation/giteveryday.txt
>>      + [Documentation/gitcvs-migration.txt]: Documentation/gitcvs-migration.txt
>>      + [Documentation/SubmittingPatches]: Documentation/SubmittingPatches
>>      ++[Documentation/CodingGuidelines]: Documentation/CodingGuidelines
>>      ++[po/README.md]: po/README.md
>>      + \ No newline at end of file
>>
>>
>>  README.md | 14 +++++++++++---
>>  1 file changed, 11 insertions(+), 3 deletions(-)
>>
>> diff --git a/README.md b/README.md
>> index f6f43e78deb..d2b061e3998 100644
>> --- a/README.md
>> +++ b/README.md
>> @@ -32,10 +32,16 @@ installed).
>>  The user discussion and development of Git take place on the Git
>>  mailing list -- everyone is welcome to post bug reports, feature
>>  requests, comments and patches to git@vger.kernel.org (read
>> -[Documentation/SubmittingPatches][] for instructions on patch submission).
>> +[Documentation/SubmittingPatches][] for instructions on patch submission
>> +and [Documentation/CodingGuidelines][]).
>> +
>> +Those wishing to help with error message translation (localization L10)
>> +should see [po/README.md][] (a `po` file is a Portable Object file that
>> +holds the translations).
>> +
>>  To subscribe to the list, send an email with just "subscribe git" in
>> -the body to majordomo@vger.kernel.org. The mailing list archives are
>> -available at <https://lore.kernel.org/git/>,
>> +the body to majordomo@vger.kernel.org (not the Git list). The mailing
>> +list archives are available at <https://lore.kernel.org/git/>,
>>  <http://marc.info/?l=git> and other archival sites.
>>  
>>  Issues which are security relevant should be disclosed privately to
>> @@ -64,3 +70,5 @@ and the name as (depending on your mood):
>>  [Documentation/giteveryday.txt]: Documentation/giteveryday.txt
>>  [Documentation/gitcvs-migration.txt]: Documentation/gitcvs-migration.txt
>>  [Documentation/SubmittingPatches]: Documentation/SubmittingPatches
>> +[Documentation/CodingGuidelines]: Documentation/CodingGuidelines
>> +[po/README.md]: po/README.md
>> \ No newline at end of file
>>
>> base-commit: 1ffcbaa1a5f10c9f706314d77f88de20a4a498c2

[PhilipOakley]

/submit

[gitgitgadget]

Submitted as pull.1115.v3.git.1642443491609.gitgitgadget@gmail.com

To fetch this version into FETCH_HEAD:

git fetch https://github.com/gitgitgadget/git pr-1115/PhilipOakley/Readme-v3

To fetch this version to local tag pr-1115/PhilipOakley/Readme-v3:

git fetch --no-tags https://github.com/gitgitgadget/git tag pr-1115/PhilipOakley/Readme-v3

[gitgitgadget]

This patch series was integrated into seen via git@9abbe26.

[gitgitgadget]

This patch series was integrated into seen via git@5f01e81.

[gitgitgadget]

This patch series was integrated into seen via git@6986355.

[gitgitgadget]

This patch series was integrated into seen via git@132b131.

[gitgitgadget]

This patch series was integrated into next via git@7e14690.

[gitgitgadget]

There was a status update in the "New Topics" section about the branch po/readme-mention-contributor-hints on the Git mailing list:

Doc update.

Will cook in 'next'.
source: <pull.1115.v3.git.1642443491609.gitgitgadget@gmail.com>

[gitgitgadget]

This patch series was integrated into seen via git@8afe4b4.

[gitgitgadget]

This patch series was integrated into seen via git@f708437.

[gitgitgadget]

This patch series was integrated into seen via git@d3142c2.

[gitgitgadget]

There was a status update in the "Cooking" section about the branch po/readme-mention-contributor-hints on the Git mailing list:

Doc update.

Will cook in 'next'.
source: <pull.1115.v3.git.1642443491609.gitgitgadget@gmail.com>

[gitgitgadget]

This patch series was integrated into seen via git@6008a26.

[gitgitgadget]

This patch series was integrated into seen via git@9a8de39.

[gitgitgadget]

This patch series was integrated into seen via git@93a30bd.

[gitgitgadget]

There was a status update in the "Cooking" section about the branch po/readme-mention-contributor-hints on the Git mailing list:

Doc update.

Will cook in 'next'.
source: <pull.1115.v3.git.1642443491609.gitgitgadget@gmail.com>

[gitgitgadget]

This patch series was integrated into seen via git@0645a4d.

[gitgitgadget]

This patch series was integrated into seen via git@cb14059.

[gitgitgadget]

This patch series was integrated into seen via git@5d8730a.

[gitgitgadget]

This patch series was integrated into seen via git@6d58801.

[gitgitgadget]

This patch series was integrated into seen via git@f01d91d.

[gitgitgadget]

There was a status update in the "Cooking" section about the branch po/readme-mention-contributor-hints on the Git mailing list:

Doc update.

Will merge to 'master'.
source: <pull.1115.v3.git.1642443491609.gitgitgadget@gmail.com>

[gitgitgadget]

This patch series was integrated into seen via git@3ca33f2.

[gitgitgadget]

This patch series was integrated into seen via git@643cab8.

[gitgitgadget]

This patch series was integrated into seen via git@1a63afa.

[gitgitgadget]

This patch series was integrated into seen via git@2981dbe.

[gitgitgadget]

This patch series was integrated into next via git@2981dbe.

[gitgitgadget]

This patch series was integrated into master via git@2981dbe.

[gitgitgadget]

Closed via 2981dbe.