[PATCH] Documentation/MyFirstContribution: add missing dependencies and clarify build steps

[PATCH] Documentation/MyFirstContribution: add missing dependencies and clarify build steps

[Shreyansh Paliwal]

Fix issues in the MyFirstContribution guide that can lead to
confusion or failiure 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,
including the AsciiDoc and DocBook-XSL stylesheets, 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
experience 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

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

[Shreyansh Paliwal]

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

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

[Pushkar Singh]

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

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

[Shreyansh Paliwal]

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

Actually, I included this mainly to make sure readers understand the purpose
of -j$(nproc) in the command. The motivation for adding the note came from 
my own experience, where I ran the tests with this and it saturated my system
resources and interfered with other important processes, which led me to
reduce the parallel job count.

As for the difficulty that beginners may face when reading failures,
my expectation was that users could either trace failures using the summary
shown at the end of the test run or adjust the level of parallelism based
on the note, rather than starting without parallelism altogether,
which can significantly increase test runtime.

Best,
Shreyansh

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

[Junio C Hamano]

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.

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

[Shreyansh Paliwal]

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #1: Type: text/plain; charset=y, Size: 2950 bytes --]

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

Sorry, my bad. Will fix it in v2.

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

Actually, I initially kept the quotes, but the test that checks consistency between
the manpage synopsis and the -h output was still failing. At that point, my intention
was to switch to the [synopsis] style, so I removed the quotes, but I missed updating
the markup from [verse] to [synopsis].
Will fix this as well in v2.

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

I totally agree with the “where would we stop?” concern, that is also
why I intentionally avoided calling out Windows or any linux-distro
specific details elsewhere in the document.

My thinking here was that docbook-xsl felt more like a peer dependency
to asciidoc rather than a deeper, transitive one (like xml-core),
especially since it is explicitly mentioned in INSTALL doc.

An alternative could be to keep it less concrete and say something like

	“make sure you have the `asciidoc` installed along with the
	 required docbook toolchain. Refer INSTALL for details”

Please let me know what would be the appropriate approach with this.

Best,
Shreyansh

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

[Junio C Hamano]

Shreyansh Paliwal <shreyanshpaliwalcmsmn@gmail.com> writes:

>> 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.
> ...
> Please let me know what would be the appropriate approach with this.

Again, I personally find that stopping at asciidoc and letting the
user deal with their platform convention to get asciidoc working,
like the current documentation does, draws the line better.

If we are not mentioning to check INSTALL elsewhere in the
instruction, we probably should, and the place where we mention what
software you need to install (like compilers, make, etc.) would be
more appropriate, than a note about building documentation.

Thanks.

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

[Shreyansh Paliwal]

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #1: Type: text/plain; charset=y, Size: 1084 bytes --]

> >> 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.
> > ...
> > Please let me know what would be the appropriate approach with this.
> 
> Again, I personally find that stopping at asciidoc and letting the
> user deal with their platform convention to get asciidoc working,
> like the current documentation does, draws the line better.
> 
> If we are not mentioning to check INSTALL elsewhere in the
> instruction, we probably should, and the place where we mention what
> software you need to install (like compilers, make, etc.) would be
> more appropriate, than a note about building documentation.
> 
> Thanks.

Since INSTALL is already referenced near the beginning of the document,
I will drop the additional mention there and keep the instructions as before
in the building documentation part.

I’ll update the patch accordingly and send a v2.

Thanks for the review and guidance.

Best,
Shreyansh

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

[Shreyansh Paliwal]

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

* 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 documentation 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..7306edab0f 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
@@ -503,8 +505,8 @@ git-psuh - Delight users' typo with a shy horse
 
 SYNOPSIS
 --------
-[verse]
-'git-psuh [<arg>...]'
+[synopsis]
+git psuh [<arg>...]
 
 DESCRIPTION
 -----------
@@ -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