{"thread":{"id":"64754","subject":"[PATCH] Documentation/MyFirstContribution: add missing dependencies and clarify build steps","startedAt":"2026-01-08T17:47:22Z","lastAt":"2026-01-12T19:56:47Z","messageCount":9,"participants":["Shreyansh Paliwal","Pushkar Singh","Junio C Hamano"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"533298","messageId":"20260108174651.1618874-1-shreyanshpaliwalcmsmn@gmail.com","threadId":"64754","inReplyTo":null,"subject":"[PATCH] Documentation/MyFirstContribution: add missing dependencies and clarify build steps","fromName":"Shreyansh Paliwal","fromEmail":"shreyanshpaliwalcmsmn@gmail.com","sentAt":"2026-01-08T17:40:49Z","receivedAt":"2026-01-08T17:47:22Z","isPatch":true,"sender":{"key":"shreyanshpaliwalcmsmn@gmail.com","avatar":"https://avatars.githubusercontent.com/u/152720574?v=4"},"body":"Fix issues in the MyFirstContribution guide that can lead to\nconfusion or failiure when following the documented steps.\n\nAdd missing header includes in code examples (environment.h and\nstrbuf.h), correct manpage synopsis formatting to prevent failing\ndocumentation tests, clarify documentation build prerequisites,\nincluding the AsciiDoc and DocBook-XSL stylesheets, specify the use\nof parallel test execution with -j$(nproc), noting that it runs\ntests using all available CPUs and may be adjusted.\n\nThese updates improve accuracy and make the first-time contributor\nexperience smoother.\n\nSigned-off-by: Shreyansh Paliwal <shreyanshpaliwalcmsmn@gmail.com>\n---\n Documentation/MyFirstContribution.adoc | 15 +++++++++------\n 1 file changed, 9 insertions(+), 6 deletions(-)\n\ndiff --git a/Documentation/MyFirstContribution.adoc b/Documentation/MyFirstContribution.adoc\nindex f186dfbc89..38f2a23e77 100644\n--- a/Documentation/MyFirstContribution.adoc\n+++ b/Documentation/MyFirstContribution.adoc\n@@ -331,7 +331,8 @@ on the command line, including the name of our command. (If `prefix` is empty\n for you, try `cd Documentation/ && ../bin-wrappers/git psuh`). That's not so\n helpful. So what other context can we get?\n \n-Add a line to `#include \"config.h\"` and `#include \"repository.h\"`.\n+Add a line to `#include \"config.h\"`, `#include \"repository.h\"` and\n+`#include \"environment.h\"`.\n Then, add the following bits to the function body:\n function body:\n \n@@ -429,6 +430,7 @@ Add the following includes:\n ----\n #include \"commit.h\"\n #include \"pretty.h\"\n+#include \"strbuf.h\"\n ----\n \n Then, add the following lines within your implementation of `cmd_psuh()` near\n@@ -504,7 +506,7 @@ git-psuh - Delight users' typo with a shy horse\n SYNOPSIS\n --------\n [verse]\n-'git-psuh [<arg>...]'\n+git psuh [<arg>...]\n \n DESCRIPTION\n -----------\n@@ -531,7 +533,7 @@ easier for your user, who can skip to the section they know contains the\n information they need.\n \n NOTE: Before trying to build the docs, make sure you have the package `asciidoc`\n-installed.\n+and `docbook-xsl` installed. See `INSTALL` for details.\n \n Now that you've written your manpage, you'll need to build it explicitly. We\n convert your AsciiDoc to troff which is man-readable like so:\n@@ -726,9 +728,10 @@ $ prove -j$(nproc) --shuffle t[0-9]*.sh\n ----\n \n NOTE: You can also do this with `make test` or use any testing harness which can\n-speak TAP. `prove` can run concurrently. `shuffle` randomizes the order the\n-tests are run in, which makes them resilient against unwanted inter-test\n-dependencies. `prove` also makes the output nicer.\n+speak TAP. `prove` can run concurrently. `-j$(nproc)` runs tests using all\n+available CPUs in parallel, but the job count can be adjusted as needed.\n+`shuffle` randomizes the order the tests are run in, which makes them resilient\n+against unwanted inter-test dependencies. `prove` also makes the output nicer.\n \n Go ahead and commit this change, as well.\n \n-- \n2.43.0\n\n"},{"id":"533600","messageId":"20260112094030.314203-1-shreyanshpaliwalcmsmn@gmail.com","threadId":"64754","inReplyTo":"20260108174651.1618874-1-shreyanshpaliwalcmsmn@gmail.com","subject":"[PATCH] doc: MyFirstContribution: fix missing dependencies and clarify build steps","fromName":"Shreyansh Paliwal","fromEmail":"shreyanshpaliwalcmsmn@gmail.com","sentAt":"2026-01-12T09:40:23Z","receivedAt":"2026-01-12T09:40:46Z","isPatch":true,"sender":{"key":"shreyanshpaliwalcmsmn@gmail.com","avatar":"https://avatars.githubusercontent.com/u/152720574?v=4"},"body":"Fix several issues in the MyFirstContribution guide that can lead to\nconfusion or test failures when following the documented steps.\n\n* Add missing header includes in code examples (environment.h and\nstrbuf.h).\n\n*  correct manpage synopsis formatting to prevent failing documentation tests.\n\n* clarify documentation build prerequisites, particularly specifying for DocBook-XSL.\n\n* specify the use of parallel test execution with -j$(nproc), noting that\nit runs tests using all available CPUs and may be adjusted.\n\nThese updates improve accuracy and make the first-time contributor\njourney smoother.\n\nSigned-off-by: Shreyansh Paliwal <shreyanshpaliwalcmsmn@gmail.com>\n---\n Documentation/MyFirstContribution.adoc | 15 +++++++++------\n 1 file changed, 9 insertions(+), 6 deletions(-)\n\ndiff --git a/Documentation/MyFirstContribution.adoc b/Documentation/MyFirstContribution.adoc\nindex f186dfbc89..38f2a23e77 100644\n--- a/Documentation/MyFirstContribution.adoc\n+++ b/Documentation/MyFirstContribution.adoc\n@@ -331,7 +331,8 @@ on the command line, including the name of our command. (If `prefix` is empty\n for you, try `cd Documentation/ && ../bin-wrappers/git psuh`). That's not so\n helpful. So what other context can we get?\n \n-Add a line to `#include \"config.h\"` and `#include \"repository.h\"`.\n+Add a line to `#include \"config.h\"`, `#include \"repository.h\"` and\n+`#include \"environment.h\"`.\n Then, add the following bits to the function body:\n function body:\n \n@@ -429,6 +430,7 @@ Add the following includes:\n ----\n #include \"commit.h\"\n #include \"pretty.h\"\n+#include \"strbuf.h\"\n ----\n \n Then, add the following lines within your implementation of `cmd_psuh()` near\n@@ -504,7 +506,7 @@ git-psuh - Delight users' typo with a shy horse\n SYNOPSIS\n --------\n [verse]\n-'git-psuh [<arg>...]'\n+git psuh [<arg>...]\n \n DESCRIPTION\n -----------\n@@ -531,7 +533,7 @@ easier for your user, who can skip to the section they know contains the\n information they need.\n \n NOTE: Before trying to build the docs, make sure you have the package `asciidoc`\n-installed.\n+and `docbook-xsl` installed. See `INSTALL` for details.\n \n Now that you've written your manpage, you'll need to build it explicitly. We\n convert your AsciiDoc to troff which is man-readable like so:\n@@ -726,9 +728,10 @@ $ prove -j$(nproc) --shuffle t[0-9]*.sh\n ----\n \n NOTE: You can also do this with `make test` or use any testing harness which can\n-speak TAP. `prove` can run concurrently. `shuffle` randomizes the order the\n-tests are run in, which makes them resilient against unwanted inter-test\n-dependencies. `prove` also makes the output nicer.\n+speak TAP. `prove` can run concurrently. `-j$(nproc)` runs tests using all\n+available CPUs in parallel, but the job count can be adjusted as needed.\n+`shuffle` randomizes the order the tests are run in, which makes them resilient\n+against unwanted inter-test dependencies. `prove` also makes the output nicer.\n \n Go ahead and commit this change, as well.\n \n-- \n2.43.0\n\n"},{"id":"533607","messageId":"CALE2CrTuZkFm1R3Bb6gFmrN1trr88vdO_7Aw6ycBYvFpWMEEtA@mail.gmail.com","threadId":"64754","inReplyTo":"20260112094030.314203-1-shreyanshpaliwalcmsmn@gmail.com","subject":"Re: [PATCH] doc: MyFirstContribution: fix missing dependencies and clarify build steps","fromName":"Pushkar Singh","fromEmail":"pushkarkumarsingh1970@gmail.com","sentAt":"2026-01-12T12:55:58Z","receivedAt":"2026-01-12T12:56:10Z","isPatch":true,"sender":{"key":"pushkarkumarsingh1970@gmail.com","avatar":"https://avatars.githubusercontent.com/u/173247767?v=4"},"body":"Hi Shreyansh,\n\nThanks for working on this. I have been going through\nMyFirstContribution myself and a lot of these changes match issues I\nactually hit while setting things up.\n\nThe extra includes like environment.h and strbuf.h make sense. I also\nran into build problems when those were missing in the examples.\nFixing the git psuh synopsis is a good catch too since it breaks the\nmanpage tests otherwise.\n\nThe note about needing docbook-xsl along with asciidoc is especially\nhelpful. That is something I had to figure out the hard way when\ntrying to build the docs.\n\nOne small thing I wondered about is the prove -j$(nproc) note. It\nmight be worth mentioning that using all CPUs can make failures harder\nto read for beginners, so starting without it could be easier. Not a\nbig deal, just a thought.\n\nOverall this looks like a nice improvement for new contributors.\n\nBest,\nPushkar\n\nOn Mon, Jan 12, 2026 at 3:10 PM Shreyansh Paliwal\n<shreyanshpaliwalcmsmn@gmail.com> wrote:\n>\n> Fix several issues in the MyFirstContribution guide that can lead to\n> confusion or test failures when following the documented steps.\n>\n> * Add missing header includes in code examples (environment.h and\n> strbuf.h).\n>\n> *  correct manpage synopsis formatting to prevent failing documentation tests.\n>\n> * clarify documentation build prerequisites, particularly specifying for DocBook-XSL.\n>\n> * specify the use of parallel test execution with -j$(nproc), noting that\n> it runs tests using all available CPUs and may be adjusted.\n>\n> These updates improve accuracy and make the first-time contributor\n> journey smoother.\n>\n> Signed-off-by: Shreyansh Paliwal <shreyanshpaliwalcmsmn@gmail.com>\n> ---\n>  Documentation/MyFirstContribution.adoc | 15 +++++++++------\n>  1 file changed, 9 insertions(+), 6 deletions(-)\n>\n> diff --git a/Documentation/MyFirstContribution.adoc b/Documentation/MyFirstContribution.adoc\n> index f186dfbc89..38f2a23e77 100644\n> --- a/Documentation/MyFirstContribution.adoc\n> +++ b/Documentation/MyFirstContribution.adoc\n> @@ -331,7 +331,8 @@ on the command line, including the name of our command. (If `prefix` is empty\n>  for you, try `cd Documentation/ && ../bin-wrappers/git psuh`). That's not so\n>  helpful. So what other context can we get?\n>\n> -Add a line to `#include \"config.h\"` and `#include \"repository.h\"`.\n> +Add a line to `#include \"config.h\"`, `#include \"repository.h\"` and\n> +`#include \"environment.h\"`.\n>  Then, add the following bits to the function body:\n>  function body:\n>\n> @@ -429,6 +430,7 @@ Add the following includes:\n>  ----\n>  #include \"commit.h\"\n>  #include \"pretty.h\"\n> +#include \"strbuf.h\"\n>  ----\n>\n>  Then, add the following lines within your implementation of `cmd_psuh()` near\n> @@ -504,7 +506,7 @@ git-psuh - Delight users' typo with a shy horse\n>  SYNOPSIS\n>  --------\n>  [verse]\n> -'git-psuh [<arg>...]'\n> +git psuh [<arg>...]\n>\n>  DESCRIPTION\n>  -----------\n> @@ -531,7 +533,7 @@ easier for your user, who can skip to the section they know contains the\n>  information they need.\n>\n>  NOTE: Before trying to build the docs, make sure you have the package `asciidoc`\n> -installed.\n> +and `docbook-xsl` installed. See `INSTALL` for details.\n>\n>  Now that you've written your manpage, you'll need to build it explicitly. We\n>  convert your AsciiDoc to troff which is man-readable like so:\n> @@ -726,9 +728,10 @@ $ prove -j$(nproc) --shuffle t[0-9]*.sh\n>  ----\n>\n>  NOTE: You can also do this with `make test` or use any testing harness which can\n> -speak TAP. `prove` can run concurrently. `shuffle` randomizes the order the\n> -tests are run in, which makes them resilient against unwanted inter-test\n> -dependencies. `prove` also makes the output nicer.\n> +speak TAP. `prove` can run concurrently. `-j$(nproc)` runs tests using all\n> +available CPUs in parallel, but the job count can be adjusted as needed.\n> +`shuffle` randomizes the order the tests are run in, which makes them resilient\n> +against unwanted inter-test dependencies. `prove` also makes the output nicer.\n>\n>  Go ahead and commit this change, as well.\n>\n> --\n> 2.43.0\n>\n>\n"},{"id":"533634","messageId":"xmqqcy3eoq6e.fsf@gitster.g","threadId":"64754","inReplyTo":"20260112094030.314203-1-shreyanshpaliwalcmsmn@gmail.com","subject":"Re: [PATCH] doc: MyFirstContribution: fix missing dependencies and clarify build steps","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-01-12T14:34:33Z","receivedAt":"2026-01-12T14:34:35Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Shreyansh Paliwal <shreyanshpaliwalcmsmn@gmail.com> writes:\n\n> Fix several issues in the MyFirstContribution guide that can lead to\n> confusion or test failures when following the documented steps.\n>\n> * Add missing header includes in code examples (environment.h and\n> strbuf.h).\n>\n> *  correct manpage synopsis formatting to prevent failing documentation tests.\n\nTwo spaces???\n\n>\n> * clarify documentation build prerequisites, particularly specifying for DocBook-XSL.\n>\n> * specify the use of parallel test execution with -j$(nproc), noting that\n> it runs tests using all available CPUs and may be adjusted.\n>\n> These updates improve accuracy and make the first-time contributor\n> journey smoother.\n>\n> Signed-off-by: Shreyansh Paliwal <shreyanshpaliwalcmsmn@gmail.com>\n> ---\n>  Documentation/MyFirstContribution.adoc | 15 +++++++++------\n>  1 file changed, 9 insertions(+), 6 deletions(-)\n>\n> diff --git a/Documentation/MyFirstContribution.adoc b/Documentation/MyFirstContribution.adoc\n> index f186dfbc89..38f2a23e77 100644\n> --- a/Documentation/MyFirstContribution.adoc\n> +++ b/Documentation/MyFirstContribution.adoc\n> @@ -331,7 +331,8 @@ on the command line, including the name of our command. (If `prefix` is empty\n>  for you, try `cd Documentation/ && ../bin-wrappers/git psuh`). That's not so\n>  helpful. So what other context can we get?\n>  \n> -Add a line to `#include \"config.h\"` and `#include \"repository.h\"`.\n> +Add a line to `#include \"config.h\"`, `#include \"repository.h\"` and\n> +`#include \"environment.h\"`.\n\nGood.\n\n>  Then, add the following bits to the function body:\n>  function body:\n>  \n> @@ -429,6 +430,7 @@ Add the following includes:\n>  ----\n>  #include \"commit.h\"\n>  #include \"pretty.h\"\n> +#include \"strbuf.h\"\n>  ----\n>  \n>  Then, add the following lines within your implementation of `cmd_psuh()` near\n> @@ -504,7 +506,7 @@ git-psuh - Delight users' typo with a shy horse\n>  SYNOPSIS\n>  --------\n>  [verse]\n> -'git-psuh [<arg>...]'\n> +git psuh [<arg>...]\n\nRemoving \"-\" does make sense but did you really want to remove the\nquotes around the command?  If you are moving to the [synopsis]\nstyle from [verse] (*), it may make sense, but otherwise...?\n\n    Side note: see de56e1d7 (Merge branch\n    'ja/doc-commit-markup-updates', 2025-01-29) for example.\n\n>  NOTE: Before trying to build the docs, make sure you have the package `asciidoc`\n> -installed.\n> +and `docbook-xsl` installed. See `INSTALL` for details.\n\nI suspect this is highly distribution specific.  The asciidoc\npackage is typically packaged to depend on or suggest the docbook\ntoolchain including docbook-xsl, and if we start adding more \"to\nhelp newbies\", we'd face the problem of \"where would we stop?\".  For\nexample, on Debian derived systems, the docbook-xsl package\ntypicallly depends on the xml-core package---should we also list it?\n\nI personally find that stopping at asciidoc and let the user deal\nwith their platform convention to get asciidoc working, like the\ncurrent documentation does, draws the line better than the above\nupdated text.\n\n"},{"id":"533651","messageId":"20260112160828.350483-1-shreyanshpaliwalcmsmn@gmail.com","threadId":"64754","inReplyTo":"CALE2CrTuZkFm1R3Bb6gFmrN1trr88vdO_7Aw6ycBYvFpWMEEtA@mail.gmail.com","subject":"Re: [PATCH] doc: MyFirstContribution: fix missing dependencies and clarify build steps","fromName":"Shreyansh Paliwal","fromEmail":"shreyanshpaliwalcmsmn@gmail.com","sentAt":"2026-01-12T16:05:52Z","receivedAt":"2026-01-12T16:08:42Z","isPatch":true,"sender":{"key":"shreyanshpaliwalcmsmn@gmail.com","avatar":"https://avatars.githubusercontent.com/u/152720574?v=4"},"body":"> One small thing I wondered about is the prove -j$(nproc) note. It\n> might be worth mentioning that using all CPUs can make failures harder\n> to read for beginners, so starting without it could be easier. Not a\n> big deal, just a thought.\n\nActually, I included this mainly to make sure readers understand the purpose\nof -j$(nproc) in the command. The motivation for adding the note came from \nmy own experience, where I ran the tests with this and it saturated my system\nresources and interfered with other important processes, which led me to\nreduce the parallel job count.\n\nAs for the difficulty that beginners may face when reading failures,\nmy expectation was that users could either trace failures using the summary\nshown at the end of the test run or adjust the level of parallelism based\non the note, rather than starting without parallelism altogether,\nwhich can significantly increase test runtime.\n\nBest,\nShreyansh\n"},{"id":"533653","messageId":"20260112161538.351527-1-shreyanshpaliwalcmsmn@gmail.com","threadId":"64754","inReplyTo":"xmqqcy3eoq6e.fsf@gitster.g","subject":"Re: [PATCH] doc: MyFirstContribution: fix missing dependencies and clarify build steps","fromName":"Shreyansh Paliwal","fromEmail":"shreyanshpaliwalcmsmn@gmail.com","sentAt":"2026-01-12T16:11:09Z","receivedAt":"2026-01-12T16:15:49Z","isPatch":true,"sender":{"key":"shreyanshpaliwalcmsmn@gmail.com","avatar":"https://avatars.githubusercontent.com/u/152720574?v=4"},"body":"> > Fix several issues in the MyFirstContribution guide that can lead to\n> > confusion or test failures when following the documented steps.\n> >\n> > * Add missing header includes in code examples (environment.h and\n> > strbuf.h).\n> >\n> > *  correct manpage synopsis formatting to prevent failing documentation tests.\n> \n> Two spaces???\n\nSorry, my bad. Will fix it in v2.\n\n> >  Then, add the following bits to the function body:\n> >  function body:\n> >  \n> > @@ -429,6 +430,7 @@ Add the following includes:\n> >  ----\n> >  #include \"commit.h\"\n> >  #include \"pretty.h\"\n> > +#include \"strbuf.h\"\n> >  ----\n> >  \n> >  Then, add the following lines within your implementation of `cmd_psuh()` near\n> > @@ -504,7 +506,7 @@ git-psuh - Delight users' typo with a shy horse\n> >  SYNOPSIS\n> >  --------\n> >  [verse]\n> > -'git-psuh [<arg>...]'\n> > +git psuh [<arg>...]\n> \n> Removing \"-\" does make sense but did you really want to remove the\n> quotes around the command?  If you are moving to the [synopsis]\n> style from [verse] (*), it may make sense, but otherwise...?\n> \n>     Side note: see de56e1d7 (Merge branch\n>     'ja/doc-commit-markup-updates', 2025-01-29) for example.\n\nActually, I initially kept the quotes, but the test that checks consistency between\nthe manpage synopsis and the -h output was still failing. At that point, my intention\nwas to switch to the [synopsis] style, so I removed the quotes, but I missed updating\nthe markup from [verse] to [synopsis].\nWill fix this as well in v2.\n\n> >  NOTE: Before trying to build the docs, make sure you have the package `asciidoc`\n> > -installed.\n> > +and `docbook-xsl` installed. See `INSTALL` for details.\n> \n> I suspect this is highly distribution specific.  The asciidoc\n> package is typically packaged to depend on or suggest the docbook\n> toolchain including docbook-xsl, and if we start adding more \"to\n> help newbies\", we'd face the problem of \"where would we stop?\".  For\n> example, on Debian derived systems, the docbook-xsl package\n> typicallly depends on the xml-core package---should we also list it?\n> \n> I personally find that stopping at asciidoc and let the user deal\n> with their platform convention to get asciidoc working, like the\n> current documentation does, draws the line better than the above\n> updated text.\n\nI totally agree with the “where would we stop?” concern, that is also\nwhy I intentionally avoided calling out Windows or any linux-distro\nspecific details elsewhere in the document.\n\nMy thinking here was that docbook-xsl felt more like a peer dependency\nto asciidoc rather than a deeper, transitive one (like xml-core),\nespecially since it is explicitly mentioned in INSTALL doc.\n\nAn alternative could be to keep it less concrete and say something like\n\n\t“make sure you have the `asciidoc` installed along with the\n\t required docbook toolchain. Refer INSTALL for details”\n\nPlease let me know what would be the appropriate approach with this.\n\nBest,\nShreyansh\n"},{"id":"533661","messageId":"xmqqbjiymzpq.fsf@gitster.g","threadId":"64754","inReplyTo":"20260112161538.351527-1-shreyanshpaliwalcmsmn@gmail.com","subject":"Re: [PATCH] doc: MyFirstContribution: fix missing dependencies and clarify build steps","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-01-12T18:51:29Z","receivedAt":"2026-01-12T18:51:31Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Shreyansh Paliwal <shreyanshpaliwalcmsmn@gmail.com> writes:\n\n>> I personally find that stopping at asciidoc and let the user deal\n>> with their platform convention to get asciidoc working, like the\n>> current documentation does, draws the line better than the above\n>> updated text.\n> ...\n> Please let me know what would be the appropriate approach with this.\n\nAgain, I personally find that stopping at asciidoc and letting the\nuser deal with their platform convention to get asciidoc working,\nlike the current documentation does, draws the line better.\n\nIf we are not mentioning to check INSTALL elsewhere in the\ninstruction, we probably should, and the place where we mention what\nsoftware you need to install (like compilers, make, etc.) would be\nmore appropriate, than a note about building documentation.\n\nThanks.\n"},{"id":"533674","messageId":"20260112191029.376820-1-shreyanshpaliwalcmsmn@gmail.com","threadId":"64754","inReplyTo":"xmqqbjiymzpq.fsf@gitster.g","subject":"Re: [PATCH] doc: MyFirstContribution: fix missing dependencies and clarify build steps","fromName":"Shreyansh Paliwal","fromEmail":"shreyanshpaliwalcmsmn@gmail.com","sentAt":"2026-01-12T19:10:08Z","receivedAt":"2026-01-12T19:10:43Z","isPatch":true,"sender":{"key":"shreyanshpaliwalcmsmn@gmail.com","avatar":"https://avatars.githubusercontent.com/u/152720574?v=4"},"body":"> >> I personally find that stopping at asciidoc and let the user deal\n> >> with their platform convention to get asciidoc working, like the\n> >> current documentation does, draws the line better than the above\n> >> updated text.\n> > ...\n> > Please let me know what would be the appropriate approach with this.\n> \n> Again, I personally find that stopping at asciidoc and letting the\n> user deal with their platform convention to get asciidoc working,\n> like the current documentation does, draws the line better.\n> \n> If we are not mentioning to check INSTALL elsewhere in the\n> instruction, we probably should, and the place where we mention what\n> software you need to install (like compilers, make, etc.) would be\n> more appropriate, than a note about building documentation.\n> \n> Thanks.\n\nSince INSTALL is already referenced near the beginning of the document,\nI will drop the additional mention there and keep the instructions as before\nin the building documentation part.\n\nI’ll update the patch accordingly and send a v2.\n\nThanks for the review and guidance.\n\nBest,\nShreyansh\n"},{"id":"533678","messageId":"20260112195625.391821-1-shreyanshpaliwalcmsmn@gmail.com","threadId":"64754","inReplyTo":"20260112191029.376820-1-shreyanshpaliwalcmsmn@gmail.com","subject":"[PATCH v2] doc: MyFirstContribution: fix missing dependencies and clarify build steps","fromName":"Shreyansh Paliwal","fromEmail":"shreyanshpaliwalcmsmn@gmail.com","sentAt":"2026-01-12T19:53:43Z","receivedAt":"2026-01-12T19:56:47Z","isPatch":true,"sender":{"key":"shreyanshpaliwalcmsmn@gmail.com","avatar":"https://avatars.githubusercontent.com/u/152720574?v=4"},"body":"Fix issues in the MyFirstContribution guide that can lead to confusion or\ntest failures when following the documented steps.\n\n* Add missing header includes in code examples (environment.h and strbuf.h).\n\n* Correct manpage synopsis formatting to prevent failing documentation tests.\n\n* Specify the use of parallel test execution with -j$(nproc), noting that it\nruns tests using all available CPUs and may be adjusted.\n\nThese updates improve documentation accuracy and make the first-time contributor\njourney smoother.\n\nSigned-off-by: Shreyansh Paliwal <shreyanshpaliwalcmsmn@gmail.com>\n---\n Documentation/MyFirstContribution.adoc | 15 +++++++++------\n 1 file changed, 9 insertions(+), 6 deletions(-)\n\ndiff --git a/Documentation/MyFirstContribution.adoc b/Documentation/MyFirstContribution.adoc\nindex f186dfbc89..7306edab0f 100644\n--- a/Documentation/MyFirstContribution.adoc\n+++ b/Documentation/MyFirstContribution.adoc\n@@ -331,7 +331,8 @@ on the command line, including the name of our command. (If `prefix` is empty\n for you, try `cd Documentation/ && ../bin-wrappers/git psuh`). That's not so\n helpful. So what other context can we get?\n \n-Add a line to `#include \"config.h\"` and `#include \"repository.h\"`.\n+Add a line to `#include \"config.h\"`, `#include \"repository.h\"` and\n+`#include \"environment.h\"`.\n Then, add the following bits to the function body:\n function body:\n \n@@ -429,6 +430,7 @@ Add the following includes:\n ----\n #include \"commit.h\"\n #include \"pretty.h\"\n+#include \"strbuf.h\"\n ----\n \n Then, add the following lines within your implementation of `cmd_psuh()` near\n@@ -503,8 +505,8 @@ git-psuh - Delight users' typo with a shy horse\n \n SYNOPSIS\n --------\n-[verse]\n-'git-psuh [<arg>...]'\n+[synopsis]\n+git psuh [<arg>...]\n \n DESCRIPTION\n -----------\n@@ -726,9 +728,10 @@ $ prove -j$(nproc) --shuffle t[0-9]*.sh\n ----\n \n NOTE: You can also do this with `make test` or use any testing harness which can\n-speak TAP. `prove` can run concurrently. `shuffle` randomizes the order the\n-tests are run in, which makes them resilient against unwanted inter-test\n-dependencies. `prove` also makes the output nicer.\n+speak TAP. `prove` can run concurrently. `-j$(nproc)` runs tests using all\n+available CPUs in parallel, but the job count can be adjusted as needed.\n+`shuffle` randomizes the order the tests are run in, which makes them resilient\n+against unwanted inter-test dependencies. `prove` also makes the output nicer.\n \n Go ahead and commit this change, as well.\n \n-- \n2.43.0\n\n"}]}