Skip to contentSkip to conversation

some clarifications to MyFirstContribution

PATCH Superseded Emily Shaffer 6 participants 20 messages Oct 26, 2019 – Oct 31, 2019 Documentation

lore
Share & tools
lore
#0 lore raw

cover some clarifications to MyFirstContribution

Hi all,

With the wave of Outreachy participants (hello! welcome!) a few shortcomings in the MyFirstContribution tutorial have been noted; plus, a comment from SZEDER (thanks!) sent along some weeks ago about a missing step in the new command process.

[1/3] Per SZEDER's comment, we should be adding git psuh to the list
of commands used by 'git help'.
[2/3] Outreachy applicant Heba Waly indicated that the tutorial doesn't
cover dependencies needed to build Git. However, I don't have a good handle on what's needed for platforms besides Linux, so I really appreciate others suggesting dependency installation steps for other platforms (even if it is a link to another guide).
[3/3] Per some discussions in #git-devel this week, it's not apparent
who to ask for the /allow comment to tell GitGitGadget that you can be trusted. So, add the same hint which is proposed to be shown in GitGitGadget's welcome message.

Emily Shaffer (3):
myfirstcontrib: add 'psuh' to command-list.txt
myfirstcontrib: add dependency installation step
myfirstcontrib: hint to find gitgitgadget allower

 Documentation/MyFirstContribution.txt | 57 +++++++++++++++++++++++++--
 1 file changed, 54 insertions(+), 3 deletions(-)
Signature · 1 line
2.24.0.rc0.303.g954a862665-goog
#1 lore raw

PATCH 1/3 myfirstcontrib: add 'psuh' to command-list.txt

Users can discover commands and their brief usage by running 'git help git' or 'git help -a'; both of these pages list all available commands based on the contents of 'command-list.txt'. That means adding a new command there is an important part of the new command process, and therefore belongs in the new command tutorial.

Teach new users how to add their command, and include a brief overview of how to discover which attributes to place on the command in the list.

Since 'git psuh' prints some workspace info, doesn't modify anything, and is targeted as a user-facing porcelain command, list it as a 'mainporcelain' and 'info' command.

As the usage string is required to generate this documentation, don't add the command to the list until after the usage string is added to the tutorial.

---
 Documentation/MyFirstContribution.txt | 22 ++++++++++++++++++++++
 1 file changed, 22 insertions(+)
Documentation/MyFirstContribution.txt +22 -0
index 5e9b808f5f..12b7256454 100644
@@ -534,6 +534,28 @@ you want to pass as a parameter something which would usually be interpreted as
 a flag.) `parse_options()` will terminate parsing when it reaches `--` and give
 you the rest of the options afterwards, untouched.
 
+Now that you have a usage hint, you can teach Git how to show it in the general
+command list shown by `git help git` or `git help -a`, which is generated from
+`command-list.txt`. Find the line for 'git-pull' so you can add your 'git-psuh'
+line above it in alphabetical order. Now, we can add some attributes about the
+command which impacts where it shows up in the aforementioned help commands. The
+top of `command-list.txt` shares some information about what each attribute
+means; in those help pages, the commands are sorted according to these
+attributes. `git psuh` is user-facing, or porcelain - so we will mark it as
+"mainporcelain". For "mainporcelain" commands, the comments at the top of
+`command-list.txt` indicate we can also optionally add an attribute from another
+list; since `git psuh` shows some information about the user's workspace but
+doesn't modify anything, let's mark it as "info". Make sure to keep your
+attributes in the same style as the rest of `command-list.txt` using spaces to
+align and delineate them:
+
+----
+git-prune-packed                        plumbingmanipulators
+git-psuh                                mainporcelain		info
+git-pull                                mainporcelain           remote
+git-push                                mainporcelain           remote
+----
+
 Build again. Now, when you run with `-h`, you should see your usage printed and
 your command terminated before anything else interesting happens. Great!
 
Signature · 1 line
2.24.0.rc0.303.g954a862665-goog
#2 lore raw

Re: [PATCH 1/3] myfirstcontrib: add 'psuh' to command-list.txt

Hi,

Quoted 5 lines · Emily Shaffer

Users can discover commands and their brief usage by running 'git help git' or 'git help -a'; both of these pages list all available commands based on the contents of 'command-list.txt'. That means adding a new command there is an important part of the new command process, and therefore belongs in the new command tutorial.

Makes sense.

Not about this patch: is there a way to detect this automatically? E.g. if a command in git.c::commands doesn't appear in command-list.txt, could we make Git fail "make test"?

[...]

Documentation/MyFirstContribution.txt you want to pass as a parameter something which would usually be interpreted as · line 541

Quoted 11 lines
Documentation/MyFirstContribution.txt +5 -0
@@ -534,6 +534,28 @@ you want to pass as a parameter something which would usually be interpreted as
 a flag.) `parse_options()` will terminate parsing when it reaches `--` and give
 you the rest of the options afterwards, untouched.
 
+Now that you have a usage hint, you can teach Git how to show it in the general
+command list shown by `git help git` or `git help -a`, which is generated from
+`command-list.txt`. Find the line for 'git-pull' so you can add your 'git-psuh'
+line above it in alphabetical order. Now, we can add some attributes about the
+command which impacts where it shows up in the aforementioned help commands. The

nit: s/impacts/impact/, to agree with "attributes"

Documentation/MyFirstContribution.txt you want to pass as a parameter something which would usually be interpreted as · line 544

Quoted 3 lines
Documentation/MyFirstContribution.txt +3 -0
+top of `command-list.txt` shares some information about what each attribute
+means; in those help pages, the commands are sorted according to these
+attributes. `git psuh` is user-facing, or porcelain - so we will mark it as
                                             ^^^^^^^^^

optional: This might be an unfamiliar term to people not thinking of the plumbing fixture / chrome analogy. Is there anything we should do to help them understand what's going on?

E.g. "git help glossary" says

Porcelains expose more of a SCM interface than the plumbing.

Documentation/MyFirstContribution.txt you want to pass as a parameter something which would usually be interpreted as · line 554

Quoted 10 lines
Documentation/MyFirstContribution.txt +10 -0
+"mainporcelain". For "mainporcelain" commands, the comments at the top of
+`command-list.txt` indicate we can also optionally add an attribute from another
+list; since `git psuh` shows some information about the user's workspace but
+doesn't modify anything, let's mark it as "info". Make sure to keep your
+attributes in the same style as the rest of `command-list.txt` using spaces to
+align and delineate them:
+
+----
+git-prune-packed                        plumbingmanipulators
+git-psuh                                mainporcelain		info

tabs snuck in.

Documentation/MyFirstContribution.txt you want to pass as a parameter something which would usually be interpreted as · line 558

Quoted 4 lines
Documentation/MyFirstContribution.txt +4 -0
+git-pull                                mainporcelain           remote
+git-push                                mainporcelain           remote
+----
+

The rest looks good.

Thanks,
Jonathan

#3 lore raw

Re: [PATCH 1/3] myfirstcontrib: add 'psuh' to command-list.txt

Quoted 11 lines · Jonathan Nieder
Quoted 5 lines

Users can discover commands and their brief usage by running 'git help git' or 'git help -a'; both of these pages list all available commands based on the contents of 'command-list.txt'. That means adding a new command there is an important part of the new command process, and therefore belongs in the new command tutorial.

Makes sense.

Not about this patch: is there a way to detect this automatically? E.g. if a command in git.c::commands doesn't appear in command-list.txt, could we make Git fail "make test"?

We almost detect this already:

  $ sed -i -e '/^git-bisect/d' command-list.txt 
  $ make check-docs
  make -C Documentation lint-docs
  make[1]: Entering directory '/home/szeder/src/git/Documentation'
      GEN cmd-list.made
      GEN doc.dep
  make[2]: Entering directory '/home/szeder/src/git'
  make[2]: 'GIT-VERSION-FILE' is up to date.
  make[2]: Leaving directory '/home/szeder/src/git'
  make[2]: Entering directory '/home/szeder/src/git'
  make[2]: 'GIT-VERSION-FILE' is up to date.
  make[2]: Leaving directory '/home/szeder/src/git'
      LINT lint-docs
  make[1]: Leaving directory '/home/szeder/src/git/Documentation'
  no link: git-bisect
  $ echo $?
  0

See that last "no link: git-bisect" line? That's what happened to catch my eyes when Derrick forgot to add his new 'sparse-checkout' builtin to 'command-list.txt'. I still haven't looked up what that 'no link' is supposed to mean, but if it were an error, then we would have surely detected the missing entry in 'command-list.txt' in out CI builds.

Another possibility would be to auto-generate that long list of 'cmd_foo()' function declaration in 'builtin.h' from 'command-list.txt', by adding a 'builtin' attribute to mark builtin commands.

#4 lore raw

Re: [PATCH 1/3] myfirstcontrib: add 'psuh' to command-list.txt

Quoted 4 lines · SZEDER Gábor

See that last "no link: git-bisect" line? That's what happened to catch my eyes when Derrick forgot to add his new 'sparse-checkout' builtin to 'command-list.txt'. I still haven't looked up what that 'no link' is supposed to mean, but if it were an error, then we would

Build procedure for the Documentation uses ../command-list.txt as its input to produce cmds-<class>.txt files, that are included in git.txt (hence resulting git.1 and git.html). While it works, it tries to make sure that a command that has its own documentation page at Documentation/git-<command>.txt is listed; otherwise we have a page for <command> to which there is no link from git.{1,html}.

I think "make check-builtins" might also want to sanity check command-list.txt.

#5 lore raw

Re: [PATCH 1/3] myfirstcontrib: add 'psuh' to command-list.txt

Quoted 7 lines · Junio C Hamano
Quoted 4 lines · SZEDER Gábor

See that last "no link: git-bisect" line? That's what happened to catch my eyes when Derrick forgot to add his new 'sparse-checkout' builtin to 'command-list.txt'. I still haven't looked up what that 'no link' is supposed to mean, but if it were an error, then we would

Quoted 6 lines

Build procedure for the Documentation uses ../command-list.txt as its input to produce cmds-<class>.txt files, that are included in git.txt (hence resulting git.1 and git.html). While it works, it tries to make sure that a command that has its own documentation page at Documentation/git-<command>.txt is listed; otherwise we have a page for <command> to which there is no link from git.{1,html}.

Oh, then it doesn't quite do what I thought it does.

Quoted 2 lines

I think "make check-builtins" might also want to sanity check command-list.txt.

I haven't noticed that we have something like that. FWIW, our documentation CI job runs it already.

And indeed it can be easily extended to check 'command-list.txt' as well, but then it will find some other builtins not included in 'command-list.txt', namely:

bisect--helper env--helper fsck-objects init-db merge-ours merge-recursive merge-subtree remote-ext remote-fd submodule--helper

I think it makes sense not to include the '*--helper' commands, or 'fsck-objects' and 'init-db', but I'm not sure about the others.

OTOH, it won't help if we add a new git-foo script and forgot to include it in 'command-list.txt'.

#6 lore raw

Re: [PATCH 1/3] myfirstcontrib: add 'psuh' to command-list.txt

In reply to SZEDER Gábor

Hi Gábor,

Quoted 33 lines · SZEDER Gábor
Quoted 11 lines · Jonathan Nieder
Quoted 5 lines

Users can discover commands and their brief usage by running 'git help git' or 'git help -a'; both of these pages list all available commands based on the contents of 'command-list.txt'. That means adding a new command there is an important part of the new command process, and therefore belongs in the new command tutorial.

Makes sense.

Not about this patch: is there a way to detect this automatically? E.g. if a command in git.c::commands doesn't appear in command-list.txt, could we make Git fail "make test"?

We almost detect this already:

  $ sed -i -e '/^git-bisect/d' command-list.txt
  $ make check-docs
  make -C Documentation lint-docs
  make[1]: Entering directory '/home/szeder/src/git/Documentation'
      GEN cmd-list.made
      GEN doc.dep
  make[2]: Entering directory '/home/szeder/src/git'
  make[2]: 'GIT-VERSION-FILE' is up to date.
  make[2]: Leaving directory '/home/szeder/src/git'
  make[2]: Entering directory '/home/szeder/src/git'
  make[2]: 'GIT-VERSION-FILE' is up to date.
  make[2]: Leaving directory '/home/szeder/src/git'
      LINT lint-docs
  make[1]: Leaving directory '/home/szeder/src/git/Documentation'
  no link: git-bisect
  $ echo $?
  0
Quoted 6 lines

See that last "no link: git-bisect" line? That's what happened to catch my eyes when Derrick forgot to add his new 'sparse-checkout' builtin to 'command-list.txt'. I still haven't looked up what that 'no link' is supposed to mean, but if it were an error, then we would have surely detected the missing entry in 'command-list.txt' in out CI builds.

FWIW I think the only reason that this is not an error in check-docs (which _is_ run by our CI/PR builds, in the Documentation job) is that it used to be buggy.

However, I think I managed to address the remaining issues in js/misc-doc-fixes (and maybe there were a couple spill-overs into js/check-docs-exe).

In short: I think we can make this type of issue trigger an error in check-docs now (as in: non-zero exit code).

Ciao,
Dscho

Quoted 7 lines

Another possibility would be to auto-generate that long list of 'cmd_foo()' function declaration in 'builtin.h' from 'command-list.txt', by adding a 'builtin' attribute to mark builtin commands.

#7 lore raw

PATCH 2/3 myfirstcontrib: add dependency installation step

In reply to Emily Shaffer

Indicate that the user needs some dependencies before the build will run happily on their machine; this dependency list doesn't seem to be made clear anywhere else in the project documentation. Then, so the user can be certain any build failures are due to their code and not their environment, perform a build on a clean checkout of 'master'. Also, move the note about build parallelization up here, so that it appears next to the very first build invocation in the tutorial.

---
 Documentation/MyFirstContribution.txt | 27 ++++++++++++++++++++++++---
 1 file changed, 24 insertions(+), 3 deletions(-)
Documentation/MyFirstContribution.txt +24 -3
index 12b7256454..b8ffeda07e 100644
@@ -38,6 +38,30 @@ $ git clone https://github.com/git/git git
 $ cd git
 ----
 
+[[dependencies]]
+=== Installing Dependencies
+
+To build Git from source, you need to have a handful of dependencies installed
+on your system. For a hint of what's needed, you can take a look at
+`ci/install-dependencies.sh`.
+
+To install the dependencies needed for a basic build on Linux, run something
+like this (or replace `apt` with your distribution's package manager of choice):
+
+----
+# apt install libssl-dev zlib1g-dev libcurl4-gnutls-dev libexpat1-dev
+----
+
+Make sure that your environment has everything you need by building your brand
+new clone of Git from the above step:
+
+----
+$ make
+----
+
+NOTE: The Git build is parallelizable. `-j#` is not included above but you can
+use it as you prefer, here and elsewhere.
+
 [[identify-problem]]
 === Identify Problem to Solve
 
@@ -138,9 +162,6 @@ NOTE: When you are developing the Git project, it's preferred that you use the
 `DEVELOPER` flag; if there's some reason it doesn't work for you, you can turn
 it off, but it's a good idea to mention the problem to the mailing list.
 
-NOTE: The Git build is parallelizable. `-j#` is not included above but you can
-use it as you prefer, here and elsewhere.
-
 Great, now your new command builds happily on its own. But nobody invokes it.
 Let's change that.
 
Signature · 1 line
2.24.0.rc0.303.g954a862665-goog
Reviewed-by on v1 2/3
#8 lore raw

Re: [PATCH 2/3] myfirstcontrib: add dependency installation step

Hi,

Quoted 3 lines · Emily Shaffer

Indicate that the user needs some dependencies before the build will run happily on their machine; this dependency list doesn't seem to be made clear anywhere else in the project documentation.

In theory, this info should be in INSTALL. I wouldn't be surprised if it's missing some info, though.

[...]

Quoted 5 lines
Documentation/MyFirstContribution.txt +0 -0
@@ -38,6 +38,30 @@ $ git clone https://github.com/git/git git
 $ cd git
 ----

Documentation/MyFirstContribution.txt $ git clone https://github.com/git/git git · line 49

Quoted 10 lines
Documentation/MyFirstContribution.txt +9 -0
 
+[[dependencies]]
+=== Installing Dependencies
+
+To build Git from source, you need to have a handful of dependencies installed
+on your system. For a hint of what's needed, you can take a look at
+`ci/install-dependencies.sh`.
+
+To install the dependencies needed for a basic build on Linux, run something
+like this (or replace `apt` with your distribution's package manager of choice):

pedantic nit: s/or replace/replacing/ ("or" would mean rpm is an alternative to what came before, but "something like" in the phrase before has rpm already included)

Documentation/MyFirstContribution.txt $ git clone https://github.com/git/git git · line 52

Quoted 3 lines
Documentation/MyFirstContribution.txt +3 -0
+
+----
+# apt install libssl-dev zlib1g-dev libcurl4-gnutls-dev libexpat1-dev

Perhaps build-essential, too, in case they're using a system not set up for development.

Quoted 16 lines
Documentation/MyFirstContribution.txt +12 -0
+----
+
+Make sure that your environment has everything you need by building your brand
+new clone of Git from the above step:
+
+----
+$ make
+----
+
+NOTE: The Git build is parallelizable. `-j#` is not included above but you can
+use it as you prefer, here and elsewhere.
+
 [[identify-problem]]
 === Identify Problem to Solve
 

Documentation/MyFirstContribution.txt NOTE: When you are developing the Git project, it's preferred that you use the · line 166

Quoted 8 lines
Documentation/MyFirstContribution.txt +0 -3
@@ -138,9 +162,6 @@ NOTE: When you are developing the Git project, it's preferred that you use the
 `DEVELOPER` flag; if there's some reason it doesn't work for you, you can turn
 it off, but it's a good idea to mention the problem to the mailing list.
 
-NOTE: The Git build is parallelizable. `-j#` is not included above but you can
-use it as you prefer, here and elsewhere.
-
 Great, now your new command builds happily on its own. But nobody invokes it.
 Let's change that.

With whatever subset of the changes above make sense,

Thanks.

#9 lore raw

Re: [PATCH 2/3] myfirstcontrib: add dependency installation step

Quoted 18 lines · Jonathan Nieder

Hi,

Quoted 3 lines · Emily Shaffer

Indicate that the user needs some dependencies before the build will run happily on their machine; this dependency list doesn't seem to be made clear anywhere else in the project documentation.

In theory, this info should be in INSTALL. I wouldn't be surprised if it's missing some info, though.

[...]

Quoted 6 lines
Documentation/MyFirstContribution.txt +0 -0
@@ -38,6 +38,30 @@ $ git clone https://github.com/git/git git
 $ cd git
 ----
 
Quoted 13 lines

Documentation/MyFirstContribution.txt $ git clone https://github.com/git/git git · line 49

Quoted 9 lines
Documentation/MyFirstContribution.txt +9 -0
+[[dependencies]]
+=== Installing Dependencies
+
+To build Git from source, you need to have a handful of dependencies installed
+on your system. For a hint of what's needed, you can take a look at
+`ci/install-dependencies.sh`.
+
+To install the dependencies needed for a basic build on Linux, run something
+like this (or replace `apt` with your distribution's package manager of choice):

pedantic nit: s/or replace/replacing/ ("or" would mean rpm is an alternative to what came before, but "something like" in the phrase before has rpm already included)

This section, as you hinted at the beginning, should be a single sentence, i.e. just "follow INSTALL". Any clarifications should be made as a patch to the INSTALL file.

Thanks.

#10 lore raw

Re: [PATCH 2/3] myfirstcontrib: add dependency installation step

Quoted 34 lines · Junio C Hamano
Quoted 18 lines · Jonathan Nieder

Hi,

Quoted 3 lines · Emily Shaffer

Indicate that the user needs some dependencies before the build will run happily on their machine; this dependency list doesn't seem to be made clear anywhere else in the project documentation.

In theory, this info should be in INSTALL. I wouldn't be surprised if it's missing some info, though.

[...]

Quoted 6 lines
Documentation/MyFirstContribution.txt +0 -0
@@ -38,6 +38,30 @@ $ git clone https://github.com/git/git git
 $ cd git
 ----
 
Quoted 13 lines

Documentation/MyFirstContribution.txt $ git clone https://github.com/git/git git · line 49

Quoted 9 lines
Documentation/MyFirstContribution.txt +9 -0
+[[dependencies]]
+=== Installing Dependencies
+
+To build Git from source, you need to have a handful of dependencies installed
+on your system. For a hint of what's needed, you can take a look at
+`ci/install-dependencies.sh`.
+
+To install the dependencies needed for a basic build on Linux, run something
+like this (or replace `apt` with your distribution's package manager of choice):

pedantic nit: s/or replace/replacing/ ("or" would mean rpm is an alternative to what came before, but "something like" in the phrase before has rpm already included)

Quoted 3 lines

This section, as you hinted at the beginning, should be a single sentence, i.e. just "follow INSTALL". Any clarifications should be made as a patch to the INSTALL file.

Thanks. I ended up with a little over one sentence; I don't like that a newbie following INSTALL file would end up with their locally-built Git installed (and they may only be interested in a one-off contribution, and never fetch again, or something) so I tried to highlight the dependencies portion of INSTALL:

To build Git from source, you need to have a handful of dependencies installed on your system. For a hint of what's needed, you can take a look at INSTALL, paying close attention to the section about Git's dependencies on external programs and libraries. That document mentions a way to "test-drive" our freshly built Git without installing; that's the method we'll be using in this tutorial.

Make sure that your environment has everything you need by building your brand new clone of Git from the above step:

- Emily

#11 lore raw

PATCH 3/3 myfirstcontrib: hint to find gitgitgadget allower

In reply to Emily Shaffer

GitGitGadget, a handy tool for converting pull requests against Git into Git-mailing-list-friendly-patch-emails, requires as anti-spam that all new users be "/allow"ed by an existing user once before it will do anything for that new user. While this tutorial explained that mechanism, it did not give much hint on how to go about finding someone to allow your new pull request. So, teach our new GitGitGadget user where to look for someone who can add their name to the list.

The advice in this patch is based on the advice proposed for
GitGitGadget: https://github.com/gitgitgadget/gitgitgadget/pull/138

---
 Documentation/MyFirstContribution.txt | 8 ++++++++
 1 file changed, 8 insertions(+)
Documentation/MyFirstContribution.txt +8 -0
index b8ffeda07e..2de06de026 100644
@@ -789,6 +789,14 @@ will automatically run your PRs through the CI even without the permission given
 but you will not be able to `/submit` your changes until someone allows you to
 use the tool.
 
+NOTE: You can typically find someone who can `/allow` you on GitGitGadget by
+either examining recent pull requests where someone has been granted `/allow`
+(https://github.com/gitgitgadget/git/pulls?utf8=%E2%9C%93&q=is%3Apr+is%3Aopen+%22%2Fallow%22[Search:
+is:pr is:open "/allow"]), in which case both the author and the person who
+granted the `/allow` can now `/allow` you, or by inquiring on the
+https://webchat.freenode.net/#git-devel[#git-devel] IRC channel on Freenode
+linking your pull request and asking for someone to `/allow` you.
+
 If the CI fails, you can update your changes with `git rebase -i` and push your
 branch again:
 
Signature · 1 line
2.24.0.rc0.303.g954a862665-goog
Reviewed-by on v1 3/3
#12 lore raw

Re: [PATCH 3/3] myfirstcontrib: hint to find gitgitgadget allower

Quoted 8 lines · Emily Shaffer

GitGitGadget, a handy tool for converting pull requests against Git into Git-mailing-list-friendly-patch-emails, requires as anti-spam that all new users be "/allow"ed by an existing user once before it will do anything for that new user. While this tutorial explained that mechanism, it did not give much hint on how to go about finding someone to allow your new pull request. So, teach our new GitGitGadget user where to look for someone who can add their name to the list.

Quoted 7 lines

The advice in this patch is based on the advice proposed for
GitGitGadget: https://github.com/gitgitgadget/gitgitgadget/pull/138

---
 Documentation/MyFirstContribution.txt | 8 ++++++++
 1 file changed, 8 insertions(+)

Though I'd appreciate an ack from a gitgitgadget specialist too, so cc-ing Dscho.

Quoted 19 lines
Documentation/MyFirstContribution.txt +8 -0
index b8ffeda07e..2de06de026 100644
@@ -789,6 +789,14 @@ will automatically run your PRs through the CI even without the permission given
 but you will not be able to `/submit` your changes until someone allows you to
 use the tool.
 
+NOTE: You can typically find someone who can `/allow` you on GitGitGadget by
+either examining recent pull requests where someone has been granted `/allow`
+(https://github.com/gitgitgadget/git/pulls?utf8=%E2%9C%93&q=is%3Apr+is%3Aopen+%22%2Fallow%22[Search:
+is:pr is:open "/allow"]), in which case both the author and the person who
+granted the `/allow` can now `/allow` you, or by inquiring on the
+https://webchat.freenode.net/#git-devel[#git-devel] IRC channel on Freenode
+linking your pull request and asking for someone to `/allow` you.
+
 If the CI fails, you can update your changes with `git rebase -i` and push your
 branch again:
 
#13 lore raw

Re: [PATCH 3/3] myfirstcontrib: hint to find gitgitgadget allower

Hi Jonathan,

Quoted 18 lines · Jonathan Nieder
Quoted 8 lines · Emily Shaffer

GitGitGadget, a handy tool for converting pull requests against Git into Git-mailing-list-friendly-patch-emails, requires as anti-spam that all new users be "/allow"ed by an existing user once before it will do anything for that new user. While this tutorial explained that mechanism, it did not give much hint on how to go about finding someone to allow your new pull request. So, teach our new GitGitGadget user where to look for someone who can add their name to the list.

Quoted 7 lines

The advice in this patch is based on the advice proposed for
GitGitGadget: https://github.com/gitgitgadget/gitgitgadget/pull/138

---
 Documentation/MyFirstContribution.txt | 8 ++++++++
 1 file changed, 8 insertions(+)
Quoted 4 lines

Though I'd appreciate an ack from a gitgitgadget specialist too, so cc-ing Dscho.

Seeing as the suggestions from gitgitgadget/gitgitgadget#138 partially came from me (and that I merged that PR after reviewing it), this comes very easily:

Thanks,
Dscho

Quoted 21 lines
Quoted 20 lines
Documentation/MyFirstContribution.txt +8 -0
index b8ffeda07e..2de06de026 100644
@@ -789,6 +789,14 @@ will automatically run your PRs through the CI even without the permission given
 but you will not be able to `/submit` your changes until someone allows you to
 use the tool.
 
+NOTE: You can typically find someone who can `/allow` you on GitGitGadget by
+either examining recent pull requests where someone has been granted `/allow`
+(https://github.com/gitgitgadget/git/pulls?utf8=%E2%9C%93&q=is%3Apr+is%3Aopen+%22%2Fallow%22[Search:
+is:pr is:open "/allow"]), in which case both the author and the person who
+granted the `/allow` can now `/allow` you, or by inquiring on the
+https://webchat.freenode.net/#git-devel[#git-devel] IRC channel on Freenode
+linking your pull request and asking for someone to `/allow` you.
+
 If the CI fails, you can update your changes with `git rebase -i` and push your
 branch again:
 
#14 lore raw

Re: [PATCH 3/3] myfirstcontrib: hint to find gitgitgadget allower

In reply to Emily Shaffer
Quoted 6 lines · Emily Shaffer
Documentation/MyFirstContribution.txt +0 -0
index b8ffeda07e..2de06de026 100644

Documentation/MyFirstContribution.txt will automatically run your PRs through the CI even without the permission given · line 798

Quoted 10 lines
Documentation/MyFirstContribution.txt +7 -0
@@ -789,6 +789,14 @@ will automatically run your PRs through the CI even without the permission given
 but you will not be able to `/submit` your changes until someone allows you to
 use the tool.
 
+NOTE: You can typically find someone who can `/allow` you on GitGitGadget by
+either examining recent pull requests where someone has been granted `/allow`
+(https://github.com/gitgitgadget/git/pulls?utf8=%E2%9C%93&q=is%3Apr+is%3Aopen+%22%2Fallow%22[Search:
+is:pr is:open "/allow"]), in which case both the author and the person who
+granted the `/allow` can now `/allow` you, or by inquiring on the
+https://webchat.freenode.net/#git-devel[#git-devel] IRC channel on Freenode
+linking your pull request and asking for someone to `/allow` you.

Nit: that's a lot to put in a single sentence. Maybe break it into parts like:

NOTE: You can typically find someone who can /allow you on GitGitGadget by looking at recent pull requests where someone has been /allowed. Both the author of that pull request and the person who granted the permission can now /allow you. You can also inquire on the IRC channel on Freenode linking your pull request and asking someone to /allow you.

Quoted 3 lines
Documentation/MyFirstContribution.txt +1 -0
+
 If the CI fails, you can update your changes with `git rebase -i` and push your
 branch again:
Signature · 2 lines
Regards,
Pratyush Yadav
#15 lore raw
In reply to Emily Shaffer
Quoted 4 lines · Emily Shaffer

[1/3] Per SZEDER's comment, we should be adding git psuh to the list
of commands used by 'git help'.
[2/3] Outreachy applicant Heba Waly indicated that the tutorial doesn't
cover dependencies needed to build Git.

Oh! It's also a good idea to give these people credit for their contribution, via a Reported-by in the commit message.

Sorry I missed it before (I tend to read the patches first and cover letter last, which is good for ensuring the commit messages are self contained enough to be helpful when the patch gets dug up in history later, but not so good for noticing this kind of thing).

Thanks,
Jonathan

#16 lore raw

v2 cover some clarifications to MyFirstContribution

In reply to Emily Shaffer

With adjustments to install step based on email comments, plus Reported-by in command-list and install step patches.

- Emily

Emily Shaffer (3):
myfirstcontrib: add 'psuh' to command-list.txt
myfirstcontrib: add dependency installation step
myfirstcontrib: hint to find gitgitgadget allower

 Documentation/MyFirstContribution.txt | 53 +++++++++++++++++++++++++--
 1 file changed, 50 insertions(+), 3 deletions(-)
Signature · 1 line
2.24.0.rc0.303.g954a862665-goog
#17 lore raw

PATCH v2 1/3 myfirstcontrib: add 'psuh' to command-list.txt

Users can discover commands and their brief usage by running 'git help git' or 'git help -a'; both of these pages list all available commands based on the contents of 'command-list.txt'. That means adding a new command there is an important part of the new command process, and therefore belongs in the new command tutorial.

Teach new users how to add their command, and include a brief overview of how to discover which attributes to place on the command in the list.

Since 'git psuh' prints some workspace info, doesn't modify anything, and is targeted as a user-facing porcelain command, list it as a 'mainporcelain' and 'info' command.

As the usage string is required to generate this documentation, don't add the command to the list until after the usage string is added to the tutorial.

---
 Documentation/MyFirstContribution.txt | 22 ++++++++++++++++++++++
 1 file changed, 22 insertions(+)
Documentation/MyFirstContribution.txt +22 -0
index 5e9b808f5f..12b7256454 100644
@@ -534,6 +534,28 @@ you want to pass as a parameter something which would usually be interpreted as
 a flag.) `parse_options()` will terminate parsing when it reaches `--` and give
 you the rest of the options afterwards, untouched.
 
+Now that you have a usage hint, you can teach Git how to show it in the general
+command list shown by `git help git` or `git help -a`, which is generated from
+`command-list.txt`. Find the line for 'git-pull' so you can add your 'git-psuh'
+line above it in alphabetical order. Now, we can add some attributes about the
+command which impacts where it shows up in the aforementioned help commands. The
+top of `command-list.txt` shares some information about what each attribute
+means; in those help pages, the commands are sorted according to these
+attributes. `git psuh` is user-facing, or porcelain - so we will mark it as
+"mainporcelain". For "mainporcelain" commands, the comments at the top of
+`command-list.txt` indicate we can also optionally add an attribute from another
+list; since `git psuh` shows some information about the user's workspace but
+doesn't modify anything, let's mark it as "info". Make sure to keep your
+attributes in the same style as the rest of `command-list.txt` using spaces to
+align and delineate them:
+
+----
+git-prune-packed                        plumbingmanipulators
+git-psuh                                mainporcelain		info
+git-pull                                mainporcelain           remote
+git-push                                mainporcelain           remote
+----
+
 Build again. Now, when you run with `-h`, you should see your usage printed and
 your command terminated before anything else interesting happens. Great!
 
Signature · 1 line
2.24.0.rc0.303.g954a862665-goog
#18 lore raw

PATCH v2 2/3 myfirstcontrib: add dependency installation step

In reply to Emily Shaffer

Indicate that the user needs some dependencies before the build will run happily on their machine; this dependency list doesn't seem to be made clear anywhere else in the project documentation. Then, so the user can be certain any build failures are due to their code and not their environment, perform a build on a clean checkout of 'master'. Also, move the note about build parallelization up here, so that it appears next to the very first build invocation in the tutorial.

---
 Documentation/MyFirstContribution.txt | 23 ++++++++++++++++++++---
 1 file changed, 20 insertions(+), 3 deletions(-)
Documentation/MyFirstContribution.txt +20 -3
index 12b7256454..5ce94e077c 100644
@@ -38,6 +38,26 @@ $ git clone https://github.com/git/git git
 $ cd git
 ----
 
+[[dependencies]]
+=== Installing Dependencies
+
+To build Git from source, you need to have a handful of dependencies installed
+on your system. For a hint of what's needed, you can take a look at
+`INSTALL`, paying close attention to the section about Git's dependencies on
+external programs and libraries. That document mentions a way to "test-drive"
+our freshly built Git without installing; that's the method we'll be using in
+this tutorial.
+
+Make sure that your environment has everything you need by building your brand
+new clone of Git from the above step:
+
+----
+$ make
+----
+
+NOTE: The Git build is parallelizable. `-j#` is not included above but you can
+use it as you prefer, here and elsewhere.
+
 [[identify-problem]]
 === Identify Problem to Solve
 
@@ -138,9 +158,6 @@ NOTE: When you are developing the Git project, it's preferred that you use the
 `DEVELOPER` flag; if there's some reason it doesn't work for you, you can turn
 it off, but it's a good idea to mention the problem to the mailing list.
 
-NOTE: The Git build is parallelizable. `-j#` is not included above but you can
-use it as you prefer, here and elsewhere.
-
 Great, now your new command builds happily on its own. But nobody invokes it.
 Let's change that.
 
Signature · 1 line
2.24.0.rc0.303.g954a862665-goog
#19 lore raw

PATCH v2 3/3 myfirstcontrib: hint to find gitgitgadget allower

In reply to Emily Shaffer

GitGitGadget, a handy tool for converting pull requests against Git into Git-mailing-list-friendly-patch-emails, requires as anti-spam that all new users be "/allow"ed by an existing user once before it will do anything for that new user. While this tutorial explained that mechanism, it did not give much hint on how to go about finding someone to allow your new pull request. So, teach our new GitGitGadget user where to look for someone who can add their name to the list.

The advice in this patch is based on the advice proposed for
GitGitGadget: https://github.com/gitgitgadget/gitgitgadget/pull/138

---
 Documentation/MyFirstContribution.txt | 8 ++++++++
 1 file changed, 8 insertions(+)
Documentation/MyFirstContribution.txt +8 -0
index 5ce94e077c..b55837e646 100644
@@ -785,6 +785,14 @@ will automatically run your PRs through the CI even without the permission given
 but you will not be able to `/submit` your changes until someone allows you to
 use the tool.
 
+NOTE: You can typically find someone who can `/allow` you on GitGitGadget by
+either examining recent pull requests where someone has been granted `/allow`
+(https://github.com/gitgitgadget/git/pulls?utf8=%E2%9C%93&q=is%3Apr+is%3Aopen+%22%2Fallow%22[Search:
+is:pr is:open "/allow"]), in which case both the author and the person who
+granted the `/allow` can now `/allow` you, or by inquiring on the
+https://webchat.freenode.net/#git-devel[#git-devel] IRC channel on Freenode
+linking your pull request and asking for someone to `/allow` you.
+
 If the CI fails, you can update your changes with `git rebase -i` and push your
 branch again:
 
Signature · 1 line
2.24.0.rc0.303.g954a862665-goog