Re: [PATCH] MyFirstContribution: add tip for confirming patches reached the mailing list

From: Junio C Hamano <gitster@pobox.com>
Date: Oct 24, 2025, 16:02 UTC
Message-ID: <xmqqwm4kp9t7.fsf@gitster.g>
In-Reply-To: <20251024151532.1968-1-qjessa662@gmail.com>

QueenJcloud <qjessa662@gmail.com> writes:

> After explaining how to send patches using `git send-email`, add a helpful tip
> for contributors on how to confirm that their patches were successfully sent
> and appeared on the mailing list. This provides reassurance for newcomers and
> helps them verify their submission.

This is a bit wider than desirable; it will bust 80-column limit when quoted twice in a discussion thread.

> Signed-off-by: Queen Ediri Jessa <qjessa662@gmail.com>
> ---
>  Documentation/MyFirstContribution.adoc | 7 +++++++
>  1 file changed, 7 insertions(+)

We want to see that author identity and the identity on Sign-off match. I can tweak the author identity on our end for this patch, but if you are going to send further patches please make sure that your [user] name = "..." configuration is what you wrote on the Sign-off line.

Show 15 quoted lines

> diff --git a/Documentation/MyFirstContribution.adoc b/Documentation/MyFirstContribution.adoc
> index 02ba8ba5f6..94acdaeddd 100644
> --- a/Documentation/MyFirstContribution.adoc
> +++ b/Documentation/MyFirstContribution.adoc
> @@ -1158,6 +1158,13 @@ prompt for each patch that's about to go out. This gives you one last chance to
>  edit or quit sending something (but again, don't edit code this way). Once you
>  press `y` or `a` at these prompts your emails will be sent! Congratulations!
>  
> +[TIP]
> +====
> +After sending your patches, you can confirm that they reached the mailing list
> +by visiting https://lore.kernel.org/git/. Use the search bar to find your name
> +or the subject of your patch. If it appears, your email was successfully delivered.
> +====|
> +

Use of [TIP] is new (we seem to use only [NOTE] adminition blocks in the existing text). After reading the part before this hunk, the structure of the section is

    (title -- sending email)

    It's time to mail it out, with this command

    $ git send-email ...

    [note] ...
    [note] ...
    [note] ...

    After you run the command above, you will be presented with a prompt...

And you are adding a [tip] _after_ that, but the existing notes are also about tips to use "git send-email" correctly. It is not like existing explanation "After you run ..." is exactly correct. When you get prompted, the command hasn't finished running. It merely is "after you type the command and hit return".

I am tempted to move that "After you run..." sentence up and above these three [note] admonition blocks (and rephrase it a bit, perhaps with "After" -> "When"). Then add this new piece as the fourth [note].

What's the vertical bar "|" after the closing example block delimiter (i.e. the second "====")? I'll drop it as otherwise Asciidoctor complains

  asciidoctor: WARNING: MyFirstContribution.adoc: line 1162: unterminated admonition block

and makes the rest of the document part of this [TIP].

Thanks.