documentation: add lab for first contribution

Documentation/MyFirstContribution new file +4 -0

+=== Set Up Your Workspace
+
+Let's start by making a development branch to work on our changes. Per
+`Documentation/SubmittingPatches`, since a brand new command is a new feature,

Documentation/MyFirstContribution new file +15 -0

+The options are documented in `builtin.h` under "Adding a new built-in." Since
+we hope to print some data about the user's current workspace context later,
+we need a Git directory, so choose `RUN_SETUP` as your only option.
+
+Go ahead and build again. You should see a clean build, so let's kick the tires
+and see if it works. There's a binary you can use to test with in
+`./bin-wrappers`.
+
+----
+./bin-wrappers/git psuh
+----
+
+Check it out! You've got a command! Nice work! Let's commit this.
+
+----

+=== Implementation
+ ...
+=== Adding documentation
+ ...

Documentation/MyFirstContribution line 4

Quoted 10 lines · Emily Shaffer via GitGitGadget

Documentation/MyFirstContribution new file +4 -0

new file mode 100644
index 0000000000..9b87e424d6
@@ -0,0 +1,674 @@
+My First Contribution
+=====================
+
+== Summary

Just a minor nit but only the document title uses the underlined mark-up format, but not each of its sections?

Is the goal of this document to help those who want to contribute to *THIS* project, or to any project that happens to use Git as their source control tool of choice? I take it to be the former, but if that is the case, perhaps extend the title to "My First Contribution to the Git Project" or something, so that those who use us merely as a tool can tell that it can be ignored more easily?

Quoted 5 lines

Documentation/MyFirstContribution new file +4 -0

+=== Set Up Your Workspace
+
+Let's start by making a development branch to work on our changes. Per
+`Documentation/SubmittingPatches`, since a brand new command is a new feature,

Documentation/MyFirstContribution line 55

Quoted 10 lines

Documentation/MyFirstContribution new file +10 -0

+it's fine to base your work on `master`. However, in the future for bugfixes,
+etc., you should check that doc and base it on the appropriate branch.
+
+For the purposes of this doc, we will base all our work on `master`. Before
+running the command below, ensure that you are on `master` first so your
+branch diverges at the right point.
+
+----
+git checkout -b psuh
+----

An obvious and more explicit alternative, which may be better both for tutorial purposes (as it illustrates what is going on better by not relying on an implicit default) and for real-life (as it does not require checking out 'master' only to switch away from a new branch, saving a entry of two in the HEAD reflog) is

For the purposes of this doc, we will base all our work on the master branch of the upstream project. Fork the psuh branch you use for your development like so:

----
$ git checkout -b psuh origin/master
----

Documentation/MyFirstContribution line 67

Quoted 3 lines

Documentation/MyFirstContribution new file +3 -0

+=== Adding a new command
+
+Lots of the main useful commands are written as builtins, which means they are

Drop 'useful', and possibly 'main' as well. I would have written "Many of the Git subcommands are..." if I were writing it myself without reading yours.

Documentation/MyFirstContribution line 71

Quoted 3 lines

Documentation/MyFirstContribution new file +3 -0

+implemented in C and compiled into the main `git` executable.. So it is
+informative to implement `git psuh` as a builtin.
+Create a new file in `builtin/` called `psuh.c`.

I am not sure what "informative" in this context means.

Typically a built-in subcommand is implemented as a function whose name is "cmd_" followed by the name of the subcommand and stored in a C source file that is named after the name of the subcommand inside builtin/ directory, so it is natural to implement your psuh command as a cmd_psuh() function in builtin/psuh.c.

Documentation/MyFirstContribution line 84

Quoted 11 lines

Documentation/MyFirstContribution new file +11 -0

+The entry point of your new command needs to match a certain signature:
+----
+int cmd_psuh(int argc, const char **argv, const char *prefix)
+----
+
+We'll also need to add the extern declaration of psuh; open up `builtin.h`,
+find the declaration for cmd_push, and add a new line for psuh:
+
+----
+extern int cmd_psuh(int argc, const char **argv, const char *prefix);
+----

I think there is a push to drop the "extern " from decls of functions in *.h header files.

Documentation/MyFirstContribution line 89

Quoted 4 lines

Documentation/MyFirstContribution new file +4 -0

+Be sure to `#include "builtin.h"` in your `psuh.c`.
+
+Go ahead and add some throwaway printf to that method. This is a decent
+starting point as we can now add build rules and register the command.

We are writing in C; don't call a function method.

Documentation/MyFirstContribution line 95

Quoted 7 lines

Documentation/MyFirstContribution new file +6 -0

+
+NOTE: Your throwaway text, as well as much of the text you will be adding over
+the course of this lab, is user-facing. That means it needs to be localizable.
+Take a look at `po/README` under "Marking strings for translation". Throughout
+the lab, we will mark strings for translation as necessary; you should also do
+so when writing your user-facing commands in the future.

Good. I think that it is beneficial to give a more concrete example, rather than leaving at saying "type any throwaway printf", perhaps like:

        ----
        int cmd_psuh(int ac, const char *av, const char *prefix)
        {
                printf(_("Pony says Uh, hello!\n"));
                return 0;
        }
        ----

at this point. That illustrates _() and also the fact that successful command execution is concluded by returning 0 from the service function.

Documentation/MyFirstContribution line 98

Quoted 3 lines

Documentation/MyFirstContribution new file +2 -0

+Let's try to build it.  Open Makefile, find where `builtin/push.o` is added
+to BUILTIN_OBJS, and add `builtin/psuh.o` in the same way. Once you've done so,

In the same way "next to it"? Do we want to say taht we are trying to keep these lines sorted?

Documentation/MyFirstContribution line 100

Quoted 2 lines

Documentation/MyFirstContribution new file +2 -0

+move to the root directory and build simply with `make -j$(nproc)`. Optionally, add
+the DEVELOPER=1 variable to turn on some additional warnings:

We tend to avoid saying root and instead say the top-level directory, to avoid clueless literally doing "cd / && make" ;-).

As this is a developer-facing document, not making DEVELOPER=1 optional is preferrable. Only when you are on a platform where DEVELOPER=1 does not work well for you, optionally it is OK to drop it.

Is it needed to say -j$(nproc) here, by the way? That's a preference highly personal. I wouldn't write

        $ time nice -20 make -j

in a toturial I'd be writing, even if that is what I might often use, and I expect those developers who are hacking Git to know how to run $(MAKE) in a way appropriate for their boxes.

Documentation/MyFirstContribution line 51

Quoted 3 lines

Documentation/MyFirstContribution new file +2 -0

+----
+echo DEVELOPER=1 > config.mak

Follow the Documentation/CodingGuildelines when writing for our developers. Lose SP between the redirection operator and its target filename.

Quoted 3 lines

Documentation/MyFirstContribution new file +2 -0

+make -j$(nproc)
+----

Documentation/MyFirstContribution line 108

Quoted 3 lines

Documentation/MyFirstContribution new file +3 -0

+
+Great, now your new command builds happily on its own. But nobody invokes it.
+Let's change that.

This is a tangent, but if we want to show off check-docs at this point or perhaps a bit later, where it would notice that psuh is implemented but not documented.

Documentation/MyFirstContribution line 114

Quoted 5 lines

Documentation/MyFirstContribution new file +5 -0

+The list of commands lives in `git.c`. We can register a new command by adding
+a cmd_struct to the commands[] array. struct cmd_struct takes a string with the
+command name, a function pointer to the command implementation, and a setup
+option flag. For now, let's keep cheating off of push. Find the line where
+cmd_push is registered, copy it, and modify it for cmd_psuh.

Right now, the elements in commands[] can be in any order, if I am not mistaken in reading get_builtin(). It might want to be updated, though, so recommanding to meek the list sorted may not be a bad idea.

Quoted 20 lines

Documentation/MyFirstContribution new file +19 -0

+The options are documented in `builtin.h` under "Adding a new built-in." Since
+we hope to print some data about the user's current workspace context later,
+we need a Git directory, so choose `RUN_SETUP` as your only option.
+
+Go ahead and build again. You should see a clean build, so let's kick the tires
+and see if it works. There's a binary you can use to test with in
+`./bin-wrappers`.
+
+----
+./bin-wrappers/git psuh
+----
+
+Check it out! You've got a command! Nice work! Let's commit this.
+
+----
+git add Makefile builtin.h builtin/psuh.c git.c
+git commit -s
+----
+

Documentation/MyFirstContribution line 140

Quoted 6 lines

Documentation/MyFirstContribution new file +6 -0

+Consider something like the following as your commit message. Start the commit
+with a 50-column or less subject line, including the name of the component
+you're working on. Remember to be explicit and provide the "Why" of your commit,
+especially if it couldn't easily be understood from your diff. When editing
+your commit message, don't remove the Signed-off-by line which was added by `-s`
+above.

... then leave it in your example, perhaps?

Quoted 6 lines

Documentation/MyFirstContribution new file +6 -0

+
+----
+psuh: add a new built-in by popular demand
+
+Internal metrics indicate this is a command many users expect to be
+present. So here's an implementation to help drive customer

Documentation/MyFirstContribution line 152

Quoted 6 lines

Documentation/MyFirstContribution new file +6 -0

+satisfaction and engagement: a pony which doubtfully greets the user,
+or, a Pony Saying "Um, Hello" (PSUH).
+
+This commit message is intentionally formatted to 72 columns per line,
+starts with a single line as "commit message subject" that uses the
+imperative present tense, and is designed to add information about the

There is no imperative past tense ;-)

Use "that is written in the imperative mood" instead if you want to be grammatical, or alternatively "that is written as if giving an order to the codebase to 'be like so'" (it actually is giving an order to the patch-monkey at the other end of your e-mail submission to do so ;-).

Documentation/MyFirstContribution line 154

Quoted 3 lines

Documentation/MyFirstContribution new file +2 -0

+commit that is not readily deduced from reading the associated diff,
+such as answering the question "why?".

Nicely written.

Keep a sample sign-off by "A U Thor <[email protected]>" here.

Documentation/MyFirstContribution line 166

Quoted 12 lines

Documentation/MyFirstContribution new file +12 -0

+----
+
+Go ahead and inspect your new commit with `git show`. "psuh:" indicates you
+have modified mainly the `psuh` command. The subject line gives readers an idea
+of what you've changed. The signed-off line (-s) indicates that you agree to
+the Developer's Certificate of Origin 1.1 (see the SubmittingPatches [[dco]]
+header). If you wish to add some context to your change, go ahead with
+`git commit --amend`.
+
+For the remainder of the tutorial, the subject line only will be listed for the
+sake of brevity. However, fully-fleshed example commit messages are available
+on the reference implementation linked at the top of this document.

OK.

Documentation/MyFirstContribution line 246

Quoted 4 lines

Documentation/MyFirstContribution new file +4 -0

+=== Implementation
+ ...
+=== Adding documentation
+ ...

After skimming the remainder of your draft, i am not sure if this order of presentation is the best one.

My personal preference is to make a small progress in the implementation and then immediately after that add a test, whose first iteration might even look like:

#!/bin/sh
test_description="test git psuh"
. ./test-lib.sh

test_expect_success setup '
: nothing special yet
'

test_expect_success 'git psuh succeeds without an argument' '
git psuh
'

test_done

But that may make the very initial step a bit too broad for a new develoepr to grok. I dunno.

I like this suggestion, but don't like the use of "fork" as it somewhat conflates
a GitHub-specific term. I'll take this recommendation but use "create" instead of "fork".

Quoted 2 lines

... then leave it in your example, perhaps?

Good point. :) I had wanted to avoid including my own name/email in the tutorial; I used a throwaway "Git Contributor <[email protected]>" for the example.
...

Quoted 1 line

Keep a sample sign-off by "A U Thor <[email protected]>" here.

Do folks on Git project usually engage in test-driven development? I would be happy to move the test up towards the front of the document and mention the usefulness of TDD, but not if that's not something emphasized usually by the group..

Quoted 6 lines

Quoted 2 lines

... then leave it in your example, perhaps?

Good point. :) I had wanted to avoid including my own name/email in the tutorial; I used a throwaway "Git Contributor <[email protected]>" for the example.
...

Quoted 1 line

Quoted 1 line

Keep a sample sign-off by "A U Thor <[email protected]>" here.

No, use "A U Thor <[email protected]>" as I suggested. That's the author ident the aspiring Git developer MUST become familiar with while working with our test suite in t/. There you will also find the counterpart committer ident to use, if needed.

Just FYI, I rarely give a "do it exactly like this" suggestion; often I instead stop at giving a general direction and leave it up to the contributers to perfect it. The "A U Thor" is one of those rare cases. On the other hand, "fork" was *not*.

Quoted 5 lines

Do folks on Git project usually engage in test-driven development? I would be happy to move the test up towards the front of the document and mention the usefulness of TDD, but not if that's not something emphasized usually by the group..

I have no strong opinion on this myself.

I suspect that the developer would clean up with "rebase -i" by squashing before submitting the result of a very fine-grained TDD workflow, as nobody would want to read printf("hello world") in [PATCH 1/47] that would become a real feature in a later step. So if the tutorial wants to go into that tangent (which might be too much detail), it may be worth showing from the first few commits, but otherwise a sequence that pretends the reader to be a perfect developer who does not make any mistake in the middle may be more concise and more readable. I dunno.

Thanks.

RFC. I am still working on adding a section on handling refs and objects.

A tutorial for beginners explaining how to commit to git/git from clone to push. This tutorial attempts to explain the GitGitGadget workflow; with the review I'm hoping to understand whether it's worth the effort to detail how to use git send-email as well. The linked implementation is present in my personal fork and I'd be happy for any comments people wish to give against that implementation, too, although it obviously isn't destined for git/git. I wrote this guide in order to learn the process myself, so I welcome all feedback.

Additionally, if there are skills around working with the codebase that should really be included in the "Implementation" section I'd be happy to add them.

Emily Shaffer (1):
documentation: add lab for first contribution

 Documentation/MyFirstContribution | 674 ++++++++++++++++++++++++++++++
 1 file changed, 674 insertions(+)
 create mode 100644 Documentation/MyFirstContribution

base-commit: e35b8cb8e212e3557efc565157ceb5cbaaf0d87f
Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-177%2Fnasamuffin%2Fmyfirstcontrib-v1
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-177/nasamuffin/myfirstcontrib-v1
Pull-Request: https://github.com/gitgitgadget/git/pull/177

Signature · 1 line

gitgitgadget

RFC. I am still working on adding a section on handling refs and objects.

Quoted 1 line · Emily Shaffer via GitGitGadget

RFC. I am still working on adding a section on handling refs and objects.

Thanks. Is 'lab' understood widely enough? I _think_ you are abbreviating what is known as 'codelab' by your colleagues at work, but would it make it more in line with what we already have in this project, perhaps, to call it a "tutorial"?

Subject: Re: [PATCH v2 1/1] documentation: add lab for first contribution
From: Emily Shaffer <[email protected]>

This code lab covers how to add a new command to Git and, in the process, everything from cloning git/git to getting reviewed on the mail

Documentation/Makefile +2 -0

index 26a2342bea..af303c2419 100644
@@ -74,6 +74,7 @@ API_DOCS = $(patsubst %.txt,%,$(filter-out technical/api-index-skel.txt technica
 SP_ARTICLES += $(API_DOCS)
 
 TECH_DOCS += SubmittingPatches
+TECH_DOCS += MyFirstContribution
 TECH_DOCS += technical/hash-function-transition
 TECH_DOCS += technical/http-protocol
 TECH_DOCS += technical/index-format

@@ -338,6 +339,7 @@ clean:
 	$(RM) howto-index.txt howto/*.html doc.dep
 	$(RM) technical/*.html technical/api-index.txt
 	$(RM) SubmittingPatches.txt
+	$(RM) MyFirstContribution.txt
 	$(RM) $(cmds_txt) $(mergetools_txt) *.made
 	$(RM) manpage-base-url.xsl
 

+Consider something like the following as your commit message. Start the commit

+...

Documentation/Makefile +13 -0

+
+git_config(git_default_config, NULL)
+if (git_config_get_string_const("user.name", &cfg_name) > 0)
+{
+	printf(_("No name is found in config\n"));
+}
+else
+{
+	printf(_("Your name: %s\n"), cfg_name);
+}
+----
+
+git_config(...) will grab the configuration from config files known to Git and

Documentation/Makefile +10 -0

+Still, it'd be nice to know what the user's working context is like. Let's see
+if we can print the name of the user's current branch. We can cheat off of the
+`git status` implementation; the printer is located in `wt-status.c` and we can
+see that the branch is held in a `struct wt_status`.  `wt_status_print()` gets
+invoked by `cmd_status()` in `builtin/commit.c`. Looking at that implementation
+we see the status config being populated like so:
+
+----
+status_init_config(&s, git_status_config);
+----

Documentation/Makefile +16 -0

+Run it again. Check it out - here's the (verbose) name of your current branch!
+
+Let's commit this as well.
+
+----
+git commit -sm "psuh: print the current branch"
+----
+
+Now let's see if we can get some info about a specific commit.
+
+Luckily, there are some helpers for us here. `commit.h` has a function called
+`lookup_commit_reference_by_name` to which we can simply provide a hardcoded
+string; `pretty.h` has an extremely handy `pp_commit_easy()` call which doesn't
+require a full format object to be passed.
+
+Add the following:

Documentation/Makefile +6 -0

+	pp_commit_easy(CMIT_FMT_ONELINE, c, &commitline);
+	printf(_("Current commit: %s\n"), commitline.buf);
+}
+----
+
+The `struct strbuf` provides some safety belts to your basic `char*`, one of

+=== Adding documentation

Documentation/Makefile +10 -0

+
+Awesome! You've got a fantastic new command that you're ready to share with the
+community. But hang on just a minute - this isn't very user-friendly. Run the
+following:
+
+----
+./bin-wrappers/git help psuh
+----
+
+Your new command is undocumented! Let's fix that.

+Then, within your cmd_psuh implementation, we can declare and populate our

+option struct. Ours is pretty boring but you can add more to it if you like:

+----

Documentation/Makefile +5 -0

+	struct option options[] = {
+		OPT_END()
+	};
+----
+

Documentation/Makefile +26 -0

+Related reading: `t/README`
+
+=== Overview of Testing Structure
+
+The tests in Git live in t/ and are named with a 4-decimal digit, according to
+the schema shown in the Naming Tests section of `t/README`.
+
+=== Writing Your Test
+
+Since this a toy command, let's go ahead and name the test with t9999. However,
+as many of the family/subcmd combinations are full, best practice seems to be
+to find a command close enough to the one you've added and share its naming
+space.
+
+Create your test script and mark it executable:
+
+----
+touch t/t9999-psuh-codelab.sh
+chmod +x t/t9999-psuh-codelab.sh
+----
+
+Begin with the header as so (see
+"Writing Tests" and "Source 'test-lib.sh'" in `t/README`):
+
+----
+#!/bin/sh

Documentation/Makefile +23 -0

+Here's an example of a cover letter for `git psuh`:
+
+----
+Our internal metrics indicate widespread interest in the command
+git-psuh - that is, many users are trying to use it, but finding it is
+unavailable, using some unknown workaround instead.
+
+The following handful of patches add the psuh command and implement some
+handy features on top of it.
+
+This patchset is part of the MyFirstContribution codelab and should not
+be merged.
+
+ Documentation/git-psuh.txt | 40 +++++++++++++++++++
+ Makefile                   |  1 +
+ builtin.h                  |  1 +
+ builtin/psuh.c             | 78 ++++++++++++++++++++++++++++++++++++++
+ git.c                      |  1 +
+ t/t9999-psuh-codelab.sh    | 12 ++++++
+ 6 files changed, 133 insertions(+)
+----
+
+NOTE: When you've got a real change to send, you'll use `[email protected]`

Documentation/Makefile +14 -0

+has a plaintext email mode; the Git list rejects HTML email.) Please also follow
+the mailing list etiquette outlined in the 
+https://kernel.googlesource.com/pub/scm/git/git/+/todo/MaintNotes[Maintainer's
+Note], which are similar to etiquette rules in most open source communities
+surrounding bottom-posting and inline replies.
+
+////
+TODO - mail list etiquette
+////
+
+You should apply changes using interactive rebase, or by adding new commits if
+the changes seem to require it.
+
+NOTE: Interactive rebase can be tricky; check out this handy

+== Now What?

Documentation/Makefile +4 -0

+
+The Git project has four integration branches: `pu`, `next`, `master`, and
+`maint`. Your change will be placed into `pu` fairly early on by the maintainer
+while it is still in the review process; from there, when it is ready for wider

Documentation/MyFirstContribution line 405

Quoted 5 lines · Emily Shaffer via GitGitGadget

Documentation/MyFirstContribution new file +5 -0

+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:
+
+make all doc
+man Documentation/git-psuh.1

Hmph. I didn't know you can do that without "-l" (local) option. Perhaps with "-l" spelled out, it might be more portable but I dunno.

Quoted 10 lines · Junio C Hamano

Documentation/MyFirstContribution line 405

Quoted 5 lines · Emily Shaffer via GitGitGadget

Documentation/MyFirstContribution new file +5 -0

+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:
+
+make all doc
+man Documentation/git-psuh.1

Hmph. I didn't know you can do that without "-l" (local) option. Perhaps with "-l" spelled out, it might be more portable but I dunno.

It's more portable[1] to eschew the -l (local) option to 'man'.

[1]: http://public-inbox.org/git/[email protected]/

Quoted 2 lines

This code lab covers how to add a new command to Git and, in the process, everything from cloning git/git to getting reviewed on the mail

"lab"? I thought we settled on "tutorial". Also the place we are having conversation we call "mailing list", I think.

Documentation/Makefile $(patsubst %,%.html,$(API_DOCS) technical/api-index $(TECH_DOCS)): %.html : %.tx · line 385

Quoted 2 lines

Documentation/Makefile +2 -0

+MyFirstContribution.txt: MyFirstContribution
+     $(QUIET_GEN) cp $< $@

Hmph.

Unlike SubmittingPatches that has known as that specific filename for a long time before we added to the *.txt -> *.html toolchain (hence people may look for it without the *.txt suffix), I do not immediately see why the source of this new tutorial needs a variant without the suffix. Is there a reason why this new file cannot be created as Documentaiton/MyFirstContribution.txt that I am missing?

Documentation/MyFirstContribution line 27

Quoted 6 lines

+== Getting Started

Documentation/MyFirstContribution new file +5 -0

+
+=== Pull the Git codebase
+
+Git is mirrored in a number of locations. https://git-scm.com/downloads
+suggests the best place to clone from is GitHub.

"suggests that one of the best places ..."?

Documentation/MyFirstContribution line 47

Quoted 4 lines

Documentation/MyFirstContribution new file +4 -0

+Let's start by making a development branch to work on our changes. Per
+`Documentation/SubmittingPatches`, since a brand new command is a new feature,
+it's fine to base your work on `master`. However, in the future for bugfixes,
+etc., you should check that doc and base it on the appropriate branch.

Avoid unnecessary abbreviation; s/doc/document/. Same for "lab", if we are to call this "codelab" instead of "tutorial". I won't repeat this for brevity, but I see many instances of them.

Documentation/MyFirstContribution line 55

Quoted 7 lines

Documentation/MyFirstContribution new file +7 -0

+For the purposes of this doc, we will base all our work on the `master` branch
+of the upstream project. Create the `psuh` branch you will use for development
+like so:
+
+----
+git checkout -b psuh origin/master
+----

        ----
        $ git checkout -b psuh origin/master
        ----

I think both of our existing tutorials spell out the shell prompt to clarify what these lines are. It would especially help in this document, where you have other monospaced display material that are not commands to be typed but code snippets.

Documentation/MyFirstContribution line 58

Quoted 4 lines

Documentation/MyFirstContribution new file +3 -0

+
+We'll make a number of commits here in order to demonstrate how to send many
+patches up for review simultaneously.

I'd write "a topic with multiple patches" instead of "many patches". The point being that we are not sending a group of unrelated changes, but are focusing on a theme.

Quoted 5 lines

+== Code It Up!

Documentation/MyFirstContribution new file +4 -0

+
+NOTE: A reference implementation can be found at
+https://github.com/nasamuffin/git/tree/psuh.
+

Review

Quoted 3 lines

+=== Adding a new command

(quoted diff) +2 -0

+
+Lots of the main useful commands are written as builtins, which means they are

I'd say "the subcommands" without "main" or "useful". There are fringe subcommands that are implemented as built-in, there are main useful commands that are not built-in, and "useful"-ness is in the eyes of beholder.

Documentation/MyFirstContribution line 69

Quoted 2 lines

Documentation/MyFirstContribution new file +2 -0

+implemented in C and compiled into the main `git` executable. Since they are so
+common, it is a useful exercise to implement `git psuh` as a builtin subcommand.

What does "they" refer to in this sentence? Exiting built-in commands are so common? In what way are they "common"? They are commonly used? That is not relevant in the choice of making 'git psuh' a built-in or a standalone.

Adding a new built-in command, if it were common, may be a good target for illustration. But it is not all that common.

Adding a built-in command requires you to understand the start-up sequence to the exit status, and serves as a good end-to-end exercise, if this tutorial's main aim is to give a tour of the codebase and its internal API. An almost no-op "git psuh" built-in is small enough to serve as a good end-to-end exercise, without requiring the author to know much about the internal API, and would be a good material to show how the contributor, the reviewers and the maintainer work together to add it to the system.

So "they are so common" is probably not a good excuse, even though using git psuh may be a good exercise for the purpose of this tutorial.

Since adding an almost no-op built-in command is relatively simple, it is a good material to demonstrate how you as an individual contributor, the reviewers and the maintainer work together to integrate such a change to the system.

perhaps?

Documentation/MyFirstContribution line 74

Quoted 4 lines

Documentation/MyFirstContribution new file +4 -0

+Built-in subcommands are typically implemented in a function named "cmd_"
+followed by the name of the subcommand, in a source file named after the
+subcommand and contained within `builtin/`. So it makes sense to implement your
+command in `builtin/psuh.c`. Create that file, and within, write the entry point

s/within/& it/ perhaps?

Documentation/MyFirstContribution line 82

Quoted 8 lines

Documentation/MyFirstContribution new file +8 -0

+for your command in a function matching the style and signature:
+
+----
+int cmd_psuh(int argc, const char **argv, const char *prefix)
+----
+
+We'll also need to add the extern declaration of psuh; open up `builtin.h`,
+find the declaration for cmd_push, and add a new line for psuh:

s/:/ immediately before it, to keep the declarations sorted&/ perhaps.

Documentation/MyFirstContribution line 141

Quoted 7 lines

Documentation/MyFirstContribution new file +7 -0

+The options are documented in `builtin.h` under "Adding a new built-in." Since
+we hope to print some data about the user's current workspace context later,
+we need a Git directory, so choose `RUN_SETUP` as your only option.
+
+Go ahead and build again. You should see a clean build, so let's kick the tires
+and see if it works. There's a binary you can use to test with in
+`./bin-wrappers`.

... in bin-wrappers directory.

Quoted 1 line

+Consider something like the following as your commit message. Start the commit

I'd drop the first sentence, and instead say "You'll see something like this in your editor" just before the sample.

Documentation/MyFirstContribution line 156

Quoted 2 lines

Documentation/MyFirstContribution new file +2 -0

+with a 50-column or less subject line, including the name of the component
+you're working on. Remember to be explicit and provide the "Why" of your commit,

s/your commit/your change/;

Documentation/MyFirstContribution line 162

Quoted 6 lines

Documentation/MyFirstContribution new file +6 -0

+especially if it couldn't easily be understood from your diff. When editing
+your commit message, don't remove the Signed-off-by line which was added by `-s`
+above.
+
+----
+psuh: add a new built-in by popular demand

I probably would not even say "new" (what you add did not exist before, so it is redundant) and spend the bits elsewhere (perhaps by spelling out "built-in command").

Quoted 8 lines

Documentation/MyFirstContribution new file +8 -0

+
+Internal metrics indicate this is a command many users expect to be
+present. So here's an implementation to help drive customer
+satisfaction and engagement: a pony which doubtfully greets the user,
+or, a Pony Saying "Um, Hello" (PSUH).
+
+This commit message is intentionally formatted to 72 columns per line,
+starts with a single line as "commit message subject" that is written as

Documentation/MyFirstContribution line 174

Quoted 4 lines

Documentation/MyFirstContribution new file +4 -0

+if to command the codebase to do something (add this, teach a command
+that). The body of the message is designed to add information about the
+commit that is not readily deduced from reading the associated diff,
+such as answering the question "why?".

If you can actually rephrase to make the above into a rectangular text with 72-columns wide, that would be perfect ;-) I certainly would not insist.

Documentation/MyFirstContribution line 181

Quoted 7 lines

Documentation/MyFirstContribution new file +7 -0

+
+Signed-off-by: A U Thor <[email protected]>
+----
+
+Go ahead and inspect your new commit with `git show`. "psuh:" indicates you
+have modified mainly the `psuh` command. The subject line gives readers an idea
+of what you've changed. The signed-off line (-s) indicates that you agree to

Either "sign-off line" or "signed-off-by line".

Documentation/MyFirstContribution line 188

Quoted 7 lines

Documentation/MyFirstContribution new file +7 -0

+the Developer's Certificate of Origin 1.1 (see the SubmittingPatches [[dco]]
+header). If you wish to add some context to your change, go ahead with
+`git commit --amend`.
+
+For the remainder of the tutorial, the subject line only will be listed for the
+sake of brevity. However, fully-fleshed example commit messages are available
+on the reference implementation linked at the top of this document.

Good.

Documentation/MyFirstContribution line 192

Quoted 3 lines

+=== Implementation

Documentation/MyFirstContribution new file +2 -0

+
+It's probably useful to do at least something besides print out a string. Let's

s/print/&ing/

Quoted 5 lines

Documentation/MyFirstContribution new file +5 -0

+start by having a look at everything we get.
+
+Modify your `cmd_psuh` implementation to dump the args you're passed:
+
+----

Documentation/MyFirstContribution line 202

Quoted 5 lines

Documentation/MyFirstContribution new file +5 -0

+     printf(Q_("Your args (there is %i):\n",
+               "Your args (there are %i):\n",
+               argc),
+            argc);
+     for (int i = 0; i < argc; i++) {

I do not think we use this particular C99; define 'int i' at the beginning of the function, not for the loop..

Quoted 1 line

+ printf("%s\n", argv[i]);

Personal preference: printf("%d: %s\n", i, argv[i]);

Documentation/MyFirstContribution line 205

Quoted 3 lines

Documentation/MyFirstContribution new file +2 -0

+     }
+     printf(_("Your prefix:\n%s\n"), prefix);

I think prefix can be NULL. Not just in a bare repository but most notably at the top-level of the working tree.

Documentation/MyFirstContribution line 216

Quoted 11 lines

+----

Documentation/MyFirstContribution new file +10 -0

+
+As you may expect, there's pretty much just whatever we give 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"`. Then, add the following bits:
+
+----
+const char *cfg_name;

Not file-scope static?

Ah, adding to the function's set of local variables? Explicitly say so when you instruct "add the following bits", e.g. "... to the function body".

Indenting the material a bit, the same way as you have the previous code block, may also help.

Quoted 15 lines

+...

Documentation/MyFirstContribution new file +13 -0

+
+git_config(git_default_config, NULL)
+if (git_config_get_string_const("user.name", &cfg_name) > 0)
+{
+     printf(_("No name is found in config\n"));
+}
+else
+{
+     printf(_("Your name: %s\n"), cfg_name);
+}
+----
+
+git_config(...) will grab the configuration from config files known to Git and

Documentation/MyFirstContribution line 241

Quoted 10 lines

Documentation/MyFirstContribution new file +10 -0

+apply standard precedence rules. git_config_get_string_const(...) will look up
+a specific key ("user.name") and give you the value. There are a number of
+single-key lookup functions like this one; you can see them all (and more info
+about how to use git_config()) in `Documentation/technical/api-config.txt`.
+
+You should see that the name printed matches the one you see when you run:
+
+----
+git config --get user.name
+----

        ----
        $ git config --get user.name
        ----

(I won't repeat this for brevity).

Documentation/MyFirstContribution line 250

Quoted 8 lines

Documentation/MyFirstContribution new file +8 -0

+Great! Now we know how to check for values in the git config. Let's commit this
+too, so we don't lose our progress.
+
+----
+git add builtin/psuh.c
+git commit -sm "psuh: show parameters & config opts"
+----
+

For this first "abbreviated" example, it probably is worth repeating

(Again, the above is merely for brevity of the tutorial---in a real project, do not use "commit -m" but use the editor and write a real message).

immediately after the example.

Quoted 10 lines

Documentation/MyFirstContribution new file +10 -0

+Still, it'd be nice to know what the user's working context is like. Let's see
+if we can print the name of the user's current branch. We can cheat off of the
+`git status` implementation; the printer is located in `wt-status.c` and we can
+see that the branch is held in a `struct wt_status`.  `wt_status_print()` gets
+invoked by `cmd_status()` in `builtin/commit.c`. Looking at that implementation
+we see the status config being populated like so:
+
+----
+status_init_config(&s, git_status_config);
+----

Documentation/MyFirstContribution line 270

Quoted 10 lines

Documentation/MyFirstContribution new file +10 -0

+
+But as we drill down, we can find that `status_init_config()` wraps a call
+to `git_config()`. Let's modify the code we wrote in the previous commit.
+
+----
+#include "wt-status.h"
+
+...
+
+// Add a wt_status to fill at the top.

We do not use // comments. I think this actually is taking advangage of the fact and giving a meta-comment that would not enter into the student's code, but if that is what is going on, perhaps tell it explicitly upfront to help readers, perhaps like:

Throughout this tutorial, you may see in-code comment that uses the double-dash // comment. These are not to be used in the Git codebase---instead we are giving readers a meta comment to explain what is going on in the example.

or something.

Quoted 7 lines

Documentation/MyFirstContribution new file +7 -0

+struct wt_status status;
+
+...
+
+// modify the prior code:
+wt_status_prepare(the_repository, &status);
+git_config(git_default_config, &status);

Documentation/MyFirstContribution line 282

Quoted 5 lines

Documentation/MyFirstContribution new file +5 -0

+
+...
+
+printf(_("Your current branch: %s\n"), status.branch);
+----

The same "is this done inside the function? If so say so and indent" comment applies to this part.

Quoted 16 lines

Documentation/MyFirstContribution new file +16 -0

+Run it again. Check it out - here's the (verbose) name of your current branch!
+
+Let's commit this as well.
+
+----
+git commit -sm "psuh: print the current branch"
+----
+
+Now let's see if we can get some info about a specific commit.
+
+Luckily, there are some helpers for us here. `commit.h` has a function called
+`lookup_commit_reference_by_name` to which we can simply provide a hardcoded
+string; `pretty.h` has an extremely handy `pp_commit_easy()` call which doesn't
+require a full format object to be passed.
+
+Add the following:

Documentation/MyFirstContribution line 309

Quoted 10 lines

Documentation/MyFirstContribution new file +10 -0

+
+----
+#include "commit.h"
+#include "pretty.h"
+
+...
+
+struct commit *c = NULL;
+struct strbuf commitline;
+strbuf_init(&commitline, 0);

struct strbuf commitline = STRBUF_INIT

perhaps?

Documentation/MyFirstContribution line 316

Quoted 7 lines

Documentation/MyFirstContribution new file +7 -0

+
+...
+
+c = lookup_commit_reference_by_name("origin/master");
+
+if (c != NULL)
+{

'{' never comes on its own line unless it is for the outermost block of the function body.

Quoted 6 lines

Documentation/MyFirstContribution new file +6 -0

+     pp_commit_easy(CMIT_FMT_ONELINE, c, &commitline);
+     printf(_("Current commit: %s\n"), commitline.buf);
+}
+----
+
+The `struct strbuf` provides some safety belts to your basic `char*`, one of

Documentation/MyFirstContribution line 332

Quoted 10 lines

Documentation/MyFirstContribution new file +10 -0

+which is a length member to prevent buffer overruns. It needs to be initialized
+nicely with `strbuf_init`. Keep it in mind when you need to pass around `char*`.
+
+`lookup_commit_reference_by_name` resolves the name you pass it, so you can play
+with the value there and see what kind of things you can come up with.
+
+`pp_commit_easy` is a convenience wrapper in `pretty.h` that takes a single
+format enum shorthand, rather than an entire format struct. It then prints the
+commit according to that shorthand. These are similar to the formats available
+with `--pretty=FOO` in many Git commands.

At least the first mention of "print" that describes pp_* family of functions should use the word "pretty-print"; that would implicitly explain why the functions are called pp_*.

It then pretty-prints the commit ...

Documentation/MyFirstContribution line 398

Quoted 3 lines

Documentation/MyFirstContribution new file +3 -0

+The most important pieces of this to note are the file header, underlined by =,
+the NAME section, and the SYNOPSIS, which would normally contain the grammar if
+your command took arguments.  Feel free to add new headers if you wish.

What do you mean by the last sentence, especially by "new headers"?

We do not want develoeprs to feel free to add random new sections to the manpage, if that is what you mean. Rather we should encourage them to stick to the established structure, so that all manpages look the same and readers would know to which section to jump to to find necessary piece of information.

Quoted 4 lines

Documentation/MyFirstContribution new file +4 -0

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

Documentation/MyFirstContribution line 406

Quoted 4 lines

+----

Documentation/MyFirstContribution new file +3 -0

+make all doc
+man Documentation/git-psuh.1
+----

Hmph. I didn't know you can do that without "-l" (local) option. Perhaps with "-l" spelled out, it might be more portable but I dunno.

Documentation/MyFirstContribution line 430

Quoted 7 lines

Documentation/MyFirstContribution new file +6 -0

+Go ahead and commit your new documentation change.
 
+=== Adding usage text
+
+Try and run `./bin-wrappers/git psuh -h`. Your command should crash at the end.
+That's because `-h` is a special case which your command should handle by
+printing usage.

This is a tangent but an important one. I wonder we can turn the "crash" into a more graceful error exit? It is important because a fix like that will force us to update this sentence.

Documentation/MyFirstContribution line 437

Quoted 6 lines

Documentation/MyFirstContribution new file +6 -0

+Take a look at `Documentation/technical/api-parse-options.txt`. This is a handy
+tool for pulling out options you need to be able to handle, and it takes a
+usage string.
+
+In order to use it, we'll need to prepare a NULL-terminated usage string and a
+builtin_psuh_options array. Add a line to `#include "parse-options.h"`.

Consistently quote variables and functions like so. The array variable above, and also ...

Quoted 1 line

+Then, within your cmd_psuh implementation, we can declare and populate our

... cmd_psuh() here, too (I am also suggesting to add () as a sign that the identifier talks about a function).

Quoted 1 line

+option struct. Ours is pretty boring but you can add more to it if you like:

s/you can more to it if you like/we will add more in a later step/ perhaps? Or am I expecting too much? Use of parse_options() is an important skill required to write a modern Git subcommand.

Quoted 6 lines

+----

Documentation/MyFirstContribution new file +5 -0

+     struct option options[] = {
+             OPT_END()
+     };
+----
+

Documentation/MyFirstContribution

Quoted 10 lines

Documentation/MyFirstContribution new file +10 -0

+Finally, before you print your args and prefix, add the call to
+`parse-options()`:
+
+----
+     argc = parse_options(argc, argv, prefix, options, psuh_usage, 0);
+----
+
+This call will modify your `argv` and `options` parameters. It will strip
+options you specified in `options` from `argv` and populate them in `options`
+instead, if they were provided.

That is a misleading description.

I am sure that in the right mental model used by users of the parse_options API, argv[] gets modified, but options[] array is constant. It is just some entries in options[] have a pointer to locations they (i.e. the entries) request parse_options() call to update. The options[] array, e.g. the entries that record these variables to be updated, stay the same.

Documentation/MyFirstContribution line 477

Quoted 12 lines

Be sure to replace your argc with the result

Documentation/MyFirstContribution new file +11 -0

+from `parse_options`, or you will be confused if you try to parse argv later.
+
+It's worth noting the special argument `--`. As you may be aware, many Unix
+commands use `--` to indicate "end of named parameters" - all parameters after
+the `--` are interpreted merely as positional arguments. (This can be handy if
+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.
+
+Build again. Now, when you run with -h, you should see your usage printed and
+your command terminated before anything else interesting happens. Great!

If you had a separate section (because the first use in the tutorial of parse_options() that uses an empty options[] array is there only to use the psuh_usage usage string) that teaches the use of command line option, most of the above will move to that new section, and that may help making the result into easier-to-digest pieces. How about adding "--user=<name>" command line option, which would override the user.name config setting your command is already reading at this step in the sequence?

Documentation/MyFirstContribution line 485

Quoted 8 lines

Documentation/MyFirstContribution new file +8 -0

+
+Go ahead and commit this one, too.
+
+== Testing
+
+It's important to test your code - even for a little toy command like this one.
+Moreover, your patch won't be accepted into the Git tree without tests to
+demonstrate that it does what it's supposed to do. So let's add some tests.

Tests are *NOT* added to demonstrate that it does what it's supposed to do.

You add a test because you care about an externally visible behaviour you defined will *not* get broken by later changes (probably by others), by illustrating the behaviour of the feature and comparing it with what is expected.

Secondary reason to add a test is to demonstrate that a feature does *not* kick in when it is not supposed to, but "Git contribution 101" students are probably not ready for that one.

Quoted 33 lines

Documentation/MyFirstContribution new file +33 -0

+Related reading: `t/README`
+
+=== Overview of Testing Structure
+
+The tests in Git live in t/ and are named with a 4-decimal digit, according to
+the schema shown in the Naming Tests section of `t/README`.
+
+=== Writing Your Test
+
+Since this a toy command, let's go ahead and name the test with t9999. However,
+as many of the family/subcmd combinations are full, best practice seems to be
+to find a command close enough to the one you've added and share its naming
+space.
+
+Create your test script and mark it executable:
+
+----
+touch t/t9999-psuh-codelab.sh
+chmod +x t/t9999-psuh-codelab.sh
+----
+
+Begin with the header as so (see
+"Writing Tests" and "Source 'test-lib.sh'" in `t/README`):
+
+----
+#!/bin/sh
+
+test_description='git-psuh test
+
+This test runs git-psuh and makes sure it does not crash.'
+
+. ./test-lib.sh
+----

Documentation/MyFirstContribution line 522

Quoted 3 lines

Documentation/MyFirstContribution new file +3 -0

+
+Tests are framed inside of a `test_expect_success` in order to output TAP
+formatted results. Begin your first test and set up the repo to test in:

Hmmm, I doubt the wisdom in that. Almost all our tests can work in the default test repository. Why should we show the exception to those who are beginning their first step with "hello world", risking the use of "rm -rf"?

Documentation/MyFirstContribution line 652

Quoted 7 lines

+=== Sending a PR to GitGitGadget

Documentation/MyFirstContribution new file +5 -0

+
+GitGitGadget is a tool created by Johannes Schindelin to make life as a Git
+contributor easier for those used to the GitHub PR workflow. It allows
+contributors to open pull requests against its mirror of the Git project, and
+does some magic to turn the PR into a set of emails and sent them out for you.

s/sent them/send them/

Documentation/MyFirstContribution line 709

Quoted 6 lines

+== Sending Patches with git send-email

Documentation/MyFirstContribution new file +4 -0

+
+There are a couple reasons you may not want to use GitGitGadget, such as needing
+to send an RFC patch, wanting to check your work before mailing, or not having a
+GitHub account. Luckily, you can use Git to mail your patches instead!

Hmph, just for my education, is there anything in GGG that makes it unsuitable for an RFC/WIP? It also is not clear to me what it does have to do with the ability to "check your work before mailing"; the proposed log message and the patch text can be polished even before you push to your GitHub repository, so ...

Documentation/MyFirstContribution line 737

Quoted 12 lines

+=== Preparing initial patchset

Documentation/MyFirstContribution new file +11 -0

+
+Sending emails with Git is a two-part process; before you can prepare the emails
+themselves, you'll need to prepare the patches. Luckily, this is pretty simple:
+
+----
+git format-patch -o psuh/ master..psuh
+----
+
+The `-o psuh/` parameter tells `format-patch` to place the patch files into a
+directory. This is useful because `git send-email` can take a directory and
+send out all the patches from there.

I'd rather not recommend the "send the whole directory contents" feature. Instead, it is preferrable to do

git send-email psuh/0*.patch
git send-email psuh/v2-*.patch

etc., using the same psuh/ directory as the output redirectory throughout the iterations. That practice would primarily help you write the cover letters for later iterations while peeking at the ones you wrote for earlier iterations.

Documentation/MyFirstContribution line 748

Quoted 11 lines

+master..psuh tells format-patch to generate patches for the difference

Documentation/MyFirstContribution new file +9 -0

+between `master` and `psuh`. It will make one patch file per commit. After you
+run, you can go have a look at each of the patches with your favorite text
+editor and make sure everything looks alright; however, it's not recommended to
+make code fixups via the patch file. It's a better idea to make the change the
+normal way using `git rebase -i` or by adding a new commit than by modifying a
+patch.
+
+Check and make sure that your patches exist in the directory you specified -
+you're nearly ready to send out your review!

OK. I'll suggest using --cover-letter at this step, though.

Documentation/MyFirstContribution line 755

Quoted 7 lines

+=== Preparing email

Documentation/MyFirstContribution new file +5 -0

+
+In addition to an email per patch, the Git community also expects your patches
+to come with a cover letter, typically with a subject line [PATCH 0/x] (where
+x is the number of patches you're sending).  You'll need to add some extra
+parameters when you invoke `git send-email` to add the cover letter.

I am going to suggest getting rid of mention of the cover letter out of this section, and move it to the previous section. Regardless of where the cover-letter is covered, I think we would want to say that a single-patch topic typically do not need a cover.

Documentation/MyFirstContribution line 764

Quoted 9 lines

+----

Documentation/MyFirstContribution new file +7 -0

+git send-email \
+     [email protected] \
+     [email protected] \
+     --subject="[PATCH 0/7] adding the 'psuh' command" \
+     --compose \
+     psuh/
+----

About this "--compose" thing later. In short, I'd rather see the contributor prepare the cover next to the patch files when they run format-patch.

Documentation/MyFirstContribution line 786

Quoted 8 lines

Documentation/MyFirstContribution new file +8 -0

+
+The `--to` and `--from` fields are pretty obvious. `--subject` should indicate
+that it's a cover letter with the [PATCH 0/x] tag (check how many patches you
+are about to send so you can indicate the size of the thread correctly).
+`--compose` indicates that you want to open an editor to write the cover letter
+ ...
+The argument to `--stat` bounds the column width of the output, which is handy
+as emails to Git shouldn't exceed 72 columns of width.

Most of the above will become unnecessary if you tell format-patch to give you the cover template, I think.

Quoted 23 lines

Documentation/MyFirstContribution new file +23 -0

+Here's an example of a cover letter for `git psuh`:
+
+----
+Our internal metrics indicate widespread interest in the command
+git-psuh - that is, many users are trying to use it, but finding it is
+unavailable, using some unknown workaround instead.
+
+The following handful of patches add the psuh command and implement some
+handy features on top of it.
+
+This patchset is part of the MyFirstContribution codelab and should not
+be merged.
+
+ Documentation/git-psuh.txt | 40 +++++++++++++++++++
+ Makefile                   |  1 +
+ builtin.h                  |  1 +
+ builtin/psuh.c             | 78 ++++++++++++++++++++++++++++++++++++++
+ git.c                      |  1 +
+ t/t9999-psuh-codelab.sh    | 12 ++++++
+ 6 files changed, 133 insertions(+)
+----
+
+NOTE: When you've got a real change to send, you'll use `[email protected]`

Documentation/MyFirstContribution line 820

Quoted 10 lines

Documentation/MyFirstContribution new file +10 -0

+in the `--to` field. For now, though, don't spam the list with the codelab -
+send it to yourself and check if it looks right.
+
+=== Sending email
+
+After you finish running the command above and editing your cover letter, you
+will be presented with an interactive prompt for each patch that's about to go
+out. This gives you one last chance to edit or quit sending something (but
+again, don't edit code this way). Once you press `y` or `a` at these prompts
+your emails will go out!

I have a moderate aversion against the workflow to use the editor inside "git send-email" invocation. The prompting that urges "now do this next" tends to make haste that is wastful.

Your example at least prepares the patches in a separate step, so it is a bit better than running format-patch from within the send-email command, which is a small consolation but still...

I'd rather see people trained to use "format-patch -o <topic>" to save the patch files and the cover letter template in a directory [*1*], which will give them a chance to write the cover letter in a separate editor session, and send the result out with a separate "git send-email <topic>/*.patch" or "git send-email <topic>/v2-*.patch" invocations, *AFTER* they have a chance to sleep on it.

Side note. *1* ... and keep it throughout iterations, so "format-patch -v2 -o" will name the same output directory, which will let you reuse material in the cover letter for earlier iterations when you write the cover letter for the latest iteration).

Documentation/MyFirstContribution line 825

Quoted 5 lines

Documentation/MyFirstContribution new file +5 -0

+
+Awesome, now the community will drop everything and review your changes. (Just
+kidding - be patient!)
+
+=== Applying Changes

I am wondering if we want to retitle this to "responding to reviews".

Documentation/MyFirstContribution line 828

Quoted 2 lines

Documentation/MyFirstContribution new file +2 -0

+Once you do have some review comments, you should make changes if necessary, or
+push back on the changes by replying to the emails. (Make sure your mail client

Responding that you understood what was suggested and explaining the reason why you do not take the suggestion (either you think your original is better for reason X, or you thought of a solution even better than your original or what was suggested) is of course good. But I often see people who do not respond when taking what was suggested and jump directly to sending the new iteration, which I think should be strongly discouraged.

It is a better idea to respond to review comments whether you would take or reject the suggested changes. Reviewers are busy, and when you silently take the suggestions and send v2 without responding to reviews on your v1, those who gave you valuable input are forced to read your v2 to see what you did to their suggestions.

Documentation/MyFirstContribution line 837

Quoted 9 lines

Documentation/MyFirstContribution new file +9 -0

+has a plaintext email mode; the Git list rejects HTML email.) Please also follow
+the mailing list etiquette outlined in the
+https://kernel.googlesource.com/pub/scm/git/git/+/todo/MaintNotes[Maintainer's
+Note], which are similar to etiquette rules in most open source communities
+surrounding bottom-posting and inline replies.
+
+////
+TODO - mail list etiquette
+////

Quoted 5 lines

Documentation/MyFirstContribution new file +5 -0

+
+You should apply changes using interactive rebase, or by adding new commits if
+the changes seem to require it.
+
+NOTE: Interactive rebase can be tricky; check out this handy

Documentation/MyFirstContribution line 852

Quoted 10 lines

Documentation/MyFirstContribution new file +10 -0

+https://www.oreilly.com/library/view/git-pocket-guide/9781449327507/ch10.html
+[overview] from O'Reilly.
+
+=== Sending v2
+
+When you're ready with the next iteration of your patch, the process is pretty
+much the same, with a few differences:
+
+* When you run `format-patch`, include the argument `-v2` to add a "v2" tag to
+the subject lins given.

I think "lins" is a typo for "line", but I am not sure what "the subject line given" wants to say.

... include the argument -v2. This marks the patches as the second iteration by prefixing their subject with "[PATCH v2]" instead of "[PATCH]".

perhaps? I dunno.

Documentation/MyFirstContribution line 860

Quoted 9 lines

Documentation/MyFirstContribution new file +8 -0

+* When you run `send-email`, include the argument `--in-reply-to=<message-id>`
+with the Message-Id of the cover letter of the previous version. (You can find
+that Message-Id on https://public-inbox.org/git/.) Also, change the subject line
+on your cover letter to include "v2" to match the subjects of your patches.
+
+When it's time for v3 or beyond, simply change the number above, but make sure
+your v2 cover letter is in reply to your v1 cover letter, and your v3 cover
+letter is in reply to your v2 cover letter, and so on.

A single-patch topic typically should not have a cover. Saying "the first message of the previous round" instead of "the cover letter of the previous version" would cover the case as well as a multi-patch series with a cover letter.

Quoted 12 lines

+== Now What?

Documentation/MyFirstContribution new file +10 -0

+
+The Git project has four integration branches: `pu`, `next`, `master`, and
+`maint`. Your change will be placed into `pu` fairly early on by the maintainer
+while it is still in the review process; from there, when it is ready for wider
+testing, it will be merged into `next`. Plenty of early testers use `next` and
+may report issues. Eventually, changes in `next` will make it to `master`,
+which is typically considered stable. Finally, when a new release is cut,
+`maint` is used to base bugfixes onto. As mentioned at the beginning of this
+document, you can read `Documents/SubmittingPatches` for some more info about
+the use of the various integration branches.

Documentation/MyFirstContribution line 876

Quoted 4 lines

Documentation/MyFirstContribution new file +4 -0

+
+Back to now: your code has been lauded by the upstream reviewers. It is perfect.
+It is ready to be accepted. You don't need to do anything else; the maintainer
+will pull your patchset into `next` and life is good.

"pull" may not be a good verb to use in this project. I would have written "the maintainer will merge your topic branch to 'next'" if I were doing this tutorial.

Review

Quoted 3 lines

(quoted diff) +2 -0

+However, if it isn't so perfect, once it is in `next`, you can no longer modify
+your commits in GitGitGadget or the email thread. Consider that review "closed

If it isn't so perfect, the first thing the contributor can do that I as the maintainer woudl appreciate is to say "I've sent v4 of my series and you marked it for 'next', but I'd still want to fix up this and that in it; wait for v5 before merging" before it hits 'next'.

Of course, no single contributor or reviewers (myself included) is perfect, so it often happens that further issues are noticed only after a topic hits 'next'. But it's not like the merge to 'next' is point of no return---polishing can and do continue, but this time it is done incrementally.

I'd replace "can no longer modify..." with something like "would switch to updating the topic incrementally, instead of redoing the topic wholesale". You are still moving forward, helping to perfect the same topic, as opposed to be working on a separate topic that depends on it.

Thanks.

RFC. I am still working on adding a section on handling refs and objects.

This tutorial covers how to add a new command to Git and, in the process, everything from cloning git/git to getting reviewed on the mailing list. It's meant for new contributors to go through interactively, learning the techniques generally used by the git/git development community.

Signed-off-by Emily Shaffer <[email protected]>

---

+- `Documentation/SubmittingPatches`
+- `Documentation/howto/new-command.txt`

+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

+----

Documentation/MyFirstContribution.txt new file +13 -0

+
+`git_config()` will grab the configuration from config files known to Git and
+apply standard precedence rules. `git_config_get_string_const()` will look up
+a specific key ("user.name") and give you the value. There are a number of
+single-key lookup functions like this one; you can see them all (and more info
+about how to use `git_config()`) in `Documentation/technical/api-config.txt`.
+
+You should see that the name printed matches the one you see when you run:
+
+----
+$ git config --get user.name
+----
+

Documentation/MyFirstContribution.txt new file +7 -0

+below as well; make sure to replace it with the correct Message-Id for your
+**previous cover letter** - that is, if you're sending v2, use the Message-Id
+from v1; if you're sending v3, use the Message-Id from v2.
+
+Now send the emails again, paying close attention to which messages you pass in
+to the command:
+

+--- in your patch. Take the example below, generated with git format-patch +on a single commit:

Quoted 6 lines · Emily Shaffer

This tutorial covers how to add a new command to Git and, in the process, everything from cloning git/git to getting reviewed on the mailing list. It's meant for new contributors to go through interactively, learning the techniques generally used by the git/git development community.

Quoted 2 lines

Signed-off-by Emily Shaffer <[email protected]>

---

I think a stray "lab" remains in the title of the patch. They seem to have disappeared from all the other places, and "tutorial" is consistently used, which is good.

My eyes have lost freshness on this topic, so my review tonight is bound to be (much) less thorough than the previous round.

Quoted 3 lines

+- `Documentation/SubmittingPatches`
+- `Documentation/howto/new-command.txt`

Good (relative to the earlier one, these are set in monospace).

Documentation/MyFirstContribution.txt line 26

Quoted 6 lines

Documentation/MyFirstContribution.txt new file +6 -0

+
+== Getting Started
+
+=== Pull the Git codebase
+
+Git is mirrored in a number of locations. https://git-scm.com/downloads

Perhaps URLs should also be set in monospace?

Quoted 4 lines

+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

I do not think you want to set 'flag' in monospace, too. i.e. s| flag| flag|;

Documentation/MyFirstContribution.txt line 242

Quoted 9 lines

Documentation/MyFirstContribution.txt new file +9 -0

+     git_config(git_default_config, NULL)
+     if (git_config_get_string_const("user.name", &cfg_name) > 0)
+     {
+             printf(_("No name is found in config\n"));
+     }
+     else
+     {
+             printf(_("Your name: %s\n"), cfg_name);
+     }

Style. Opening braces "{" for control structures are never be on its own line, and else comes on the same line as closing "}" of if, i.e.

        if (...) {
                print ...
        } else {
                print ...
        }

Or just get rid of braces if you are not going to extend one (or both) of if/else blocks into multi-statement blocks.

Quoted 14 lines

+----

Documentation/MyFirstContribution.txt new file +13 -0

+
+`git_config()` will grab the configuration from config files known to Git and
+apply standard precedence rules. `git_config_get_string_const()` will look up
+a specific key ("user.name") and give you the value. There are a number of
+single-key lookup functions like this one; you can see them all (and more info
+about how to use `git_config()`) in `Documentation/technical/api-config.txt`.
+
+You should see that the name printed matches the one you see when you run:
+
+----
+$ git config --get user.name
+----
+

Documentation/MyFirstContribution.txt line 266

Quoted 10 lines

Documentation/MyFirstContribution.txt new file +10 -0

+Great! Now we know how to check for values in the Git config. Let's commit this
+too, so we don't lose our progress.
+
+----
+$ git add builtin/psuh.c
+$ git commit -sm "psuh: show parameters & config opts"
+----
+
+NOTE: Again, the above is for sake of brevity in this tutorial. In a real change
+you should not use `-m` but instead use the editor to write a verbose message.

We never encourge people to write irrelevant things or obvious things that do not have to be said. But a single-liner message rarely is sufficient to convey "what motivated the change, and why the change is done in the way seen in the patch" in a meaningful way.

i.e. s|verbose|meaningful|;

Documentation/MyFirstContribution.txt line 537

Quoted 7 lines

Documentation/MyFirstContribution.txt new file +6 -0

+Create your test script and mark it executable:
+
+----
+$ touch t/t9999-psuh-tutorial.sh
+$ chmod +x t/t9999-psuh-tutorial.sh
+----

I never "create an empty file" before editing in real life. Is this a common workflow in some circles?

I'd be tempted to suggest s/touch/edit/ here, but I dunno.

Documentation/MyFirstContribution.txt line 926

Quoted 5 lines

Documentation/MyFirstContribution.txt new file +4 -0

+https://public-inbox.org/git/[email protected]/other/junk
+----
+
+Your Message-Id is `[email protected]`. This example will be used

Technically, <[email protected]> with angle bracket is the message Id, but the tool is lenient to allow this common mistake ;-) so this one, and the "send-email --in-reply-to=" example below can stay as-is.

Documentation/MyFirstContribution.txt line 937

Quoted 12 lines

Documentation/MyFirstContribution.txt new file +11 -0

+below as well; make sure to replace it with the correct Message-Id for your
+**previous cover letter** - that is, if you're sending v2, use the Message-Id
+from v1; if you're sending v3, use the Message-Id from v2.
+
+Now send the emails again, paying close attention to which messages you pass in
+to the command:
+
+----
+$ git send-email [email protected]
+              [email protected]
+----

Documentation/MyFirstContribution.txt line 943

Quoted 6 lines

Documentation/MyFirstContribution.txt new file +6 -0

+
+=== Bonus Chapter: One-Patch Changes
+
+In some cases, your very small change may consist of only one patch. When that
+happens, you only need to send one email. Your commit message should already be
+verbose, but if you need to supply even more context, you can do so below the

s|be verbose|explain what and why of the change well| or something like that?

Quoted 2 lines

+--- in your patch. Take the example below, generated with git format-patch +on a single commit:

+=== Implementation

Documentation/MyFirstContribution.txt new file +16 -0

+
+It's probably useful to do at least something besides printing out a string.
+Let's start by having a look at everything we get.
+
+Modify your `cmd_psuh` implementation to dump the args you're passed:
+
+----
+	int i;
+
+	...
+
+	printf(Q_("Your args (there is %d):\n",
+		  "Your args (there are %d):\n",
+		  argc),
+	       argc);
+	for (i = 0; i < argc; i++) {

+=== Adding documentation

Documentation/MyFirstContribution.txt new file +62 -0

+
+Awesome! You've got a fantastic new command that you're ready to share with the
+community. But hang on just a minute - this isn't very user-friendly. Run the
+following:
+
+----
+$ ./bin-wrappers/git help psuh
+----
+
+Your new command is undocumented! Let's fix that.
+
+Take a look at `Documentation/git-*.txt`. These are the manpages for the
+subcommands that Git knows about. You can open these up and take a look to get
+acquainted with the format, but then go ahead and make a new file
+`Documentation/git-psuh.txt`. Like with most of the documentation in the Git
+project, help pages are written with AsciiDoc (see CodingGuidelines, "Writing
+Documentation" section). Use the following template to fill out your own
+manpage:
+
+// Surprisingly difficult to embed AsciiDoc source within AsciiDoc.
+[listing]
+....
+git-psuh(1)
+===========
+
+NAME
+----
+git-psuh - Delight users' typo with a shy horse
+
+
+SYNOPSIS
+--------
+[verse]
+'git-psuh'
+
+DESCRIPTION
+-----------
+...
+
+OPTIONS[[OPTIONS]]
+------------------
+...
+
+OUTPUT
+------
+...
+
+
+GIT
+---
+Part of the linkgit:git[1] suite
+....
+
+The most important pieces of this to note are the file header, underlined by =,
+the NAME section, and the SYNOPSIS, which would normally contain the grammar if
+your command took arguments. Try to use well-established manpage headers so your
+documentation is consistent with other Git and UNIX manpages; this makes life
+easier for your user, who can skip to the section they know contains the
+information they need.
+
+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:

Just a couple typo fixes listed below:

[snip]

Quoted 21 lines

+=== Implementation

Documentation/MyFirstContribution.txt new file +20 -0

+
+It's probably useful to do at least something besides printing out a string.
+Let's start by having a look at everything we get.
+
+Modify your `cmd_psuh` implementation to dump the args you're passed:
+
+----
+	int i;
+
+	...
+
+	printf(Q_("Your args (there is %d):\n",
+		  "Your args (there are %d):\n",
+		  argc),
+	       argc);
+	for (i = 0; i < argc; i++) {
+		printf("%d: %s\n", i, argv[i]);
+	}
+	printf(_("Your current working directory:\n<top-level>%s%s\n"),
+	       prefix ? "/" : "", prefix ? prefix : "");

Documentation/MyFirstContribution.txt line 223

Quoted 6 lines

Documentation/MyFirstContribution.txt new file +6 -0

+
+----
+
+Build and try it. As you may expect, there's pretty much just whatever we give
+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

Looks like you have an errant "/" after "git".

[snip]

Quoted 67 lines

+=== Adding documentation

Documentation/MyFirstContribution.txt new file +66 -0

+
+Awesome! You've got a fantastic new command that you're ready to share with the
+community. But hang on just a minute - this isn't very user-friendly. Run the
+following:
+
+----
+$ ./bin-wrappers/git help psuh
+----
+
+Your new command is undocumented! Let's fix that.
+
+Take a look at `Documentation/git-*.txt`. These are the manpages for the
+subcommands that Git knows about. You can open these up and take a look to get
+acquainted with the format, but then go ahead and make a new file
+`Documentation/git-psuh.txt`. Like with most of the documentation in the Git
+project, help pages are written with AsciiDoc (see CodingGuidelines, "Writing
+Documentation" section). Use the following template to fill out your own
+manpage:
+
+// Surprisingly difficult to embed AsciiDoc source within AsciiDoc.
+[listing]
+....
+git-psuh(1)
+===========
+
+NAME
+----
+git-psuh - Delight users' typo with a shy horse
+
+
+SYNOPSIS
+--------
+[verse]
+'git-psuh'
+
+DESCRIPTION
+-----------
+...
+
+OPTIONS[[OPTIONS]]
+------------------
+...
+
+OUTPUT
+------
+...
+
+
+GIT
+---
+Part of the linkgit:git[1] suite
+....
+
+The most important pieces of this to note are the file header, underlined by =,
+the NAME section, and the SYNOPSIS, which would normally contain the grammar if
+your command took arguments. Try to use well-established manpage headers so your
+documentation is consistent with other Git and UNIX manpages; this makes life
+easier for your user, who can skip to the section they know contains the
+information they need.
+
+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:
+
+----
+$ make all doc
+$ man Documentation/git-psuh.1

Documentation/MyFirstContribution.txt line 433

Quoted 6 lines

+----

Documentation/MyFirstContribution.txt new file +5 -0

+
+or
+
+----
+$ make -C Documentation/git-psuh.1

Needs a space after "Documentation/".

This tutorial covers how to add a new command to Git and, in the process, everything from cloning git/git to getting reviewed on the mailing list. It's meant for new contributors to go through interactively, learning the techniques generally used by the git/git development community.

Signed-off-by Emily Shaffer <[email protected]>

---
Only minor changes from v3, correcting the comments Junio made in his review.

- Changed commit subject
- Stray monospace typos
- Curly brace style

 Documentation/Makefile                |    1 +
 Documentation/MyFirstContribution.txt | 1073 +++++++++++++++++++++++++
 2 files changed, 1074 insertions(+)
 create mode 100644 Documentation/MyFirstContribution.txt

Documentation/Makefile +1 -0

index 26a2342bea..fddc3c3c95 100644
@@ -74,6 +74,7 @@ API_DOCS = $(patsubst %.txt,%,$(filter-out technical/api-index-skel.txt technica
 SP_ARTICLES += $(API_DOCS)
 
 TECH_DOCS += SubmittingPatches
+TECH_DOCS += MyFirstContribution
 TECH_DOCS += technical/hash-function-transition
 TECH_DOCS += technical/http-protocol
 TECH_DOCS += technical/index-format

Documentation/MyFirstContribution.txt new file +153 -0

new file mode 100644
index 0000000000..fc4a59a8c6
@@ -0,0 +1,1073 @@
+My First Contribution to the Git Project
+========================================
+
+== Summary
+
+This is a tutorial demonstrating the end-to-end workflow of creating a change to
+the Git tree, sending it for review, and making changes based on comments.
+
+=== Prerequisites
+
+This tutorial assumes you're already fairly familiar with using Git to manage
+source code.  The Git workflow steps will largely remain unexplained.
+
+=== Related Reading
+
+This tutorial aims to summarize the following documents, but the reader may find
+useful additional context:
+
+- `Documentation/SubmittingPatches`
+- `Documentation/howto/new-command.txt`
+
+== Getting Started
+
+=== Pull the Git codebase
+
+Git is mirrored in a number of locations. https://git-scm.com/downloads
+suggests one of the best places to clone from is GitHub.
+
+----
+$ git clone https://github.com/git/git git
+----
+
+=== Identify Problem to Solve
+
+////
+Use + to indicate fixed-width here; couldn't get ` to work nicely with the
+quotes around "Pony Saying 'Um, Hello'".
+////
+In this tutorial, we will add a new command, +git psuh+, short for ``Pony Saying
+`Um, Hello''' - a feature which has gone unimplemented despite a high frequency
+of invocation during users' typical daily workflow.
+
+(We've seen some other effort in this space with the implementation of popular
+commands such as `sl`.)
+
+=== Set Up Your Workspace
+
+Let's start by making a development branch to work on our changes. Per
+`Documentation/SubmittingPatches`, since a brand new command is a new feature,
+it's fine to base your work on `master`. However, in the future for bugfixes,
+etc., you should check that document and base it on the appropriate branch.
+
+For the purposes of this document, we will base all our work on the `master`
+branch of the upstream project. Create the `psuh` branch you will use for
+development like so:
+
+----
+$ git checkout -b psuh origin/master
+----
+
+We'll make a number of commits here in order to demonstrate how to send a topic
+with multiple patches up for review simultaneously.
+
+== Code It Up!
+
+NOTE: A reference implementation can be found at
+https://github.com/nasamuffin/git/tree/psuh.
+
+=== Adding a new command
+
+Lots of the subcommands are written as builtins, which means they are
+implemented in C and compiled into the main `git` executable. Implementing the
+very simple `psuh` command as a built-in will demonstrate the structure of the
+codebase, the internal API, and the process of working together as a contributor
+with the reviewers and maintainer to integrate this change into the system.
+
+Built-in subcommands are typically implemented in a function named "cmd_"
+followed by the name of the subcommand, in a source file named after the
+subcommand and contained within `builtin/`. So it makes sense to implement your
+command in `builtin/psuh.c`. Create that file, and within it, write the entry
+point for your command in a function matching the style and signature:
+
+----
+int cmd_psuh(int argc, const char **argv, const char *prefix)
+----
+
+We'll also need to add the extern declaration of psuh; open up `builtin.h`,
+find the declaration for `cmd_push`, and add a new line for `psuh` immediately
+before it, in order to keep the declarations sorted:
+
+----
+extern int cmd_psuh(int argc, const char **argv, const char *prefix);
+----
+
+Be sure to `#include "builtin.h"` in your `psuh.c`.
+
+Go ahead and add some throwaway printf to that function. This is a decent
+starting point as we can now add build rules and register the command.
+
+NOTE: Your throwaway text, as well as much of the text you will be adding over
+the course of this tutorial, is user-facing. That means it needs to be
+localizable. Take a look at `po/README` under "Marking strings for translation".
+Throughout the tutorial, we will mark strings for translation as necessary; you
+should also do so when writing your user-facing commands in the future.
+
+----
+int cmd_psuh(int argc, const char **argv, const char *prefix)
+{
+       printf(_("Pony saying hello goes here.\n"));
+       return 0;
+}
+----
+
+Let's try to build it.  Open `Makefile`, find where `builtin/push.o` is added
+to `BUILTIN_OBJS`, and add `builtin/psuh.o` in the same way next to it in
+alphabetical order. Once you've done so, move to the top-level directory and
+build simply with `make`. Also add the `DEVELOPER=1` variable to turn on
+some additional warnings:
+
+----
+$ echo DEVELOPER=1 >config.mak
+$ make
+----
+
+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.
+
+The list of commands lives in `git.c`. We can register a new command by adding
+a `cmd_struct` to the `commands[]` array. `struct cmd_struct` takes a string
+with the command name, a function pointer to the command implementation, and a
+setup option flag. For now, let's keep cheating off of `push`. Find the line
+where `cmd_push` is registered, copy it, and modify it for `cmd_psuh`, placing
+the new line in alphabetical order.
+
+The options are documented in `builtin.h` under "Adding a new built-in." Since
+we hope to print some data about the user's current workspace context later,
+we need a Git directory, so choose `RUN_SETUP` as your only option.
+
+Go ahead and build again. You should see a clean build, so let's kick the tires
+and see if it works. There's a binary you can use to test with in the
+`bin-wrappers` directory.
+
+----
+$ ./bin-wrappers/git psuh
+----
+

Documentation/MyFirstContribution.txt new file +260 -0

+your change, especially if it couldn't easily be understood from your diff. When
+editing your commit message, don't remove the Signed-off-by line which was added
+by `-s` above.
+
+----
+psuh: add a built-in by popular demand
+
+Internal metrics indicate this is a command many users expect to be
+present. So here's an implementation to help drive customer
+satisfaction and engagement: a pony which doubtfully greets the user,
+or, a Pony Saying "Um, Hello" (PSUH).
+
+This commit message is intentionally formatted to 72 columns per line,
+starts with a single line as "commit message subject" that is written as
+if to command the codebase to do something (add this, teach a command
+that). The body of the message is designed to add information about the
+commit that is not readily deduced from reading the associated diff,
+such as answering the question "why?".
+
+Signed-off-by: A U Thor <[email protected]>
+----
+
+Go ahead and inspect your new commit with `git show`. "psuh:" indicates you
+have modified mainly the `psuh` command. The subject line gives readers an idea
+of what you've changed. The sign-off line (`-s`) indicates that you agree to
+the Developer's Certificate of Origin 1.1 (see the
+`Documentation/SubmittingPatches` +++[[dco]]+++ header). If you wish to add some
+context to your change, go ahead with `git commit --amend`.
+
+For the remainder of the tutorial, the subject line only will be listed for the
+sake of brevity. However, fully-fleshed example commit messages are available
+on the reference implementation linked at the top of this document.
+
+=== Implementation
+
+It's probably useful to do at least something besides printing out a string.
+Let's start by having a look at everything we get.
+
+Modify your `cmd_psuh` implementation to dump the args you're passed:
+
+----
+       int i;
+
+       ...
+
+       printf(Q_("Your args (there is %d):\n",
+                 "Your args (there are %d):\n",
+                 argc),
+              argc);
+       for (i = 0; i < argc; i++) {
+               printf("%d: %s\n", i, argv[i]);
+       }
+       printf(_("Your current working directory:\n<top-level>%s%s\n"),
+              prefix ? "/" : "", prefix ? prefix : "");
+
+----
+
+Build and try it. As you may expect, there's pretty much just whatever we give
+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"`. Then, add the following bits to the
+function body:
+
+----
+       const char *cfg_name;
+
+...
+
+       git_config(git_default_config, NULL)
+       if (git_config_get_string_const("user.name", &cfg_name) > 0) {
+               printf(_("No name is found in config\n"));
+       } else {
+               printf(_("Your name: %s\n"), cfg_name);
+       }
+----
+
+`git_config()` will grab the configuration from config files known to Git and
+apply standard precedence rules. `git_config_get_string_const()` will look up
+a specific key ("user.name") and give you the value. There are a number of
+single-key lookup functions like this one; you can see them all (and more info
+about how to use `git_config()`) in `Documentation/technical/api-config.txt`.
+
+You should see that the name printed matches the one you see when you run:
+
+----
+$ git config --get user.name
+----
+
+Great! Now we know how to check for values in the Git config. Let's commit this
+too, so we don't lose our progress.
+
+----
+$ git add builtin/psuh.c
+$ git commit -sm "psuh: show parameters & config opts"
+----
+
+NOTE: Again, the above is for sake of brevity in this tutorial. In a real change
+you should not use `-m` but instead use the editor to write a meaningful
+message.
+
+Still, it'd be nice to know what the user's working context is like. Let's see
+if we can print the name of the user's current branch. We can cheat off of the
+`git status` implementation; the printer is located in `wt-status.c` and we can
+see that the branch is held in a `struct wt_status`.
+
+`wt_status_print()` gets invoked by `cmd_status()` in `builtin/commit.c`.
+Looking at that implementation we see the status config being populated like so:
+
+----
+status_init_config(&s, git_status_config);
+----
+
+But as we drill down, we can find that `status_init_config()` wraps a call
+to `git_config()`. Let's modify the code we wrote in the previous commit.
+
+Be sure to include the header to allow you to use `struct wt_status`:
+----
+#include "wt-status.h"
+----
+
+Then modify your `cmd_psuh` implementation to declare your `struct wt_status`,
+prepare it, and print its contents:
+
+----
+       struct wt_status status;
+
+...
+
+       wt_status_prepare(the_repository, &status);
+       git_config(git_default_config, &status);
+
+...
+
+       printf(_("Your current branch: %s\n"), status.branch);
+----
+
+Run it again. Check it out - here's the (verbose) name of your current branch!
+
+Let's commit this as well.
+
+----
+$ git commit -sm "psuh: print the current branch"
+----
+
+Now let's see if we can get some info about a specific commit.
+
+Luckily, there are some helpers for us here. `commit.h` has a function called
+`lookup_commit_reference_by_name` to which we can simply provide a hardcoded
+string; `pretty.h` has an extremely handy `pp_commit_easy()` call which doesn't
+require a full format object to be passed.
+
+Add the following includes:
+
+----
+#include "commit.h"
+#include "pretty.h"
+----
+
+Then, add the following lines within your implementation of `cmd_psuh()` near
+the declarations and the logic, respectively.
+
+----
+       struct commit *c = NULL;
+       struct strbuf commitline = STRBUF_INIT;
+
+...
+
+       c = lookup_commit_reference_by_name("origin/master");
+
+       if (c != NULL) {
+               pp_commit_easy(CMIT_FMT_ONELINE, c, &commitline);
+               printf(_("Current commit: %s\n"), commitline.buf);
+       }
+----
+
+The `struct strbuf` provides some safety belts to your basic `char*`, one of
+which is a length member to prevent buffer overruns. It needs to be initialized
+nicely with `STRBUF_INIT`. Keep it in mind when you need to pass around `char*`.
+
+`lookup_commit_reference_by_name` resolves the name you pass it, so you can play
+with the value there and see what kind of things you can come up with.
+
+`pp_commit_easy` is a convenience wrapper in `pretty.h` that takes a single
+format enum shorthand, rather than an entire format struct. It then
+pretty-prints the commit according to that shorthand. These are similar to the
+formats available with `--pretty=FOO` in many Git commands.
+
+Build it and run, and if you're using the same name in the example, you should
+see the subject line of the most recent commit in `origin/master` that you know
+about. Neat! Let's commit that as well.
+
+----
+$ git commit -sm "psuh: display the top of origin/master"
+----
+
+=== Adding documentation
+
+Awesome! You've got a fantastic new command that you're ready to share with the
+community. But hang on just a minute - this isn't very user-friendly. Run the
+following:
+
+----
+$ ./bin-wrappers/git help psuh
+----
+
+Your new command is undocumented! Let's fix that.
+
+Take a look at `Documentation/git-*.txt`. These are the manpages for the
+subcommands that Git knows about. You can open these up and take a look to get
+acquainted with the format, but then go ahead and make a new file
+`Documentation/git-psuh.txt`. Like with most of the documentation in the Git
+project, help pages are written with AsciiDoc (see CodingGuidelines, "Writing
+Documentation" section). Use the following template to fill out your own
+manpage:
+
+// Surprisingly difficult to embed AsciiDoc source within AsciiDoc.
+[listing]
+....
+git-psuh(1)
+===========
+
+NAME
+----
+git-psuh - Delight users' typo with a shy horse
+
+
+SYNOPSIS
+--------
+[verse]
+'git-psuh'
+
+DESCRIPTION
+-----------
+...
+
+OPTIONS[[OPTIONS]]
+------------------
+...
+
+OUTPUT
+------
+...
+
+
+GIT
+---
+Part of the linkgit:git[1] suite
+....
+
+The most important pieces of this to note are the file header, underlined by =,
+the NAME section, and the SYNOPSIS, which would normally contain the grammar if
+your command took arguments. Try to use well-established manpage headers so your
+documentation is consistent with other Git and UNIX manpages; this makes life
+easier for your user, who can skip to the section they know contains the
+information they need.
+
+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:

Documentation/MyFirstContribution.txt new file +77 -0

+$ man Documentation/git-psuh.1
+----
+
+NOTE: You may need to install the package `asciidoc` to get this to work.
+
+While this isn't as satisfying as running through `git help`, you can at least
+check that your help page looks right.
+
+You can also check that the documentation coverage is good (that is, the project
+sees that your command has been implemented as well as documented) by running
+`make check-docs` from the top-level.
+
+Go ahead and commit your new documentation change.
+
+=== Adding usage text
+
+Try and run `./bin-wrappers/git psuh -h`. Your command should crash at the end.
+That's because `-h` is a special case which your command should handle by
+printing usage.
+
+Take a look at `Documentation/technical/api-parse-options.txt`. This is a handy
+tool for pulling out options you need to be able to handle, and it takes a
+usage string.
+
+In order to use it, we'll need to prepare a NULL-terminated usage string and a
+`builtin_psuh_options` array. Add a line to `#include "parse-options.h"`.
+
+At global scope, add your usage:
+
+----
+static const char * const psuh_usage[] = {
+       N_("git psuh"),
+       NULL,
+};
+----
+
+Then, within your `cmd_psuh()` implementation, we can declare and populate our
+`option` struct. Ours is pretty boring but you can add more to it if you want to
+explore `parse_options()` in more detail:
+
+----
+       struct option options[] = {
+               OPT_END()
+       };
+----
+
+Finally, before you print your args and prefix, add the call to
+`parse-options()`:
+
+----
+       argc = parse_options(argc, argv, prefix, options, psuh_usage, 0);
+----
+
+This call will modify your `argv` parameter. It will strip the options you
+specified in `options` from `argv` and the locations pointed to from `options`
+entries will be updated. Be sure to replace your `argc` with the result from
+`parse_options()`, or you will be confused if you try to parse `argv` later.
+
+It's worth noting the special argument `--`. As you may be aware, many Unix
+commands use `--` to indicate "end of named parameters" - all parameters after
+the `--` are interpreted merely as positional arguments. (This can be handy if
+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.
+
+Build again. Now, when you run with `-h`, you should see your usage printed and
+your command terminated before anything else interesting happens. Great!
+
+Go ahead and commit this one, too.
+
+== Testing
+
+It's important to test your code - even for a little toy command like this one.
+Moreover, your patch won't be accepted into the Git tree without tests. Your
+tests should:
+
+* Illustrate the current behavior of the feature

Documentation/MyFirstContribution.txt new file +93 -0

+the schema shown in the Naming Tests section of `t/README`.
+
+=== Writing Your Test
+
+Since this a toy command, let's go ahead and name the test with t9999. However,
+as many of the family/subcmd combinations are full, best practice seems to be
+to find a command close enough to the one you've added and share its naming
+space.
+
+Create a new file `t/t9999-psuh-tutorial.sh`. Begin with the header as so (see
+"Writing Tests" and "Source 'test-lib.sh'" in `t/README`):
+
+----
+#!/bin/sh
+
+test_description='git-psuh test
+
+This test runs git-psuh and makes sure it does not crash.'
+
+. ./test-lib.sh
+----
+
+Tests are framed inside of a `test_expect_success` in order to output TAP
+formatted results. Let's make sure that `git psuh` doesn't exit poorly and does
+mention the right animal somewhere:
+
+----
+test_expect_success 'runs correctly with no args and good output' '
+       git psuh >actual &&
+       test_i18ngrep Pony actual
+'
+----
+
+Indicate that you've run everything you wanted by adding the following at the
+bottom of your script:
+
+----
+test_done
+----
+
+Make sure you mark your test script executable:
+
+----
+$ chmod +x t/t9999-psuh-tutorial.sh
+----
+
+You can get an idea of whether you created your new test script successfully
+by running `make -C t test-lint`, which will check for things like test number
+uniqueness, executable bit, and so on.
+
+=== Running Locally
+
+Let's try and run locally:
+
+----
+$ make
+$ cd t/ && prove t9999-psuh-tutorial.sh
+----
+
+You can run the full test suite and ensure `git-psuh` didn't break anything:
+
+----
+$ cd t/
+$ 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.
+
+Go ahead and commit this change, as well.
+
+== Getting Ready to Share
+
+You may have noticed already that the Git project performs its code reviews via
+emailed patches, which are then applied by the maintainer when they are ready
+and approved by the community. The Git project does not accept patches from
+pull requests, and the patches emailed for review need to be formatted a
+specific way. At this point the tutorial diverges, in order to demonstrate two
+different methods of formatting your patchset and getting it reviewed.
+
+The first method to be covered is GitGitGadget, which is useful for those
+already familiar with GitHub's common pull request workflow. This method
+requires a GitHub account.
+
+The second method to be covered is `git send-email`, which can give slightly
+more fine-grained control over the emails to be sent. This method requires some
+setup which can change depending on your system and will not be covered in this
+tutorial.
+
+Regardless of which method you choose, your engagement with reviewers will be
+the same; the review process will be covered after the sections on GitGitGadget

Documentation/MyFirstContribution.txt new file +76 -0

+
+To upload your branch to your own fork, you'll need to add the new fork as a
+remote. You can use `git remote -v` to show the remotes you have added already.
+From your new fork's page on GitHub, you can press "Clone or download" to get
+the URL; then you need to run the following to add, replacing your own URL and
+remote name for the examples provided:
+
+----
+$ git remote add remotename [email protected]:remotename/git.git
+----
+
+or to use the HTTPS URL:
+
+----
+$ git remote add remotename https://github.com/remotename/git/.git
+----
+
+Run `git remote -v` again and you should see the new remote showing up.
+`git fetch remotename` (with the real name of your remote replaced) in order to
+get ready to push.
+
+Next, double-check that you've been doing all your development in a new branch
+by running `git branch`. If you didn't, now is a good time to move your new
+commits to their own branch.
+
+As mentioned briefly at the beginning of this document, we are basing our work
+on `master`, so go ahead and update as shown below, or using your preferred
+workflow.
+
+----
+$ git checkout master
+$ git pull -r
+$ git rebase master psuh
+----
+
+Finally, you're ready to push your new topic branch! (Due to our branch and
+command name choices, be careful when you type the command below.)
+
+----
+$ git push remotename psuh
+----
+
+Now you should be able to go and check out your newly created branch on GitHub.
+
+=== Sending a PR to GitGitGadget
+
+In order to have your code tested and formatted for review, you need to start by
+opening a Pull Request against `gitgitgadget/git`. Head to
+https://github.com/gitgitgadget/git and open a PR either with the "New pull
+request" button or the convenient "Compare & pull request" button that may
+appear with the name of your newly pushed branch.
+
+Review the PR's title and description, as it's used by GitGitGadget as the cover
+letter for your change. When you're happy, submit your pull request.
+
+=== Running CI and Getting Ready to Send
+
+If it's your first time using GitGitGadget (which is likely, as you're using
+this tutorial) then someone will need to give you permission to use the tool.
+As mentioned in the GitGitGadget documentation, you just need someone who
+already uses it to comment on your PR with `/allow <username>`. GitGitGadget
+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.
+
+If the CI fails, you can update your changes with `git rebase -i` and push your
+branch again:
+
+----
+$ git push -f remotename psuh
+----
+
+In fact, you should continue to make changes this way up until the point when
+your patch is accepted into `next`.
+
+////