Re: [PATCH] doc: MyFirstContribution: fix missing dependencies and clarify build steps

From: Junio C Hamano <gitster@pobox.com>
Date: Jan 12, 2026, 14:34 UTC
Message-ID: <xmqqcy3eoq6e.fsf@gitster.g>
In-Reply-To: <20260112094030.314203-1-shreyanshpaliwalcmsmn@gmail.com>

Shreyansh Paliwal <shreyanshpaliwalcmsmn@gmail.com> writes:

Show 7 quoted lines

> Fix several issues in the MyFirstContribution guide that can lead to
> confusion or test failures when following the documented steps.
>
> * Add missing header includes in code examples (environment.h and
> strbuf.h).
>
> *  correct manpage synopsis formatting to prevent failing documentation tests.

Two spaces???

Show 25 quoted lines

>
> * clarify documentation build prerequisites, particularly specifying for DocBook-XSL.
>
> * specify the use of parallel test execution with -j$(nproc), noting that
> it runs tests using all available CPUs and may be adjusted.
>
> These updates improve accuracy and make the first-time contributor
> journey smoother.
>
> Signed-off-by: Shreyansh Paliwal <shreyanshpaliwalcmsmn@gmail.com>
> ---
>  Documentation/MyFirstContribution.adoc | 15 +++++++++------
>  1 file changed, 9 insertions(+), 6 deletions(-)
>
> diff --git a/Documentation/MyFirstContribution.adoc b/Documentation/MyFirstContribution.adoc
> index f186dfbc89..38f2a23e77 100644
> --- a/Documentation/MyFirstContribution.adoc
> +++ b/Documentation/MyFirstContribution.adoc
> @@ -331,7 +331,8 @@ on the command line, including the name of our command. (If `prefix` is empty
>  for you, try `cd Documentation/ && ../bin-wrappers/git psuh`). That's not so
>  helpful. So what other context can we get?
>  
> -Add a line to `#include "config.h"` and `#include "repository.h"`.
> +Add a line to `#include "config.h"`, `#include "repository.h"` and
> +`#include "environment.h"`.

Good.

Show 17 quoted lines

>  Then, add the following bits to the function body:
>  function body:
>  
> @@ -429,6 +430,7 @@ Add the following includes:
>  ----
>  #include "commit.h"
>  #include "pretty.h"
> +#include "strbuf.h"
>  ----
>  
>  Then, add the following lines within your implementation of `cmd_psuh()` near
> @@ -504,7 +506,7 @@ git-psuh - Delight users' typo with a shy horse
>  SYNOPSIS
>  --------
>  [verse]
> -'git-psuh [<arg>...]'
> +git psuh [<arg>...]

Removing "-" does make sense but did you really want to remove the quotes around the command? If you are moving to the [synopsis] style from [verse] (*), it may make sense, but otherwise...?

    Side note: see de56e1d7 (Merge branch
    'ja/doc-commit-markup-updates', 2025-01-29) for example.

>  NOTE: Before trying to build the docs, make sure you have the package `asciidoc`
> -installed.
> +and `docbook-xsl` installed. See `INSTALL` for details.

I suspect this is highly distribution specific. The asciidoc package is typically packaged to depend on or suggest the docbook toolchain including docbook-xsl, and if we start adding more "to help newbies", we'd face the problem of "where would we stop?". For example, on Debian derived systems, the docbook-xsl package typicallly depends on the xml-core package---should we also list it?

I personally find that stopping at asciidoc and let the user deal with their platform convention to get asciidoc working, like the current documentation does, draws the line better than the above updated text.