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

From: Pushkar Singh <pushkarkumarsingh1970@gmail.com>
Date: Jan 12, 2026, 12:55 UTC
Message-ID: <CALE2CrTuZkFm1R3Bb6gFmrN1trr88vdO_7Aw6ycBYvFpWMEEtA@mail.gmail.com>
In-Reply-To: <20260112094030.314203-1-shreyanshpaliwalcmsmn@gmail.com>

Hi Shreyansh,

Thanks for working on this. I have been going through MyFirstContribution myself and a lot of these changes match issues I actually hit while setting things up.

The extra includes like environment.h and strbuf.h make sense. I also ran into build problems when those were missing in the examples. Fixing the git psuh synopsis is a good catch too since it breaks the manpage tests otherwise.

The note about needing docbook-xsl along with asciidoc is especially helpful. That is something I had to figure out the hard way when trying to build the docs.

One small thing I wondered about is the prove -j$(nproc) note. It might be worth mentioning that using all CPUs can make failures harder to read for beginners, so starting without it could be easier. Not a big deal, just a thought.

Overall this looks like a nice improvement for new contributors.

Best, Pushkar

On Mon, Jan 12, 2026 at 3:10 PM Shreyansh Paliwal <shreyanshpaliwalcmsmn@gmail.com> wrote:

Show 80 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.
>
> * 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"`.
>  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>...]
>
>  DESCRIPTION
>  -----------
> @@ -531,7 +533,7 @@ easier for your user, who can skip to the section they know contains the
>  information they need.
>
>  NOTE: Before trying to build the docs, make sure you have the package `asciidoc`
> -installed.
> +and `docbook-xsl` installed. See `INSTALL` for details.
>
>  Now that you've written your manpage, you'll need to build it explicitly. We
>  convert your AsciiDoc to troff which is man-readable like so:
> @@ -726,9 +728,10 @@ $ prove -j$(nproc) --shuffle t[0-9]*.sh
>  ----
>
>  NOTE: You can also do this with `make test` or use any testing harness which can
> -speak TAP. `prove` can run concurrently. `shuffle` randomizes the order the
> -tests are run in, which makes them resilient against unwanted inter-test
> -dependencies. `prove` also makes the output nicer.
> +speak TAP. `prove` can run concurrently. `-j$(nproc)` runs tests using all
> +available CPUs in parallel, but the job count can be adjusted as needed.
> +`shuffle` randomizes the order the tests are run in, which makes them resilient
> +against unwanted inter-test dependencies. `prove` also makes the output nicer.
>
>  Go ahead and commit this change, as well.
>
> --
> 2.43.0
>
>