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

[Junio C Hamano <gitster@pobox.com>]

Shreyansh Paliwal <shreyanshpaliwalcmsmn@gmail.com> writes:

> 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???

>
> * 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.

>  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.