[PATCH 0/1] documentation: add lab for first contribution

[PATCH 0/1] documentation: add lab for first contribution

[Emily Shaffer via GitGitGadget]

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

[PATCH 1/1] documentation: add lab for first contribution

[Emily Shaffer via GitGitGadget]

From: Emily Shaffer <emilyshaffer@google.com>

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
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 <emilyshaffer@google.com>
---
 Documentation/MyFirstContribution | 674 ++++++++++++++++++++++++++++++
 1 file changed, 674 insertions(+)
 create mode 100644 Documentation/MyFirstContribution

diff --git a/Documentation/MyFirstContribution b/Documentation/MyFirstContribution
new file mode 100644
index 0000000000..9b87e424d6
--- /dev/null
+++ b/Documentation/MyFirstContribution
@@ -0,0 +1,674 @@
+My First Contribution
+=====================
+
+== Summary
+
+This is a codelab 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 codelab assumes you're already fairly familiar with using Git to manage
+source code.  The Git workflow steps will largely remain unexplained.
+
+=== Related Reading
+
+This codelab 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 the best place to clone from is GitHub.
+
+----
+git clone https://github.com/git/git git
+----
+
+=== Identify Problem to Solve
+
+In this codelab, 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 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
+----
+
+We'll make a number of commits here in order to demonstrate how to send many
+patches up for review simultaneously.
+
+== Code It Up!
+
+NOTE: A reference implementation can be found at
+https://github.com/nasamuffin/git/tree/codelab.
+
+=== Adding a new command
+
+Lots of the main useful commands are written as builtins, which means they are
+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`.
+
+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);
+----
+
+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.
+
+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.
+
+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,
+move to the root directory and build simply with `make -j$(nproc)`. Optionally, add
+the DEVELOPER=1 variable to turn on some additional warnings:
+
+----
+echo DEVELOPER=1 > config.mak
+make -j$(nproc)
+----
+
+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. 
+
+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
+----
+
+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.
+
+----
+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
+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
+commit that is not readily deduced from reading the associated diff,
+such as answering the question "why?".
+----
+
+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.
+
+=== Implementation
+
+It's probably useful to do at least something besides print 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:
+
+----
+	printf(Q_("Your args (there is %i):\n",
+		  "Your args (there are %i):\n",
+		  argc),
+	       argc);
+	for (int i = 0; i < argc; i++) {
+		printf("%s\n", argv[i]);
+	}
+	printf(_("Your prefix:\n%s\n"), prefix);
+----
+
+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;
+
+...
+
+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 methods 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"
+----
+
+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.
+
+----
+#include "wt-status.h"
+
+...
+
+// Add a wt_status to fill at the top.
+struct wt_status status;
+
+...
+
+// modify the prior code:
+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"
+----
+
+TODO: ref & object read
+
+=== 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 - Chastise 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.  Feel free to add new headers if you wish.
+
+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
+----
+
+or
+
+----
+make -C Documentation/git-psuh.1
+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.
+
+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 like:
+
+----
+	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` and `options` parameters. It will strip
+options you specified in `options` from `argv` and populate them in `options`
+instead, if they were provided. 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.
+So let's add some tests.
+
+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
+----
+
+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:
+
+----
+test_expect_success 'runs correctly with no args' '
+	rm -rf workbench upstream &&
+	test_create_repo upstream &&
+----
+
+`test_create_repo` comes from `test-lib.sh`. Next, we'll modify the above to
+move into the new repo and run our new command:
+
+----
+test_expect_success 'runs correctly with no args' '
+	rm -rf workbench upstream &&
+	test_create_repo upstream &&
+	(
+		cd upstream &&
+		git psuh
+	)
+'
+----
+
+Indicate that you've run everything you wanted by adding the following at the
+bottom of your script:
+
+----
+test_done
+----
+
+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 -j$(nproc)
+cd t/ && prove t9999-psuh-codelab.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
+----
+
+(You can also do this with `make test` but `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 - more to come on that soon.
+
+Before you send your patch off to be reviewed by the wide world, it's a good
+idea to run the continuous integration build and test suites against your new
+changes. You can do this manually or by using GitGitGadget, but either way,
+you're going to need to fork. First thing - make sure you have a GitHub
+account.
+
+=== Forking git/git on GitHub
+
+Head to the https://github.com/git/git[GitHub mirror] and look for the Fork
+button. Place your fork wherever you deem appropriate and create it.
+
+=== Uploading To Your Own Fork
+
+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 git@github.com: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 doc, 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.
+
+////
+TODO: The next few bullets describe testing and pushing your change with
+GitGitGadget. It may be useful to describe a workflow using git send-email as
+well.
+////
+
+=== Sending a PR to GitGitGadget
+
+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.
+It's documented at gitgitgadget.github.io.
+
+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.
+
+=== Getting CI to Run
+
+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 doc, 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.
+
+If the CI fails, you can update your changes with `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`.
+
+////
+TODO https://github.com/gitgitgadget/gitgitgadget/issues/83
+It'd be nice to be able to verify that the patch looks good before sending it
+to everyone on Git mailing list.
+=== Check Your Work 
+////
+
+=== Sending Your Patches
+
+Now that your CI is passing and someone has granted you permission to use
+GitGitGadget with the `/allow` command,  sending out for review is as simple as
+commenting on your PR with `/submit`.
+
+=== Updating With Comments
+
+As documented on the GitGitGadget site, when a reviewer asks you for changes,
+you can make them using `git rebase -i`. When you're ready, force push to your
+fork's branch again, just like when you were getting the CI to pass above.
+
+NOTE: Interactive rebase can be tricky; check out this handy
+https://www.oreilly.com/library/view/git-pocket-guide/9781449327507/ch10.html
+[overview] from O'Reilly.
+
+////
+This is the path for git send-email. Do we want to cover that approach as well?
+=== Running with Travis On Your Fork
+
+== Sending For Review
+
+=== Preparing initial patchset
+
+=== Preparing email
+
+=== Sending email
+
+=== Applying Changes
+
+=== Sending v2
+
+End of path for git send-email
+////
+
+== Now What?
+
+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.
+
+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.
+
+However, if it isn't so perfect, once it is in `next`, you can no longer modify
+your commits in GitGitGadget. Consider that PR "closed" - you will need to
+repeat the entire process for any bug fix commits you need to send, basing your
+changes on the maintainer's topic branch for your work instead of `master`.
+These topic branches are typically detailed in https://github.com/gitster/git
+and are mirrored by GitGitGadget. Since they're mirrored, you can still  use
+GitGitGadget to send email patches, as long as you've based your PR against the
+appropriate GitGitGadget/Git branch.
+
+(TODO - does that mean that GGG will Just Work for those branches?)
-- 
gitgitgadget

Re: [PATCH 0/1] documentation: add lab for first contribution

[Josh Steadmon]

On 2019.04.11 11:32, Emily Shaffer via GitGitGadget wrote:
> 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
> -- 
> gitgitgadget

Generally looks good to me! I definitely learned a few things.

In the doc, you ask whether or not to cover the 'git send-email'
workflow; I think it would be a good idea.

It would also be nice to have the Documentation/Makefile automatically
generate an HTML page for this; looks like you can follow
SubmittingPatches as an example.

I spotted a typo and a couple of whitespace issues; a fixup patch for
this is included below.

-- >8 --

Subject: [PATCH] fixup! documentation: add lab for first contribution

---
 Documentation/MyFirstContribution | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/Documentation/MyFirstContribution b/Documentation/MyFirstContribution
index 9b87e424d6..07c0b3f194 100644
--- a/Documentation/MyFirstContribution
+++ b/Documentation/MyFirstContribution
@@ -65,7 +65,7 @@ https://github.com/nasamuffin/git/tree/codelab.
 === Adding a new command
 
 Lots of the main useful commands are written as builtins, which means they are
-implemented in C and compiled into the main `git` executable.. So it is
+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`.
@@ -111,7 +111,7 @@ 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. 
+cmd_push is registered, copy it, and modify it for cmd_psuh.
 
 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,
@@ -608,7 +608,7 @@ your patch is accepted into `next`.
 TODO https://github.com/gitgitgadget/gitgitgadget/issues/83
 It'd be nice to be able to verify that the patch looks good before sending it
 to everyone on Git mailing list.
-=== Check Your Work 
+=== Check Your Work
 ////
 
 === Sending Your Patches
-- 
2.21.0.392.gf8f6787159e-goog

Re: [PATCH 0/1] documentation: add lab for first contribution

[Junio C Hamano]

"Emily Shaffer via GitGitGadget" <gitgitgadget@gmail.com> writes:

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

Re: [PATCH 1/1] documentation: add lab for first contribution

[Junio C Hamano]

"Emily Shaffer via GitGitGadget" <gitgitgadget@gmail.com> writes:

> diff --git a/Documentation/MyFirstContribution b/Documentation/MyFirstContribution
> new file mode 100644
> index 0000000000..9b87e424d6
> --- /dev/null
> +++ b/Documentation/MyFirstContribution
> @@ -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?

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

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

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

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

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

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

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

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

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

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

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

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

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

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

> +
> +----
> +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
> +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 ;-).

> +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 <author@example.com>" here.

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

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

Re: [PATCH 1/1] documentation: add lab for first contribution

[Emily Shaffer]

On Thu, Apr 11, 2019 at 8:20 PM Junio C Hamano <gitster@pobox.com> wrote:
>
> "Emily Shaffer via GitGitGadget" <gitgitgadget@gmail.com> writes:
>
> > diff --git a/Documentation/MyFirstContribution b/Documentation/MyFirstContribution
> > new file mode 100644
> > index 0000000000..9b87e424d6
> > --- /dev/null
> > +++ b/Documentation/MyFirstContribution
> > @@ -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?

I was basing the format of this document on
Documentation/SubmittingPatches, which underlines the document
title but prefixes the rest of the headers with /=+/ to indicate level. I
can change it, but I like the hierarchical headers offered by ={1,4}
prefix.

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

Good point, I'll extend the title.

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

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

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

I was hoping to indicate that it would be an informative exercise for the reader
who is following the tutorial. I'll try to reword this and make it
more clear; thanks
for the example.

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

I'd just as soon change this documentation when that push changes the
other decls,
rather than spend time explaining a transient shift in how to do
something in one
file, but if you wish I can encourage the new good behavior here instead.

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

You got me! Fixed throughout the file. Hanging head in shame. Etc.

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

Sure, done.

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

Done, mentioned alphabetical order.

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

I'd like to add a line mentioning that someone ought to report that the flag
was broken for them. Is the preference to have that reported to the mail
list?

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

Good point. I'll mention that the Git build is parallelizable and leave it
at that.

>
> > +----
> > +echo DEVELOPER=1 > config.mak
>
> Follow the Documentation/CodingGuildelines when writing for our
> developers.  Lose SP between the redirection operator and its
> target filename.

Done, thanks.

>
> > +make -j$(nproc)
> > +----
>
> > +
> > +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.
>

I'll add mention of it in the documentation section.

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

Done, mentioned 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
> > +`./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
> > +----
> > +
> > +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?
>

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

> > +
> > +----
> > +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
> > +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 ;-)
>

I'll blame dscho for that one :)

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

It's a good point though. I'd like to avoid technical grammar names
since obviously myself and dscho can't keep them straight ;) so I'll try
to explain better.

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

Credit to dscho for the last paragraph :)

>
> Keep a sample sign-off by "A U Thor <author@example.com>" here.
>
> > +----
> > +
> > +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.
>
> > +=== 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.
>

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

-- 
Emily Shaffer

Re: [PATCH 0/1] documentation: add lab for first contribution

[Emily Shaffer]

On Thu, Apr 11, 2019 at 7:35 PM Junio C Hamano <gitster@pobox.com> wrote:
>
> "Emily Shaffer via GitGitGadget" <gitgitgadget@gmail.com> writes:
>
> > 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"?
>
I think you're right; I'll try to modify throughout. As part of that
change I will also move the sample to a branch with a more descriptive
name and change the URL.

Thanks a lot for the detailed review, Junio. I expect to send a new
patch later today, including an exercise in examining a specific
commit.

-- 
Emily Shaffer

Re: [PATCH 1/1] documentation: add lab for first contribution

[Junio C Hamano]

Emily Shaffer <emilyshaffer@google.com> writes:

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

The verb "create" is not incorrect per-se.  It stops at saying that
the result points at the commit that happened to be at the tip of
the original when it was created.  But it lacks the connotation that
the resulting branch also knows that it is meant to eventually be
merged back to the line of history of the original, which "fork"
conveys.

The word "fork" is pretty well established in that context of
talking about a branch, in the form of "--fork-point" option of "git
rebase".  It is the point where a side branch diverged from the
mainline.

So I dunno.

        Side note. By the way "fork" is in no way GitHub specific.
        A random list archive search gives us this from 2007 but I
        am reasonably sure that Linus kept using the word before I
        took the maintainership over, in the context of talking
        about "distributed nature of Git makes the 'maintainer'
        honest, by allowing others to fork and become the mainstream
        if the maintainer does a bad job".

        http://public-inbox.org/git/alpine.LFD.0.98.0705010829180.3808@woody.linux-foundation.org/

        So it is fairly well understood what "fork" means in the
        project management sense around here in the Git project.

        In any case, that is a tangent.  That possible "conflation"
        is about forking the whole repository, but the example is
        talking about getting a single new branch to work on, so in
        a sense it is an apples-and-oranges comparison.

>> ... 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 <very@smart.dev>" for the example.
> ...
>> Keep a sample sign-off by "A U Thor <author@example.com>" here.


No, use "A U Thor <author@example.com>" 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*.

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

Re: [PATCH 1/1] documentation: add lab for first contribution

[Emily Shaffer]

> >> ... 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 <very@smart.dev>" for the example.
> > ...
> >> Keep a sample sign-off by "A U Thor <author@example.com>" here.
>
>
> No, use "A U Thor <author@example.com>" 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.

Done.

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

Sorry about that. I've found it's good practice to "show, don't tell"
when I make review
comments to avoid confusion, which isn't quite the same as "do it
exactly like this"
but looks similar on the box. So I guessed wrong this time. :) Will
push a fix with it.

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

In that case, I'd just as soon leave the order as it is. I think that
a developer,
outside of the context of a tutorial, will end up writing tests in the
order they
prefer regardless of the order of a tutorial they did one time. Maybe I can add
a note about tests being required for incoming patches to discourage readers
from glossing over that section.

>
> Thanks.

[PATCH v2 0/1] documentation: add lab for first contribution

[Emily Shaffer via GitGitGadget]

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/.gitignore          |   1 +
 Documentation/Makefile            |   5 +
 Documentation/MyFirstContribution | 887 ++++++++++++++++++++++++++++++
 3 files changed, 893 insertions(+)
 create mode 100644 Documentation/MyFirstContribution


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

Range-diff vs v1:

 1:  8b71fe7871 ! 1:  71d5ab539c documentation: add lab for first contribution
     @@ -10,27 +10,67 @@
      
          Signed-off-by: Emily Shaffer <emilyshaffer@google.com>
      
     + diff --git a/Documentation/.gitignore b/Documentation/.gitignore
     + --- a/Documentation/.gitignore
     + +++ b/Documentation/.gitignore
     +@@
     + mergetools-*.txt
     + manpage-base-url.xsl
     + SubmittingPatches.txt
     ++MyFirstContribution.txt
     + tmp-doc-diff/
     +
     + diff --git a/Documentation/Makefile b/Documentation/Makefile
     + --- a/Documentation/Makefile
     + +++ b/Documentation/Makefile
     +@@
     + 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
     +@@
     + 	$(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
     + 
     +@@
     + SubmittingPatches.txt: SubmittingPatches
     + 	$(QUIET_GEN) cp $< $@
     + 
     ++MyFirstContribution.txt: MyFirstContribution
     ++	$(QUIET_GEN) cp $< $@
     ++
     + XSLT = docbook.xsl
     + XSLTOPTS = --xinclude --stringparam html.stylesheet docbook-xsl.css
     + 
     +
       diff --git a/Documentation/MyFirstContribution b/Documentation/MyFirstContribution
       new file mode 100644
       --- /dev/null
       +++ b/Documentation/MyFirstContribution
      @@
     -+My First Contribution
     -+=====================
     ++My First Contribution to the Git Project
     ++========================================
      +
      +== Summary
      +
     -+This is a codelab demonstrating the end-to-end workflow of creating a change to
     ++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 codelab assumes you're already fairly familiar with using Git to manage
     ++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 codelab aims to summarize the following documents, but the reader may find
     ++This tutorial aims to summarize the following documents, but the reader may find
      +useful additional context:
      +
      +- Documentation/SubmittingPatches
     @@ -49,7 +89,7 @@
      +
      +=== Identify Problem to Solve
      +
     -+In this codelab, we will add a new command, `git psuh`, short for "Pony Saying
     ++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.
      +
     @@ -63,12 +103,12 @@
      +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.
     ++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
     ++git checkout -b psuh origin/master
      +----
      +
      +We'll make a number of commits here in order to demonstrate how to send many
     @@ -77,17 +117,19 @@
      +== Code It Up!
      +
      +NOTE: A reference implementation can be found at
     -+https://github.com/nasamuffin/git/tree/codelab.
     ++https://github.com/nasamuffin/git/tree/psuh.
      +
      +=== Adding a new command
      +
      +Lots of the main useful commands are written as builtins, which means they are
     -+implemented in C and compiled into the main `git` executable.. So it is
     -+informative to implement `git psuh` as a builtin.
     ++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.
      +
     -+Create a new file in `builtin/` called `psuh.c`.
     -+
     -+The entry point of your new command needs to match a certain signature:
     ++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
     ++for your command in a function matching the style and signature:
      +
      +----
      +int cmd_psuh(int argc, const char **argv, const char *prefix)
     @@ -102,7 +144,7 @@
      +
      +Be sure to `#include "builtin.h"` in your `psuh.c`.
      +
     -+Go ahead and add some throwaway printf to that method. This is a decent
     ++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
     @@ -111,16 +153,32 @@
      +the lab, 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. Once you've done so,
     -+move to the root directory and build simply with `make -j$(nproc)`. Optionally, add
     -+the DEVELOPER=1 variable to turn on some additional warnings:
     ++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 -j$(nproc)
     ++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.
      +
     @@ -128,7 +186,8 @@
      +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. 
     ++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,
     @@ -165,10 +224,13 @@
      +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
     ++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 <author@example.com>
      +----
      +
      +Go ahead and inspect your new commit with `git show`. "psuh:" indicates you
     @@ -226,7 +288,7 @@
      +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 methods like this one; you can see them all (and more info
     ++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:
     @@ -284,7 +346,55 @@
      +git commit -sm "psuh: print the current branch"
      +----
      +
     -+TODO: ref & object read
     ++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:
     ++
     ++----
     ++#include "commit.h"
     ++#include "pretty.h"
     ++
     ++...
     ++
     ++struct commit *c = NULL;
     ++struct strbuf commitline;
     ++strbuf_init(&commitline, 0);
     ++
     ++...
     ++
     ++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 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
      +
     @@ -314,7 +424,7 @@
      +
      +NAME
      +----
     -+git-psuh - Chastise users' typo with a shy horse
     ++git-psuh - Delight users' typo with a shy horse
      +
      +
      +SYNOPSIS
     @@ -364,6 +474,10 @@
      +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
     @@ -424,7 +538,8 @@
      +== Testing
      +
      +It's important to test your code - even for a little toy command like this one.
     -+So let's add some tests.
     ++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.
      +
      +Related reading: `t/README`
      +
     @@ -580,11 +695,11 @@
      +
      +Now you should be able to go and check out your newly created branch on GitHub.
      +
     -+////
     -+TODO: The next few bullets describe testing and pushing your change with
     -+GitGitGadget. It may be useful to describe a workflow using git send-email as
     -+well.
     -+////
     ++== Sending Patches via GitGitGadget
     ++
     ++One option for sending patches is to follow a typical pull request workflow and
     ++send your patches out via GitGitGadget. This section outlines the steps for this
     ++workflow; if you'd rather use `git send-email` skip ahead.
      +
      +=== Sending a PR to GitGitGadget
      +
     @@ -625,7 +740,7 @@
      +TODO https://github.com/gitgitgadget/gitgitgadget/issues/83
      +It'd be nice to be able to verify that the patch looks good before sending it
      +to everyone on Git mailing list.
     -+=== Check Your Work 
     ++=== Check Your Work
      +////
      +
      +=== Sending Your Patches
     @@ -644,24 +759,162 @@
      +https://www.oreilly.com/library/view/git-pocket-guide/9781449327507/ch10.html
      +[overview] from O'Reilly.
      +
     ++== Sending Patches with `git send-email`
     ++
     ++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!
     ++
      +////
     -+This is the path for git send-email. Do we want to cover that approach as well?
     ++It seems like a lot of work to set up Travis to point to your own fork, and it
     ++obviates the big reason not to use GGG - not having a GitHub account. For now,
     ++we'll skip covering Travis with personal fork.
      +=== Running with Travis On Your Fork
     ++////
     ++
     ++=== Prerequisite: Setting Up `git send-email`
      +
     -+== Sending For Review
     ++Configuration for `send-email` can vary based on your operating system and email
     ++provider, and so will not be covered in this lab, beyond stating that in many
     ++distributions of Linux, `git-send-email` is not packaged alongside the typical
     ++`git` install. You may need to install this additional package; there are a
     ++number of resources online to help you do so.
      +
      +=== Preparing initial patchset
      +
     ++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.
     ++
     ++`master..psuh` tells `format-patch` to generate patches for the difference
     ++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!
     ++
      +=== Preparing email
      +
     ++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.
     ++
     ++----
     ++git send-email \
     ++	--to=target@server.tld \
     ++	--from=me@server.tld \
     ++	--subject="[PATCH 0/7] adding the 'psuh' command" \
     ++	--compose \
     ++	psuh/
     ++----
     ++
     ++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
     ++before sending the rest of the mails. Finally, `psuh/` attaches your directory
     ++full of commit patches, prompting `send-email` to send one email per patch.
     ++
     ++When you run this, you'll get an editor so you have a chance to fill out your
     ++cover letter. This is an important component of change submission as it explains
     ++to the community from a high level what you're trying to do, and why, in a way
     ++that's more apparent than just looking at your diff. Be sure to explain anything
     ++your diff doesn't make clear on its own.
     ++
     ++It's also good practice to include a diffstat, which you can generate like so:
     ++
     ++----
     ++git diff --stat=72 master..psuh
     ++----
     ++
     ++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.
     ++
     ++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 `git@vger.kernel.org`
     ++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!
     ++
     ++Awesome, now the community will drop everything and review your changes. (Just
     ++kidding - be patient!)
     ++
      +=== Applying Changes
      +
     -+=== Sending v2
     ++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
     ++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.
      +
     -+End of path for git send-email
      +////
     ++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
     ++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.
     ++* 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.
      +
      +== Now What?
      +
     @@ -680,12 +933,12 @@
      +will pull your patchset into `next` and life is good.
      +
      +However, if it isn't so perfect, once it is in `next`, you can no longer modify
     -+your commits in GitGitGadget. Consider that PR "closed" - you will need to
     -+repeat the entire process for any bug fix commits you need to send, basing your
     -+changes on the maintainer's topic branch for your work instead of `master`.
     -+These topic branches are typically detailed in https://github.com/gitster/git
     -+and are mirrored by GitGitGadget. Since they're mirrored, you can still  use
     -+GitGitGadget to send email patches, as long as you've based your PR against the
     -+appropriate GitGitGadget/Git branch.
     -+
     -+(TODO - does that mean that GGG will Just Work for those branches?)
     ++your commits in GitGitGadget or the email thread. Consider that review "closed" 
     ++- you will need to repeat the entire process for any bug fix commits you need
     ++to send, basing your changes on the maintainer's topic branch for your work
     ++instead of `master`. These topic branches are typically detailed in
     ++https://github.com/gitster/git and are mirrored by GitGitGadget. Since they're
     ++mirrored, you can still  use GitGitGadget to send email patches, as long as
     ++you've based your PR against the appropriate GitGitGadget/Git branch. Or, you
     ++can use `git send-email` just the same as before, except you will generate diffs
     ++from `<topic>..<mybranch>` and base your work on `<topic>` instead of `master`.

-- 
gitgitgadget

[PATCH v2 1/1] documentation: add lab for first contribution

[Emily Shaffer via GitGitGadget]

From: Emily Shaffer <emilyshaffer@google.com>

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
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 <emilyshaffer@google.com>
---
 Documentation/.gitignore          |   1 +
 Documentation/Makefile            |   5 +
 Documentation/MyFirstContribution | 887 ++++++++++++++++++++++++++++++
 3 files changed, 893 insertions(+)
 create mode 100644 Documentation/MyFirstContribution

diff --git a/Documentation/.gitignore b/Documentation/.gitignore
index 3ef54e0adb..c3643661bf 100644
--- a/Documentation/.gitignore
+++ b/Documentation/.gitignore
@@ -12,4 +12,5 @@ cmds-*.txt
 mergetools-*.txt
 manpage-base-url.xsl
 SubmittingPatches.txt
+MyFirstContribution.txt
 tmp-doc-diff/
diff --git a/Documentation/Makefile b/Documentation/Makefile
index 26a2342bea..af303c2419 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -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
 
@@ -379,6 +381,9 @@ $(patsubst %,%.html,$(API_DOCS) technical/api-index $(TECH_DOCS)): %.html : %.tx
 SubmittingPatches.txt: SubmittingPatches
 	$(QUIET_GEN) cp $< $@
 
+MyFirstContribution.txt: MyFirstContribution
+	$(QUIET_GEN) cp $< $@
+
 XSLT = docbook.xsl
 XSLTOPTS = --xinclude --stringparam html.stylesheet docbook-xsl.css
 
diff --git a/Documentation/MyFirstContribution b/Documentation/MyFirstContribution
new file mode 100644
index 0000000000..40d1a3b8d7
--- /dev/null
+++ b/Documentation/MyFirstContribution
@@ -0,0 +1,887 @@
+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 the best place to clone from is GitHub.
+
+----
+git clone https://github.com/git/git git
+----
+
+=== Identify Problem to Solve
+
+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 doc and base it on the appropriate branch.
+
+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
+----
+
+We'll make a number of commits here in order to demonstrate how to send many
+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 main useful commands are written as builtins, which means they are
+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.
+
+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
+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:
+
+----
+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 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.
+
+----
+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
+`./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
+----
+
+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.
+
+----
+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
+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 <author@example.com>
+----
+
+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.
+
+=== Implementation
+
+It's probably useful to do at least something besides print 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:
+
+----
+	printf(Q_("Your args (there is %i):\n",
+		  "Your args (there are %i):\n",
+		  argc),
+	       argc);
+	for (int i = 0; i < argc; i++) {
+		printf("%s\n", argv[i]);
+	}
+	printf(_("Your prefix:\n%s\n"), prefix);
+----
+
+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;
+
+...
+
+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"
+----
+
+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.
+
+----
+#include "wt-status.h"
+
+...
+
+// Add a wt_status to fill at the top.
+struct wt_status status;
+
+...
+
+// modify the prior code:
+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:
+
+----
+#include "commit.h"
+#include "pretty.h"
+
+...
+
+struct commit *c = NULL;
+struct strbuf commitline;
+strbuf_init(&commitline, 0);
+
+...
+
+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 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.  Feel free to add new headers if you wish.
+
+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
+----
+
+or
+
+----
+make -C Documentation/git-psuh.1
+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 like:
+
+----
+	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` and `options` parameters. It will strip
+options you specified in `options` from `argv` and populate them in `options`
+instead, if they were provided. 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 to
+demonstrate that it does what it's supposed to do. So let's add some tests.
+
+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
+----
+
+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:
+
+----
+test_expect_success 'runs correctly with no args' '
+	rm -rf workbench upstream &&
+	test_create_repo upstream &&
+----
+
+`test_create_repo` comes from `test-lib.sh`. Next, we'll modify the above to
+move into the new repo and run our new command:
+
+----
+test_expect_success 'runs correctly with no args' '
+	rm -rf workbench upstream &&
+	test_create_repo upstream &&
+	(
+		cd upstream &&
+		git psuh
+	)
+'
+----
+
+Indicate that you've run everything you wanted by adding the following at the
+bottom of your script:
+
+----
+test_done
+----
+
+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 -j$(nproc)
+cd t/ && prove t9999-psuh-codelab.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
+----
+
+(You can also do this with `make test` but `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 - more to come on that soon.
+
+Before you send your patch off to be reviewed by the wide world, it's a good
+idea to run the continuous integration build and test suites against your new
+changes. You can do this manually or by using GitGitGadget, but either way,
+you're going to need to fork. First thing - make sure you have a GitHub
+account.
+
+=== Forking git/git on GitHub
+
+Head to the https://github.com/git/git[GitHub mirror] and look for the Fork
+button. Place your fork wherever you deem appropriate and create it.
+
+=== Uploading To Your Own Fork
+
+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 git@github.com: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 doc, 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 Patches via GitGitGadget
+
+One option for sending patches is to follow a typical pull request workflow and
+send your patches out via GitGitGadget. This section outlines the steps for this
+workflow; if you'd rather use `git send-email` skip ahead.
+
+=== Sending a PR to GitGitGadget
+
+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.
+It's documented at gitgitgadget.github.io.
+
+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.
+
+=== Getting CI to Run
+
+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 doc, 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.
+
+If the CI fails, you can update your changes with `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`.
+
+////
+TODO https://github.com/gitgitgadget/gitgitgadget/issues/83
+It'd be nice to be able to verify that the patch looks good before sending it
+to everyone on Git mailing list.
+=== Check Your Work
+////
+
+=== Sending Your Patches
+
+Now that your CI is passing and someone has granted you permission to use
+GitGitGadget with the `/allow` command,  sending out for review is as simple as
+commenting on your PR with `/submit`.
+
+=== Updating With Comments
+
+As documented on the GitGitGadget site, when a reviewer asks you for changes,
+you can make them using `git rebase -i`. When you're ready, force push to your
+fork's branch again, just like when you were getting the CI to pass above.
+
+NOTE: Interactive rebase can be tricky; check out this handy
+https://www.oreilly.com/library/view/git-pocket-guide/9781449327507/ch10.html
+[overview] from O'Reilly.
+
+== Sending Patches with `git send-email`
+
+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!
+
+////
+It seems like a lot of work to set up Travis to point to your own fork, and it
+obviates the big reason not to use GGG - not having a GitHub account. For now,
+we'll skip covering Travis with personal fork.
+=== Running with Travis On Your Fork
+////
+
+=== Prerequisite: Setting Up `git send-email`
+
+Configuration for `send-email` can vary based on your operating system and email
+provider, and so will not be covered in this lab, beyond stating that in many
+distributions of Linux, `git-send-email` is not packaged alongside the typical
+`git` install. You may need to install this additional package; there are a
+number of resources online to help you do so.
+
+=== Preparing initial patchset
+
+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.
+
+`master..psuh` tells `format-patch` to generate patches for the difference
+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!
+
+=== Preparing email
+
+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.
+
+----
+git send-email \
+	--to=target@server.tld \
+	--from=me@server.tld \
+	--subject="[PATCH 0/7] adding the 'psuh' command" \
+	--compose \
+	psuh/
+----
+
+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
+before sending the rest of the mails. Finally, `psuh/` attaches your directory
+full of commit patches, prompting `send-email` to send one email per patch.
+
+When you run this, you'll get an editor so you have a chance to fill out your
+cover letter. This is an important component of change submission as it explains
+to the community from a high level what you're trying to do, and why, in a way
+that's more apparent than just looking at your diff. Be sure to explain anything
+your diff doesn't make clear on its own.
+
+It's also good practice to include a diffstat, which you can generate like so:
+
+----
+git diff --stat=72 master..psuh
+----
+
+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.
+
+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 `git@vger.kernel.org`
+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!
+
+Awesome, now the community will drop everything and review your changes. (Just
+kidding - be patient!)
+
+=== Applying Changes
+
+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
+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
+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.
+* 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.
+
+== Now What?
+
+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.
+
+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.
+
+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" 
+- you will need to repeat the entire process for any bug fix commits you need
+to send, basing your changes on the maintainer's topic branch for your work
+instead of `master`. These topic branches are typically detailed in
+https://github.com/gitster/git and are mirrored by GitGitGadget. Since they're
+mirrored, you can still  use GitGitGadget to send email patches, as long as
+you've based your PR against the appropriate GitGitGadget/Git branch. Or, you
+can use `git send-email` just the same as before, except you will generate diffs
+from `<topic>..<mybranch>` and base your work on `<topic>` instead of `master`.
-- 
gitgitgadget

Re: [PATCH v2 0/1] documentation: add lab for first contribution

[Emily Shaffer]

On Tue, Apr 16, 2019 at 1:26 PM Emily Shaffer via GitGitGadget
<gitgitgadget@gmail.com> wrote:
>
> RFC. I am still working on adding a section on handling refs and objects.

Sorry for the spam; above line was stale in GitGitGadget. The relevant
section has been added
just before the help page. I think the change is complete pending
review comments.

I've also added instructions for using send-email in addition to GitGitGadget.

Thanks!

Re: [PATCH v2 1/1] documentation: add lab for first contribution

[Junio C Hamano]

"Emily Shaffer via GitGitGadget" <gitgitgadget@gmail.com> writes:

> Subject: Re: [PATCH v2 1/1] documentation: add lab for first contribution
> From: Emily Shaffer <emilyshaffer@google.com>
>
> 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.

> diff --git a/Documentation/Makefile b/Documentation/Makefile
> index 26a2342bea..af303c2419 100644
> --- a/Documentation/Makefile
> +++ b/Documentation/Makefile
> @@ -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
>  
> @@ -379,6 +381,9 @@ $(patsubst %,%.html,$(API_DOCS) technical/api-index $(TECH_DOCS)): %.html : %.tx
>  SubmittingPatches.txt: SubmittingPatches
>  	$(QUIET_GEN) cp $< $@
>  
> +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?

> +== Getting Started
> +
> +=== 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 ..."?

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

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

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

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

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

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

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

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

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

> +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/;

> +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").

> +
> +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?".

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.

> +
> +Signed-off-by: A U Thor <author@example.com>
> +----
> +
> +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".

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

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

s/print/&ing/

> +start by having a look at everything we get.
> +
> +Modify your `cmd_psuh` implementation to dump the args you're passed:
> +
> +----
> +	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..

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

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

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

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

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

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

(I won't repeat this for brevity).

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

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

> +struct wt_status status;
> +
> +...
> +
> +// modify the prior code:
> +wt_status_prepare(the_repository, &status);
> +git_config(git_default_config, &status);
> +
> +...
> +
> +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.

> +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:
> +
> +----
> +#include "commit.h"
> +#include "pretty.h"
> +
> +...
> +
> +struct commit *c = NULL;
> +struct strbuf commitline;
> +strbuf_init(&commitline, 0);

	struct strbuf commitline = STRBUF_INIT

perhaps?

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

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

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

;-)

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

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

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

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

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

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

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

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

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?

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

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

> +=== Sending a PR to GitGitGadget
> +
> +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/

> +== Sending Patches with `git send-email`
> +
> +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 ...

> +=== Preparing initial patchset
> +
> +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.

> +`master..psuh` tells `format-patch` to generate patches for the difference
> +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.

> +=== Preparing email
> +
> +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.

> +----
> +git send-email \
> +	--to=target@server.tld \
> +	--from=me@server.tld \
> +	--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.

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

> +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 `git@vger.kernel.org`
> +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).

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

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

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

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

> +== Now What?
> +
> +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.
> +
> +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.

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

Re: [PATCH v2 1/1] documentation: add lab for first contribution

[Eric Sunshine]

On Wed, Apr 17, 2019 at 1:32 AM Junio C Hamano <gitster@pobox.com> wrote:
> "Emily Shaffer via GitGitGadget" <gitgitgadget@gmail.com> writes:
> > +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/20180831063318.33373-2-sunshine@sunshineco.com/

Re: [PATCH v2 1/1] documentation: add lab for first contribution

[Emily Shaffer]

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

You're right. My find/replace missed the commit; I'll read through the document
again as well.

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

The only reason is that I wasn't aware of the special case. Fixed.

> > +== Getting Started
> > +
> > +=== 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 ..."?

I'll change it. But it seems odd to say that when git-scm.com only mentions
the one mirror.

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

Sure. I'll check across for instances of "lab" and reword them to
"tutorial"; same for "doc"
vs "document" etc.

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

I appreciate your comment about clarity. But including the prompt also
makes it more difficult to copy-paste into the command line...
I think if someone is blindly copy-pasting this tutorial, they won't
be getting a lot out of it anyway. So I'll add the prompts.

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

Good suggestion, thank you.

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

 Sure, done.

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

Good suggestion. Thanks. I riffed on it a little:

    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, write the entry point
>
> s/within/& it/ perhaps?

Done.

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

Done, the explicit mention is a good point.

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

Not sure I understand. They won't see any of it but the signoff line
in their editor.
Maybe it's okay to add "You'll be presented with your editor in order
to write a commit message", followed by the tips?

> > +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/;
>
> > +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").

Sure.

> > +
> > +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?".
>
> 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.

I'm not sure what change you're looking for. The widest line (ending
in "as") is 72 columns. Do you mean that you'd like each line to be
exactly 72 characters to the end of the word..?

> > +
> > +Signed-off-by: A U Thor <author@example.com>
> > +----
> > +
> > +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".
Done.

> > +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.
>
> > +=== Implementation
> > +
> > +It's probably useful to do at least something besides print out a string. Let's
>
> s/print/&ing/

Sure.. I think it's fine either way, but changed.

> > +start by having a look at everything we get.
> > +
> > +Modify your `cmd_psuh` implementation to dump the args you're passed:
> > +
> > +----
> > +     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..

Done.

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

Good idea.

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

You're right; this is stale compared to the sample implementation,
where I fixed this issue
(but didn't update doc). I'll change it to this:

     printf(_("Your current working directory:\n<top-level>%s%s\n"),
              prefix ? "/" : "", prefix ? prefix : "");

(thanks to dscho for the suggestion via github)

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

Sure, good catch.

>
> > +...
> > +
> > +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
> > +----
>
>         ----
>         $ git config --get user.name
>         ----
>
> (I won't repeat this for brevity).
>
> > +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.

Done.

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

You give me a lot of credit, when in reality, I'm a lowly C++
developer still learning. ;)

I'm actually going to try to reword this and other modification
examples below to make it more clear where to add the various pieces.
I don't think the "..." says as much as I wanted.

> > +struct wt_status status;
> > +
> > +...
> > +
> > +// modify the prior code:
> > +wt_status_prepare(the_repository, &status);
> > +git_config(git_default_config, &status);
> > +
> > +...
> > +
> > +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.

Yep.

As an aside, I wonder if it would have been clearer to try to show
unified-diff added lines with more of the file shown for context.
Probably not... :)

> > +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:
> > +
> > +----
> > +#include "commit.h"
> > +#include "pretty.h"
> > +
> > +...
> > +
> > +struct commit *c = NULL;
> > +struct strbuf commitline;
> > +strbuf_init(&commitline, 0);
>
>         struct strbuf commitline = STRBUF_INIT
>
> perhaps?

grep reveals about 10x instances of STRBUF_INIT exist compared to
strbuf_init(...). Sure, I'll fix it. :)

While I'm at it, I'm rewording this area as above to make it more
clear where changes should go.

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

Ok.

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

Sure, done.

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

I was sure that I saw a piece of documentation suggesting to add new
headers if necessary, i.e., "--foo options" or something. Perhaps I
dreamed it. I'll remove this suggestion and replace it with a
recommendation to use well-established manpage headers.

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

Per later email, I'll leave this the way it is.

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

I agree, although it should be a case never seen by the user - there
is a test to ensure that all commands handle "-h", so new commands
will yell during CI stage if this failure would occur...

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

Yep, done.  (Is it better generally to use foo(), or foo(...) to
indicate that isn't argumentless?) There are other places within the
tutorial where I neglected to do so. I'll go through it with a fine
comb and try to find them all.

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

I was hoping that introducing very basics - this tool exists and
you're expected to use it - would lead to developers looking through
the code on their own to learn how. So the omission of more detail on
how to use it is intentional to avoid scope creep.

My thinking, throughout writing this tutorial, was to try to show
developers a glance into what they may need later. So examining a
single commit (but not more); examining a single option (but not
more); exposing the parse library (but not more). I can add a section
but I feel that demonstrating the existence of the tool is enough.

For now, I've replaced "if you like" with "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` 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.

Thanks. I've updated the description.

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

I'll add a new section, unless I hear otherwise before I'm done writing it.

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

I've replaced that claim with a bulleted list:

    Moreover, your patch won't be accepted into the Git tree without tests. Your
    tests should:
    * Illustrate the current behavior of the feature
    * Prove the current behavior matches the expected behavior
    * Ensure the externally-visible behavior isn't broken in later changes

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

Agreed; this was a misunderstanding on my part. In fact, I fixed my
sample code branch, but didn't fix the document.

>
> > +=== Sending a PR to GitGitGadget
> > +
> > +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/

Sure.  By the way, I'll be rolling the section before this about
making a personal fork into the GGG workflow, since below I didn't
mention running Travis with personal fork.
>
> > +== Sending Patches with `git send-email`
> > +
> > +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 ...

Specifically:

- You can't ask for a subject with [RFC PATCH], as demonstrated with
this very review in the previous iteration.
- You can't prepare a dry-run email or send your email to yourself for
a final checkup.

Personally, the latter for me is very scary :) What if GGG mangles my
patchset, which I am nervous to even send to all these smart Git
developers, and they all think it is my fault? Could be I am
projecting, but when I am very new to a project, I try to be very sure
the first review request is perfect.

> > +=== Preparing initial patchset
> > +
> > +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.

Good idea; I'll rework the instructions accordingly.

>
> > +`master..psuh` tells `format-patch` to generate patches for the difference
> > +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.

Sure. I'll rework the whole section.

>
> > +=== Preparing email
> > +
> > +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.

Sure, I'll be sure to mention.

>
> > +----
> > +git send-email \
> > +     --to=target@server.tld \
> > +     --from=me@server.tld \
> > +     --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.
>
> > +
> > +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.
>
> > +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 `git@vger.kernel.org`
> > +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).
>

Thanks for all the tips. I didn't know much about using this tool;
I'll try it out on my own and rework the howto considering your
advice.

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

Good point, especially outside of a GUI review environment like Gerrit
where you can easily diff v1 to v2.
This answers a question I had, too - whether it's rude to reply "Done"
to every nit :) I'll make an effort to be verbose on the list.

I'm going to try to reorganize and make a new section for this,
because the GGG and send-email sections both need mention of review
etiquette - I don't want to only mention it under send-email and be
left with rude GGG users, or vice versa. ;)

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

Deleting this section; stale TODO, as I linked the etiquette mentions
in the Maintainer's Note.

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

Yeah, good suggestion, I've taken it close to verbatim.

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

I'll make mention of it while reworking this entire section.

>
> > +== Now What?
> > +
> > +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.
> > +
> > +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.

You're the one doing it, so I'm guessing you know best what you do
with the patches. :)

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

I will try to rework this section to explain better when you can catch
something before it goes into `next`. This gives me a good opportunity
to mention the "What's Cooking" emails, too.

It seems like you're suggesting to add new patch(es) if a bug is found
when it's already merged to next, so I'll try to explain it that way.


Thanks again for the exhaustive review. I know it's a long patch, and
your comments are very helpful.

Re: [PATCH v2 1/1] documentation: add lab for first contribution

[Junio C Hamano]

Eric Sunshine <sunshine@sunshineco.com> writes:

> On Wed, Apr 17, 2019 at 1:32 AM Junio C Hamano <gitster@pobox.com> wrote:
>> "Emily Shaffer via GitGitGadget" <gitgitgadget@gmail.com> writes:
>> > +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/20180831063318.33373-2-sunshine@sunshineco.com/

Great. Thanks.

[PATCH v3] documentation: add lab for first contribution

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

Signed-off-by: Emily Shaffer <emilyshaffer@google.com>
---
Notable changes in v3:
- Changed document name from MyFirstContribution to
  MyFirstContribution.txt; this reduced the changes to Makefile and
  eliminated changes to .gitignore.
- git send-email section now uses the --cover-letter argument to
  format-patch, and explains single-patch emails
- Reworked summary of engaging in code review, moving to its own section
  "Responding To Reviews"
- "Now What?" section now explains when to make a new commit vs when to
  modify existing commit

Other smaller file-wide changes:
- Expanded use of "doc" ; reworded references to "lab" and "codelab"
- Added $ prompts to bash snippets
- monospaced things that should be but weren't

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

diff --git a/Documentation/Makefile b/Documentation/Makefile
index 26a2342bea..fddc3c3c95 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -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
diff --git a/Documentation/MyFirstContribution.txt b/Documentation/MyFirstContribution.txt
new file mode 100644
index 0000000000..d9bed013fc
--- /dev/null
+++ b/Documentation/MyFirstContribution.txt
@@ -0,0 +1,1065 @@
+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
+----
+
+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
+----
+
+You will be presented with your editor in order to write a 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 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 <author@example.com>
+----
+
+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 verbose 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:
+
+----
+$ make all doc
+$ man Documentation/git-psuh.1
+----
+
+or
+
+----
+$ make -C Documentation/git-psuh.1
+$ 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
+* Prove the current behavior matches the expected behavior
+* Ensure the externally-visible behavior isn't broken in later changes
+
+So let's write some tests.
+
+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-tutorial.sh
+$ chmod +x 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
+----
+
+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
+and `git send-email`.
+
+== Sending Patches via GitGitGadget
+
+One option for sending patches is to follow a typical pull request workflow and
+send your patches out via GitGitGadget. 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. It also runs the Git continuous integration
+suite for you. It's documented at http://gitgitgadget.github.io.
+
+=== Forking git/git on GitHub
+
+Before you can send your patch off to be reviewed using GitGitGadget, you will
+need to fork the Git project and upload your changes. First thing - make sure
+you have a GitHub account.
+
+Head to the https://github.com/git/git[GitHub mirror] and look for the Fork
+button. Place your fork wherever you deem appropriate and create it.
+
+=== Uploading To Your Own Fork
+
+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 git@github.com: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`.
+
+////
+TODO https://github.com/gitgitgadget/gitgitgadget/issues/83
+It'd be nice to be able to verify that the patch looks good before sending it
+to everyone on Git mailing list.
+=== Check Your Work
+////
+
+=== Sending Your Patches
+
+Now that your CI is passing and someone has granted you permission to use
+GitGitGadget with the `/allow` command,  sending out for review is as simple as
+commenting on your PR with `/submit`.
+
+=== Updating With Comments
+
+Skip ahead to <<reviewing,Responding to Reviews>> for information on how to
+reply to review comments you will receive on the mailing list.
+
+Once you have your branch again in the shape you want following all review
+comments, you can submit again:
+
+----
+$ git push -f remotename psuh
+----
+
+Next, go look at your pull request against GitGitGadget; you should see the CI
+has been  kicked off again. Now while the CI is running is a good time for you
+to modify your description at the top of the pull request thread; it will be
+used again as the cover letter. You should use this space to describe what
+has changed since your previous version, so that your reviewers have some idea
+of what they're looking at. When the CI is done running, you can comment once
+more with `/submit` - GitGitGadget will automatically add a v2 mark to your
+changes.
+
+== Sending Patches with `git send-email`
+
+If you don't want to use GitGitGadget, you can also use Git itself to mail your
+patches. Some benefits of using Git this way include finer grained control of
+subject line (for example, being able to use the tag [RFC PATCH] in the subject)
+and being able to send a ``dry run'' mail to yourself to ensure it all looks
+good before going out to the list.
+
+=== Prerequisite: Setting Up `git send-email`
+
+Configuration for `send-email` can vary based on your operating system and email
+provider, and so will not be covered in this tutorial, beyond stating that in
+many distributions of Linux, `git-send-email` is not packaged alongside the
+typical `git` install. You may need to install this additional package; there
+are a number of resources online to help you do so. You will also need to
+determine the right way to configure it to use your SMTP server; again, as this
+configuration can change significantly based on your system and email setup, it
+is out of scope for the context of this tutorial.
+
+=== Preparing initial patchset
+
+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 --cover-letter -o psuh/ master..psuh
+----
+
+The `--cover-letter` parameter tells `format-patch` to create a cover letter
+template for you. You will need to fill in the template before you're ready
+to send - but for now, the template will be next to your other patches.
+
+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.
+
+`master..psuh` tells `format-patch` to generate patches for the difference
+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.
+
+NOTE: Optionally, you can also use the `--rfc` flag to prefix your patch subject
+with ``[RFC PATCH]'' instead of ``[PATCH]''. RFC stands for ``request for
+comments'' and indicates that while your code isn't quite ready for submission,
+you'd like to begin the code review process. This can also be used when your
+patch is a proposal, but you aren't sure whether the community wants to solve
+the problem with that approach or not - to conduct a sort of design review. You
+may also see on the list patches marked ``WIP'' - this means they are incomplete
+but want reviewers to look at what they have so far. You can add this flag with
+`--subject-prefix=WIP`.
+
+Check and make sure that your patches and cover letter template exist in the
+directory you specified - you're nearly ready to send out your review!
+
+=== Preparing email
+
+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). Since you invoked `format-patch`
+with `--cover-letter`, you've already got a template ready. Open it up in your
+favorite editor.
+
+You should see a number of headers present already. Check that your `From:`
+header is correct. Then modify your `Subject:` to something which succinctly
+covers the purpose of your entire topic branch, for example:
+
+----
+Subject: [PATCH 0/7] adding the 'psuh' command
+----
+
+Make sure you retain the ``[PATCH 0/X]'' part; that's what indicates to the Git
+community that this email is the beginning of a review, and many reviewers
+filter their email for this type of flag.
+
+You'll need to add some extra
+parameters when you invoke `git send-email` to add the cover letter.
+
+Next you'll have to fill out the body of your cover letter. This is an important
+component of change submission as it explains to the community from a high level
+what you're trying to do, and why, in a way that's more apparent than just
+looking at your diff. Be sure to explain anything your diff doesn't make clear
+on its own.
+
+Here's an example body for `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 tutorial and should not
+be merged.
+----
+
+The template created by `git format-patch --cover-letter` includes a diffstat.
+This gives reviewers a summary of what they're in for when reviewing your topic.
+The one generated for `psuh` from the sample implementation looks like this:
+
+----
+ Documentation/git-psuh.txt | 40 +++++++++++++++++++++
+ Makefile                   |  1 +
+ builtin.h                  |  1 +
+ builtin/psuh.c             | 73 ++++++++++++++++++++++++++++++++++++++
+ git.c                      |  1 +
+ t/t9999-psuh-tutorial.sh   | 12 +++++++
+ 6 files changed, 128 insertions(+)
+ create mode 100644 Documentation/git-psuh.txt
+ create mode 100644 builtin/psuh.c
+ create mode 100755 t/t9999-psuh-tutorial.sh
+----
+
+Finally, the letter will include the version of Git used to generate the
+patches. You can leave that string alone.
+
+=== Sending email
+
+At this point you should have a directory `psuh/` which is filled with your
+patches and a cover letter. Time to mail it out! You can send it like this:
+
+----
+$ git send-email --to=target@example.com
+----
+
+NOTE: Check `git help send-email` for some other options which you may find
+valuable, such as changing the Reply-to address or adding more CC and BCC lines.
+
+NOTE: When you are sending a real patch, it will go to git@vger.kernel.org - but
+please don't send your patchset from the tutorial to the real mailing list! For
+now, you can send it to yourself, to make sure you understand how it will look.
+
+After you run the command above, 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 be sent! Congratulations!
+
+Awesome, now the community will drop everything and review your changes. (Just
+kidding - be patient!)
+
+=== Sending v2
+
+Skip ahead to <<reviewing,Responding to Reviews>> for information on how to
+handle comments from reviewers. Continue this section when your topic branch is
+shaped the way you want it to look for your patchset v2.
+
+When you're ready with the next iteration of your patch, the process is fairly
+similar.
+
+First, generate your v2 patches again:
+
+----
+$ git format-patch -v2 --cover-letter -o psuh/ master..psuh
+----
+
+This will add your v2 patches, all named like `v2-000n-my-commit-subject.patch`,
+to the `psuh/` directory. You may notice that they are sitting alongside the v1
+patches; that's fine, but be careful when you are ready to send them.
+
+Edit your cover letter again. Now is a good time to mention what's different
+between your last version and now, if it's something significant. You do not
+need the exact same body in your second cover letter; focus on explaining to
+reviewers the changes you've made that may not be as visible.
+
+You will also need to go and find the Message-Id of your previous cover letter.
+You can either note it when you send the first series, from the output of `git
+send-email`, or you can look it up on the
+https://public-inbox.org/git[mailing list]. Find your cover letter in the
+archives, click on it, and check the URL. It should match:
+
+----
+https://public-inbox.org/git/foo.12345.author@example.com/other/junk
+----
+
+Your Message-Id is `foo.12345.author@example.com`. This example will be used
+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 --to=target@example.com
+		 --in-reply-to=foo.12345.author@example.com
+----
+
+=== 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
+`---` in your patch. Take the example below, generated with `git format-patch`
+on a single commit:
+
+----
+From 1345bbb3f7ac74abde040c12e737204689a72723 Mon Sep 17 00:00:00 2001
+From: A U Thor <author@example.com>
+Date: Thu, 18 Apr 2019 15:11:02 -0700
+Subject: [PATCH] README: change the grammar
+
+I think it looks better this way. This part of the commit message will
+end up in the commit-log.
+
+Signed-off-by: A U Thor <author@example.com>
+---
+Let's have a wild discussion about grammar on the mailing list. This
+part of my email will never end up in the commit log. Here is where I
+can add additional context to the mailing list about my intent, outside
+of the context of the commit log.
+
+ README.md | 2 +-
+ 1 file changed, 1 insertion(+), 1 deletion(-)
+
+diff --git a/README.md b/README.md
+index 88f126184c..38da593a60 100644
+--- a/README.md
++++ b/README.md
+@@ -3,7 +3,7 @@
+ Git - fast, scalable, distributed revision control system
+ =========================================================
+ 
+-Git is a fast, scalable, distributed revision control system with an
++Git is a fast, scalable, and distributed revision control system with an
+ unusually rich command set that provides both high-level operations
+ and full access to internals.
+ 
+-- 
+2.21.0.392.gf8f6787159e-goog
+----
+
+== My Patch Got Emailed - Now What?
+
+[[reviewing]]
+=== Responding to Reviews
+
+After a few days, you will hopefully receive a reply to your patchset with some
+comments. Woohoo! Now you can get back to work.
+
+It's good manners to reply to each comment, notifying the reviewer that you have
+made the change requested, feel the original is better, or that the comment
+inspired you to do something a new way which is superior to both the original
+and the suggested change. This way reviewers don't need to inspect your v2 to
+figure out whether you implemented their comment or not.
+
+If you are going to push back on a comment, be polite and explain why you feel
+your original is better; be prepared that the reviewer may still disagree with
+you, and the rest of the community may weigh in on one side or the other. As
+with all code reviews, it's important to keep an open mind to doing something a
+different way than you originally planned; other reviewers have a different
+perspective on the project than you do, and may be thinking of a valid side
+effect which had not occurred to you. It is always okay to ask for clarification
+if you aren't sure why a change was suggested, or what the reviewer is asking
+you to do.
+
+Make sure your email client has a plaintext email mode and it is turned on; 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.
+
+When you're making changes to your code, it is cleanest - that is, the resulting
+commits are easiest to look at - if you use `git rebase -i` (interactive
+rebase). Take a look at this
+https://www.oreilly.com/library/view/git-pocket-guide/9781449327507/ch10.html[overview]
+from O'Reilly. The general idea is to modify each commit which requires changes;
+this way, instead of having a patch A with a mistake, a patch B which was fine
+and required no upstream reviews in v1, and a patch C which fixes patch A for
+v2, you can just ship a v2 with a correct patch A and correct patch B. This is
+changing history, but since it's local history which you haven't shared with
+anyone, that is okay for now! (Later, it may not make sense to do this; take a
+look at the section below this one for some context.)
+
+=== After Review Approval
+
+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.
+
+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 merge your topic branch to `next` and life is good.
+
+However, if you discover it isn't so perfect after this point, you may need to
+take some special steps depending on where you are in the process.
+
+If the maintainer has announced in the "What's cooking in git.git" email that
+your topic is marked for `next` - that is, that they plan to merge it to `next`
+but have not yet done so - you should send an email asking the maintainer to
+wait a little longer: "I've sent v4 of my series and you marked it for `next`,
+but I need to change this and that - please wait for v5 before you merge it."
+
+If the topic has already been merged to `next`, rather than modifying your
+patches with `git rebase -i`, you should make further changes incrementally -
+that is, with another commit, based on top of of the maintainer's topic branch
+as detailed in https://github.com/gitster/git. Your work is still in the same
+topic but is now incremental, rather than a wholesale rewrite of the topic
+branch.
+
+The topic branches in the maintainer's GitHub are mirrored in GitGitGadget, so
+if you're sending your reviews out that way, you should be sure to open your PR
+against the appropriate GitGitGadget/Git branch.
+
+If you're using `git
+send-email`, you can use it the same way as before, but you should generate your
+diffs from `<topic>..<mybranch>` and base your work on `<topic>` instead of
+`master`.
-- 
2.21.0.392.gf8f6787159e-goog

Re: [PATCH v3] documentation: add lab for first contribution

[Junio C Hamano]

Emily Shaffer <emilyshaffer@google.com> writes:

> 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 <emilyshaffer@google.com>
> ---

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.

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

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

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

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

> +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?".

Nicely written.

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

> +----
> +
> +`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 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|;

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

> +https://public-inbox.org/git/foo.12345.author@example.com/other/junk
> +----
> +
> +Your Message-Id is `foo.12345.author@example.com`. This example will be used

Technically, <foo.12345.author@example.com> 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.

> +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 --to=target@example.com
> +		 --in-reply-to=foo.12345.author@example.com
> +----
> +
> +=== 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?

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

Re: [PATCH v3] documentation: add lab for first contribution

[Emily Shaffer]

On Sun, Apr 21, 2019 at 3:52 AM Junio C Hamano <gitster@pobox.com> wrote:
>
> Emily Shaffer <emilyshaffer@google.com> writes:
>
> > 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 <emilyshaffer@google.com>
> > ---
>
> 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.

Thanks, finished.

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

I appreciate the thorough reviews you gave til now, thanks very much
for all your time.

>
> > +- `Documentation/SubmittingPatches`
> > +- `Documentation/howto/new-command.txt`
>
> Good (relative to the earlier one, these are set in monospace).
>
> > +
> > +== 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?

This breaks the hyperlink. So I'd rather not?

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

Thanks, good catch.

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

Took this suggestion.

>
> Or just get rid of braces if you are not going to extend one (or
> both) of if/else blocks into multi-statement blocks.
>
> > +----
> > +
> > +`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 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|;

Thanks, done. I'll leave out repeating the lecture here as it was
given in the full sample commit.

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

Looking back, I'm wondering why I wrote it this way - I think I wanted
to avoid prescribing an editor and also mention the permissions.

I'll try to reword this to mention the executable bit after the
content of the test script.

>
> > +https://public-inbox.org/git/foo.12345.author@example.com/other/junk
> > +----
> > +
> > +Your Message-Id is `foo.12345.author@example.com`. This example will be used
>
> Technically, <foo.12345.author@example.com> 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.

I've since reworded this section to mention reading the Message-Id
from the permalinked email in public-inbox. I think it might be easier
than spying on the URL as the URL is different in some views and
doesn't reflect the Message-Id.

>
> > +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 --to=target@example.com
> > +              --in-reply-to=foo.12345.author@example.com
> > +----

Since I made a meaningful change in this section anyways, I've fixed
this to include the angle brackets.

> > +
> > +=== 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?
>
> > +`---` in your patch. Take the example below, generated with `git format-patch`
> > +on a single commit:

Thanks again. I'll send v4 later today or tomorrow to give more time
for comments if anybody else is planning to look.


-- 
Emily Shaffer

[PATCH v4] documentation: add tutorial for first contribution

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

Signed-off-by: Emily Shaffer <emilyshaffer@google.com>
---
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

diff --git a/Documentation/Makefile b/Documentation/Makefile
index 26a2342bea..fddc3c3c95 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -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
diff --git a/Documentation/MyFirstContribution.txt b/Documentation/MyFirstContribution.txt
new file mode 100644
index 0000000000..fc4a59a8c6
--- /dev/null
+++ b/Documentation/MyFirstContribution.txt
@@ -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
+----
+
+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
+----
+
+You will be presented with your editor in order to write a 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 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 <author@example.com>
+----
+
+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:
+
+----
+$ make all doc
+$ man Documentation/git-psuh.1
+----
+
+or
+
+----
+$ make -C Documentation/git-psuh.1
+$ 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
+* Prove the current behavior matches the expected behavior
+* Ensure the externally-visible behavior isn't broken in later changes
+
+So let's write some tests.
+
+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 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
+and `git send-email`.
+
+== Sending Patches via GitGitGadget
+
+One option for sending patches is to follow a typical pull request workflow and
+send your patches out via GitGitGadget. 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. It also runs the Git continuous integration
+suite for you. It's documented at http://gitgitgadget.github.io.
+
+=== Forking git/git on GitHub
+
+Before you can send your patch off to be reviewed using GitGitGadget, you will
+need to fork the Git project and upload your changes. First thing - make sure
+you have a GitHub account.
+
+Head to the https://github.com/git/git[GitHub mirror] and look for the Fork
+button. Place your fork wherever you deem appropriate and create it.
+
+=== Uploading To Your Own Fork
+
+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 git@github.com: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`.
+
+////
+TODO https://github.com/gitgitgadget/gitgitgadget/issues/83
+It'd be nice to be able to verify that the patch looks good before sending it
+to everyone on Git mailing list.
+=== Check Your Work
+////
+
+=== Sending Your Patches
+
+Now that your CI is passing and someone has granted you permission to use
+GitGitGadget with the `/allow` command,  sending out for review is as simple as
+commenting on your PR with `/submit`.
+
+=== Updating With Comments
+
+Skip ahead to <<reviewing,Responding to Reviews>> for information on how to
+reply to review comments you will receive on the mailing list.
+
+Once you have your branch again in the shape you want following all review
+comments, you can submit again:
+
+----
+$ git push -f remotename psuh
+----
+
+Next, go look at your pull request against GitGitGadget; you should see the CI
+has been  kicked off again. Now while the CI is running is a good time for you
+to modify your description at the top of the pull request thread; it will be
+used again as the cover letter. You should use this space to describe what
+has changed since your previous version, so that your reviewers have some idea
+of what they're looking at. When the CI is done running, you can comment once
+more with `/submit` - GitGitGadget will automatically add a v2 mark to your
+changes.
+
+== Sending Patches with `git send-email`
+
+If you don't want to use GitGitGadget, you can also use Git itself to mail your
+patches. Some benefits of using Git this way include finer grained control of
+subject line (for example, being able to use the tag [RFC PATCH] in the subject)
+and being able to send a ``dry run'' mail to yourself to ensure it all looks
+good before going out to the list.
+
+=== Prerequisite: Setting Up `git send-email`
+
+Configuration for `send-email` can vary based on your operating system and email
+provider, and so will not be covered in this tutorial, beyond stating that in
+many distributions of Linux, `git-send-email` is not packaged alongside the
+typical `git` install. You may need to install this additional package; there
+are a number of resources online to help you do so. You will also need to
+determine the right way to configure it to use your SMTP server; again, as this
+configuration can change significantly based on your system and email setup, it
+is out of scope for the context of this tutorial.
+
+=== Preparing initial patchset
+
+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 --cover-letter -o psuh/ master..psuh
+----
+
+The `--cover-letter` parameter tells `format-patch` to create a cover letter
+template for you. You will need to fill in the template before you're ready
+to send - but for now, the template will be next to your other patches.
+
+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.
+
+`master..psuh` tells `format-patch` to generate patches for the difference
+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.
+
+NOTE: Optionally, you can also use the `--rfc` flag to prefix your patch subject
+with ``[RFC PATCH]'' instead of ``[PATCH]''. RFC stands for ``request for
+comments'' and indicates that while your code isn't quite ready for submission,
+you'd like to begin the code review process. This can also be used when your
+patch is a proposal, but you aren't sure whether the community wants to solve
+the problem with that approach or not - to conduct a sort of design review. You
+may also see on the list patches marked ``WIP'' - this means they are incomplete
+but want reviewers to look at what they have so far. You can add this flag with
+`--subject-prefix=WIP`.
+
+Check and make sure that your patches and cover letter template exist in the
+directory you specified - you're nearly ready to send out your review!
+
+=== Preparing email
+
+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). Since you invoked `format-patch`
+with `--cover-letter`, you've already got a template ready. Open it up in your
+favorite editor.
+
+You should see a number of headers present already. Check that your `From:`
+header is correct. Then modify your `Subject:` to something which succinctly
+covers the purpose of your entire topic branch, for example:
+
+----
+Subject: [PATCH 0/7] adding the 'psuh' command
+----
+
+Make sure you retain the ``[PATCH 0/X]'' part; that's what indicates to the Git
+community that this email is the beginning of a review, and many reviewers
+filter their email for this type of flag.
+
+You'll need to add some extra
+parameters when you invoke `git send-email` to add the cover letter.
+
+Next you'll have to fill out the body of your cover letter. This is an important
+component of change submission as it explains to the community from a high level
+what you're trying to do, and why, in a way that's more apparent than just
+looking at your diff. Be sure to explain anything your diff doesn't make clear
+on its own.
+
+Here's an example body for `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 tutorial and should not
+be merged.
+----
+
+The template created by `git format-patch --cover-letter` includes a diffstat.
+This gives reviewers a summary of what they're in for when reviewing your topic.
+The one generated for `psuh` from the sample implementation looks like this:
+
+----
+ Documentation/git-psuh.txt | 40 +++++++++++++++++++++
+ Makefile                   |  1 +
+ builtin.h                  |  1 +
+ builtin/psuh.c             | 73 ++++++++++++++++++++++++++++++++++++++
+ git.c                      |  1 +
+ t/t9999-psuh-tutorial.sh   | 12 +++++++
+ 6 files changed, 128 insertions(+)
+ create mode 100644 Documentation/git-psuh.txt
+ create mode 100644 builtin/psuh.c
+ create mode 100755 t/t9999-psuh-tutorial.sh
+----
+
+Finally, the letter will include the version of Git used to generate the
+patches. You can leave that string alone.
+
+=== Sending email
+
+At this point you should have a directory `psuh/` which is filled with your
+patches and a cover letter. Time to mail it out! You can send it like this:
+
+----
+$ git send-email --to=target@example.com
+----
+
+NOTE: Check `git help send-email` for some other options which you may find
+valuable, such as changing the Reply-to address or adding more CC and BCC lines.
+
+NOTE: When you are sending a real patch, it will go to git@vger.kernel.org - but
+please don't send your patchset from the tutorial to the real mailing list! For
+now, you can send it to yourself, to make sure you understand how it will look.
+
+After you run the command above, 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 be sent! Congratulations!
+
+Awesome, now the community will drop everything and review your changes. (Just
+kidding - be patient!)
+
+=== Sending v2
+
+Skip ahead to <<reviewing,Responding to Reviews>> for information on how to
+handle comments from reviewers. Continue this section when your topic branch is
+shaped the way you want it to look for your patchset v2.
+
+When you're ready with the next iteration of your patch, the process is fairly
+similar.
+
+First, generate your v2 patches again:
+
+----
+$ git format-patch -v2 --cover-letter -o psuh/ master..psuh
+----
+
+This will add your v2 patches, all named like `v2-000n-my-commit-subject.patch`,
+to the `psuh/` directory. You may notice that they are sitting alongside the v1
+patches; that's fine, but be careful when you are ready to send them.
+
+Edit your cover letter again. Now is a good time to mention what's different
+between your last version and now, if it's something significant. You do not
+need the exact same body in your second cover letter; focus on explaining to
+reviewers the changes you've made that may not be as visible.
+
+You will also need to go and find the Message-Id of your previous cover letter.
+You can either note it when you send the first series, from the output of `git
+send-email`, or you can look it up on the
+https://public-inbox.org/git[mailing list]. Find your cover letter in the
+archives, click on it, then click "permalink" or "raw" to reveal the Message-Id
+header. It should match:
+
+----
+Message-Id: <foo.12345.author@example.com>
+----
+
+Your Message-Id is `<foo.12345.author@example.com>`. This example will be used
+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.
+
+While you're looking at the email, you should also note who is CC'd, as it's
+common practice in the mailing list to keep all CCs on a thread. You can add
+these CC lines directly to your cover letter with a line like so in the header
+(before the Subject line):
+
+----
+CC: author@example.com, Othe R <other@example.com>
+----
+
+Now send the emails again, paying close attention to which messages you pass in
+to the command:
+
+----
+$ git send-email --to=target@example.com
+		 --in-reply-to=<foo.12345.author@example.com>
+----
+
+=== 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
+meaningful and explain the at a high level the purpose (what is happening and
+why) of your patch, but if you need to supply even more context, you can do so
+below the `---` in your patch. Take the example below, generated with
+`git format-patch` on a single commit:
+
+----
+From 1345bbb3f7ac74abde040c12e737204689a72723 Mon Sep 17 00:00:00 2001
+From: A U Thor <author@example.com>
+Date: Thu, 18 Apr 2019 15:11:02 -0700
+Subject: [PATCH] README: change the grammar
+
+I think it looks better this way. This part of the commit message will
+end up in the commit-log.
+
+Signed-off-by: A U Thor <author@example.com>
+---
+Let's have a wild discussion about grammar on the mailing list. This
+part of my email will never end up in the commit log. Here is where I
+can add additional context to the mailing list about my intent, outside
+of the context of the commit log.
+
+ README.md | 2 +-
+ 1 file changed, 1 insertion(+), 1 deletion(-)
+
+diff --git a/README.md b/README.md
+index 88f126184c..38da593a60 100644
+--- a/README.md
++++ b/README.md
+@@ -3,7 +3,7 @@
+ Git - fast, scalable, distributed revision control system
+ =========================================================
+
+-Git is a fast, scalable, distributed revision control system with an
++Git is a fast, scalable, and distributed revision control system with an
+ unusually rich command set that provides both high-level operations
+ and full access to internals.
+
+--
+2.21.0.392.gf8f6787159e-goog
+----
+
+== My Patch Got Emailed - Now What?
+
+[[reviewing]]
+=== Responding to Reviews
+
+After a few days, you will hopefully receive a reply to your patchset with some
+comments. Woohoo! Now you can get back to work.
+
+It's good manners to reply to each comment, notifying the reviewer that you have
+made the change requested, feel the original is better, or that the comment
+inspired you to do something a new way which is superior to both the original
+and the suggested change. This way reviewers don't need to inspect your v2 to
+figure out whether you implemented their comment or not.
+
+If you are going to push back on a comment, be polite and explain why you feel
+your original is better; be prepared that the reviewer may still disagree with
+you, and the rest of the community may weigh in on one side or the other. As
+with all code reviews, it's important to keep an open mind to doing something a
+different way than you originally planned; other reviewers have a different
+perspective on the project than you do, and may be thinking of a valid side
+effect which had not occurred to you. It is always okay to ask for clarification
+if you aren't sure why a change was suggested, or what the reviewer is asking
+you to do.
+
+Make sure your email client has a plaintext email mode and it is turned on; 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.
+
+When you're making changes to your code, it is cleanest - that is, the resulting
+commits are easiest to look at - if you use `git rebase -i` (interactive
+rebase). Take a look at this
+https://www.oreilly.com/library/view/git-pocket-guide/9781449327507/ch10.html[overview]
+from O'Reilly. The general idea is to modify each commit which requires changes;
+this way, instead of having a patch A with a mistake, a patch B which was fine
+and required no upstream reviews in v1, and a patch C which fixes patch A for
+v2, you can just ship a v2 with a correct patch A and correct patch B. This is
+changing history, but since it's local history which you haven't shared with
+anyone, that is okay for now! (Later, it may not make sense to do this; take a
+look at the section below this one for some context.)
+
+=== After Review Approval
+
+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.
+
+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 merge your topic branch to `next` and life is good.
+
+However, if you discover it isn't so perfect after this point, you may need to
+take some special steps depending on where you are in the process.
+
+If the maintainer has announced in the "What's cooking in git.git" email that
+your topic is marked for `next` - that is, that they plan to merge it to `next`
+but have not yet done so - you should send an email asking the maintainer to
+wait a little longer: "I've sent v4 of my series and you marked it for `next`,
+but I need to change this and that - please wait for v5 before you merge it."
+
+If the topic has already been merged to `next`, rather than modifying your
+patches with `git rebase -i`, you should make further changes incrementally -
+that is, with another commit, based on top of of the maintainer's topic branch
+as detailed in https://github.com/gitster/git. Your work is still in the same
+topic but is now incremental, rather than a wholesale rewrite of the topic
+branch.
+
+The topic branches in the maintainer's GitHub are mirrored in GitGitGadget, so
+if you're sending your reviews out that way, you should be sure to open your PR
+against the appropriate GitGitGadget/Git branch.
+
+If you're using `git
+send-email`, you can use it the same way as before, but you should generate your
+diffs from `<topic>..<mybranch>` and base your work on `<topic>` instead of
+`master`.
-- 
2.21.0.593.g511ec345e18-goog

Re: [PATCH v4] documentation: add tutorial for first contribution

[Josh Steadmon]

Just a couple typo fixes listed below:


On 2019.04.23 12:34, Emily Shaffer wrote:
[snip]
> +=== 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

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


[snip]
> +=== 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:
> +
> +----
> +$ make all doc
> +$ man Documentation/git-psuh.1
> +----
> +
> +or
> +
> +----
> +$ make -C Documentation/git-psuh.1

Needs a space after "Documentation/".

Re: [PATCH v4] documentation: add tutorial for first contribution

[Emily Shaffer]

On Tue, Apr 30, 2019 at 11:59:23AM -0700, Josh Steadmon wrote:
> Just a couple typo fixes listed below:
> 

Thanks for the review, Josh.

I'll hold these fixes locally until I either get something more
significant to fix or Junio asks for them before a merge to next, to
reduce spam to the list.

- Emily
> 
> On 2019.04.23 12:34, Emily Shaffer wrote:
> [snip]
> > +=== 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
> 
> Looks like you have an errant "/" after "git".

Right you are. Thanks.
> 
> 
> [snip]
> > +=== 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:
> > +
> > +----
> > +$ make all doc
> > +$ man Documentation/git-psuh.1
> > +----
> > +
> > +or
> > +
> > +----
> > +$ make -C Documentation/git-psuh.1
> 
> Needs a space after "Documentation/".

Done. Thanks much.

Re: [PATCH v4] documentation: add tutorial for first contribution

[Phil Hord]

On Tue, Apr 23, 2019 at 12:35 PM Emily Shaffer <emilyshaffer@google.com> wrote:
>
> 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.
>

Thanks for working on this.  It's very nicely done.

> Signed-off-by: Emily Shaffer <emilyshaffer@google.com>
> ---
> 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
>
> diff --git a/Documentation/Makefile b/Documentation/Makefile
> index 26a2342bea..fddc3c3c95 100644
> --- a/Documentation/Makefile
> +++ b/Documentation/Makefile
> @@ -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
> diff --git a/Documentation/MyFirstContribution.txt b/Documentation/MyFirstContribution.txt
> new file mode 100644
> index 0000000000..fc4a59a8c6
> --- /dev/null
> +++ b/Documentation/MyFirstContribution.txt
> @@ -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
> +----
> +
> +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
> +----
> +
> +You will be presented with your editor in order to write a 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

This part sounds a little ambiguous to me, as I'm expected to include
the "Why" in my 50-column subject line.  I don't want to go overboard,
but maybe direct them further to

    After this, insert a blank line (always required) and then some
text describing
    your change.  Remember to be explicit and ...

> +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 <author@example.com>
> +----
> +
> +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:
> +
> +----
> +$ make all doc
> +$ man Documentation/git-psuh.1
> +----
> +
> +or
> +
> +----
> +$ make -C Documentation/git-psuh.1

There's an unwanted slash here. This should be `make -C Documentation
git-psuh.1`.

> +$ 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
> +* Prove the current behavior matches the expected behavior
> +* Ensure the externally-visible behavior isn't broken in later changes
> +
> +So let's write some tests.
> +
> +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

This doesn't parse.  How about this?

    named with a 4-decimal digit number using the schema shown in ...

> +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
> +and `git send-email`.
> +
> +== Sending Patches via GitGitGadget
> +
> +One option for sending patches is to follow a typical pull request workflow and
> +send your patches out via GitGitGadget. 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. It also runs the Git continuous integration

nit: "send" them out for you.

> +suite for you. It's documented at http://gitgitgadget.github.io.
> +
> +=== Forking git/git on GitHub
> +
> +Before you can send your patch off to be reviewed using GitGitGadget, you will
> +need to fork the Git project and upload your changes. First thing - make sure
> +you have a GitHub account.
> +
> +Head to the https://github.com/git/git[GitHub mirror] and look for the Fork
> +button. Place your fork wherever you deem appropriate and create it.
> +
> +=== Uploading To Your Own Fork

I noticed some of your titles Use Capital Initials and others do not.
I suppose either is fine, but consistency is appreciated.

> +
> +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 git@github.com: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`.
> +
> +////
> +TODO https://github.com/gitgitgadget/gitgitgadget/issues/83
> +It'd be nice to be able to verify that the patch looks good before sending it
> +to everyone on Git mailing list.
> +=== Check Your Work
> +////
> +
> +=== Sending Your Patches
> +
> +Now that your CI is passing and someone has granted you permission to use
> +GitGitGadget with the `/allow` command,  sending out for review is as simple as

nit: extra space before "sending"

> +commenting on your PR with `/submit`.
> +
> +=== Updating With Comments
> +
> +Skip ahead to <<reviewing,Responding to Reviews>> for information on how to
> +reply to review comments you will receive on the mailing list.
> +
> +Once you have your branch again in the shape you want following all review
> +comments, you can submit again:
> +
> +----
> +$ git push -f remotename psuh
> +----
> +
> +Next, go look at your pull request against GitGitGadget; you should see the CI
> +has been  kicked off again. Now while the CI is running is a good time for you

nit: extra spaces before "kicked"

> +to modify your description at the top of the pull request thread; it will be
> +used again as the cover letter. You should use this space to describe what
> +has changed since your previous version, so that your reviewers have some idea
> +of what they're looking at. When the CI is done running, you can comment once
> +more with `/submit` - GitGitGadget will automatically add a v2 mark to your
> +changes.
> +
> +== Sending Patches with `git send-email`
> +
> +If you don't want to use GitGitGadget, you can also use Git itself to mail your
> +patches. Some benefits of using Git this way include finer grained control of
> +subject line (for example, being able to use the tag [RFC PATCH] in the subject)
> +and being able to send a ``dry run'' mail to yourself to ensure it all looks
> +good before going out to the list.
> +
> +=== Prerequisite: Setting Up `git send-email`
> +
> +Configuration for `send-email` can vary based on your operating system and email
> +provider, and so will not be covered in this tutorial, beyond stating that in
> +many distributions of Linux, `git-send-email` is not packaged alongside the
> +typical `git` install. You may need to install this additional package; there
> +are a number of resources online to help you do so. You will also need to
> +determine the right way to configure it to use your SMTP server; again, as this
> +configuration can change significantly based on your system and email setup, it
> +is out of scope for the context of this tutorial.
> +
> +=== Preparing initial patchset
> +
> +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 --cover-letter -o psuh/ master..psuh
> +----
> +
> +The `--cover-letter` parameter tells `format-patch` to create a cover letter
> +template for you. You will need to fill in the template before you're ready
> +to send - but for now, the template will be next to your other patches.
> +
> +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.
> +
> +`master..psuh` tells `format-patch` to generate patches for the difference
> +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.
> +
> +NOTE: Optionally, you can also use the `--rfc` flag to prefix your patch subject
> +with ``[RFC PATCH]'' instead of ``[PATCH]''. RFC stands for ``request for
> +comments'' and indicates that while your code isn't quite ready for submission,
> +you'd like to begin the code review process. This can also be used when your
> +patch is a proposal, but you aren't sure whether the community wants to solve
> +the problem with that approach or not - to conduct a sort of design review. You
> +may also see on the list patches marked ``WIP'' - this means they are incomplete
> +but want reviewers to look at what they have so far. You can add this flag with
> +`--subject-prefix=WIP`.
> +
> +Check and make sure that your patches and cover letter template exist in the
> +directory you specified - you're nearly ready to send out your review!
> +
> +=== Preparing email
> +
> +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). Since you invoked `format-patch`
> +with `--cover-letter`, you've already got a template ready. Open it up in your
> +favorite editor.
> +
> +You should see a number of headers present already. Check that your `From:`
> +header is correct. Then modify your `Subject:` to something which succinctly
> +covers the purpose of your entire topic branch, for example:
> +
> +----
> +Subject: [PATCH 0/7] adding the 'psuh' command
> +----
> +
> +Make sure you retain the ``[PATCH 0/X]'' part; that's what indicates to the Git
> +community that this email is the beginning of a review, and many reviewers
> +filter their email for this type of flag.
> +
> +You'll need to add some extra

Early line break on this line.

> +parameters when you invoke `git send-email` to add the cover letter.
> +
> +Next you'll have to fill out the body of your cover letter. This is an important
> +component of change submission as it explains to the community from a high level
> +what you're trying to do, and why, in a way that's more apparent than just
> +looking at your diff. Be sure to explain anything your diff doesn't make clear
> +on its own.
> +
> +Here's an example body for `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 tutorial and should not
> +be merged.
> +----
> +
> +The template created by `git format-patch --cover-letter` includes a diffstat.
> +This gives reviewers a summary of what they're in for when reviewing your topic.
> +The one generated for `psuh` from the sample implementation looks like this:
> +
> +----
> + Documentation/git-psuh.txt | 40 +++++++++++++++++++++
> + Makefile                   |  1 +
> + builtin.h                  |  1 +
> + builtin/psuh.c             | 73 ++++++++++++++++++++++++++++++++++++++
> + git.c                      |  1 +
> + t/t9999-psuh-tutorial.sh   | 12 +++++++
> + 6 files changed, 128 insertions(+)
> + create mode 100644 Documentation/git-psuh.txt
> + create mode 100644 builtin/psuh.c
> + create mode 100755 t/t9999-psuh-tutorial.sh
> +----
> +
> +Finally, the letter will include the version of Git used to generate the
> +patches. You can leave that string alone.
> +
> +=== Sending email
> +
> +At this point you should have a directory `psuh/` which is filled with your
> +patches and a cover letter. Time to mail it out! You can send it like this:
> +
> +----
> +$ git send-email --to=target@example.com
> +----
> +
> +NOTE: Check `git help send-email` for some other options which you may find
> +valuable, such as changing the Reply-to address or adding more CC and BCC lines.
> +
> +NOTE: When you are sending a real patch, it will go to git@vger.kernel.org - but
> +please don't send your patchset from the tutorial to the real mailing list! For
> +now, you can send it to yourself, to make sure you understand how it will look.
> +
> +After you run the command above, 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 be sent! Congratulations!
> +
> +Awesome, now the community will drop everything and review your changes. (Just
> +kidding - be patient!)
> +
> +=== Sending v2
> +
> +Skip ahead to <<reviewing,Responding to Reviews>> for information on how to
> +handle comments from reviewers. Continue this section when your topic branch is
> +shaped the way you want it to look for your patchset v2.
> +
> +When you're ready with the next iteration of your patch, the process is fairly
> +similar.
> +
> +First, generate your v2 patches again:
> +
> +----
> +$ git format-patch -v2 --cover-letter -o psuh/ master..psuh
> +----
> +
> +This will add your v2 patches, all named like `v2-000n-my-commit-subject.patch`,
> +to the `psuh/` directory. You may notice that they are sitting alongside the v1
> +patches; that's fine, but be careful when you are ready to send them.
> +
> +Edit your cover letter again. Now is a good time to mention what's different
> +between your last version and now, if it's something significant. You do not
> +need the exact same body in your second cover letter; focus on explaining to
> +reviewers the changes you've made that may not be as visible.
> +
> +You will also need to go and find the Message-Id of your previous cover letter.
> +You can either note it when you send the first series, from the output of `git
> +send-email`, or you can look it up on the
> +https://public-inbox.org/git[mailing list]. Find your cover letter in the
> +archives, click on it, then click "permalink" or "raw" to reveal the Message-Id
> +header. It should match:
> +
> +----
> +Message-Id: <foo.12345.author@example.com>
> +----
> +
> +Your Message-Id is `<foo.12345.author@example.com>`. This example will be used
> +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.
> +
> +While you're looking at the email, you should also note who is CC'd, as it's
> +common practice in the mailing list to keep all CCs on a thread. You can add
> +these CC lines directly to your cover letter with a line like so in the header
> +(before the Subject line):
> +
> +----
> +CC: author@example.com, Othe R <other@example.com>
> +----
> +
> +Now send the emails again, paying close attention to which messages you pass in
> +to the command:
> +
> +----
> +$ git send-email --to=target@example.com
> +                --in-reply-to=<foo.12345.author@example.com>

You probably need quotes around this message-id argument to avoid the
shell interpreting it as redirection.

> +----
> +
> +=== 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
> +meaningful and explain the at a high level the purpose (what is happening and

typo: "explain at a high level"

> +why) of your patch, but if you need to supply even more context, you can do so
> +below the `---` in your patch. Take the example below, generated with
> +`git format-patch` on a single commit:
> +
> +----
> +From 1345bbb3f7ac74abde040c12e737204689a72723 Mon Sep 17 00:00:00 2001
> +From: A U Thor <author@example.com>
> +Date: Thu, 18 Apr 2019 15:11:02 -0700
> +Subject: [PATCH] README: change the grammar
> +
> +I think it looks better this way. This part of the commit message will
> +end up in the commit-log.
> +
> +Signed-off-by: A U Thor <author@example.com>
> +---
> +Let's have a wild discussion about grammar on the mailing list. This
> +part of my email will never end up in the commit log. Here is where I
> +can add additional context to the mailing list about my intent, outside
> +of the context of the commit log.
> +
> + README.md | 2 +-
> + 1 file changed, 1 insertion(+), 1 deletion(-)
> +
> +diff --git a/README.md b/README.md
> +index 88f126184c..38da593a60 100644
> +--- a/README.md
> ++++ b/README.md
> +@@ -3,7 +3,7 @@
> + Git - fast, scalable, distributed revision control system
> + =========================================================
> +
> +-Git is a fast, scalable, distributed revision control system with an
> ++Git is a fast, scalable, and distributed revision control system with an
> + unusually rich command set that provides both high-level operations
> + and full access to internals.
> +
> +--
> +2.21.0.392.gf8f6787159e-goog
> +----
> +
> +== My Patch Got Emailed - Now What?
> +
> +[[reviewing]]
> +=== Responding to Reviews
> +
> +After a few days, you will hopefully receive a reply to your patchset with some
> +comments. Woohoo! Now you can get back to work.
> +
> +It's good manners to reply to each comment, notifying the reviewer that you have
> +made the change requested, feel the original is better, or that the comment
> +inspired you to do something a new way which is superior to both the original
> +and the suggested change. This way reviewers don't need to inspect your v2 to
> +figure out whether you implemented their comment or not.
> +
> +If you are going to push back on a comment, be polite and explain why you feel
> +your original is better; be prepared that the reviewer may still disagree with
> +you, and the rest of the community may weigh in on one side or the other. As
> +with all code reviews, it's important to keep an open mind to doing something a
> +different way than you originally planned; other reviewers have a different
> +perspective on the project than you do, and may be thinking of a valid side
> +effect which had not occurred to you. It is always okay to ask for clarification
> +if you aren't sure why a change was suggested, or what the reviewer is asking
> +you to do.
> +
> +Make sure your email client has a plaintext email mode and it is turned on; 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.
> +
> +When you're making changes to your code, it is cleanest - that is, the resulting
> +commits are easiest to look at - if you use `git rebase -i` (interactive
> +rebase). Take a look at this
> +https://www.oreilly.com/library/view/git-pocket-guide/9781449327507/ch10.html[overview]
> +from O'Reilly. The general idea is to modify each commit which requires changes;
> +this way, instead of having a patch A with a mistake, a patch B which was fine
> +and required no upstream reviews in v1, and a patch C which fixes patch A for
> +v2, you can just ship a v2 with a correct patch A and correct patch B. This is
> +changing history, but since it's local history which you haven't shared with
> +anyone, that is okay for now! (Later, it may not make sense to do this; take a
> +look at the section below this one for some context.)
> +
> +=== After Review Approval
> +
> +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.
> +
> +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 merge your topic branch to `next` and life is good.
> +
> +However, if you discover it isn't so perfect after this point, you may need to
> +take some special steps depending on where you are in the process.
> +
> +If the maintainer has announced in the "What's cooking in git.git" email that
> +your topic is marked for `next` - that is, that they plan to merge it to `next`
> +but have not yet done so - you should send an email asking the maintainer to
> +wait a little longer: "I've sent v4 of my series and you marked it for `next`,
> +but I need to change this and that - please wait for v5 before you merge it."
> +
> +If the topic has already been merged to `next`, rather than modifying your
> +patches with `git rebase -i`, you should make further changes incrementally -
> +that is, with another commit, based on top of of the maintainer's topic branch

typo: "of of"

> +as detailed in https://github.com/gitster/git. Your work is still in the same
> +topic but is now incremental, rather than a wholesale rewrite of the topic
> +branch.
> +
> +The topic branches in the maintainer's GitHub are mirrored in GitGitGadget, so
> +if you're sending your reviews out that way, you should be sure to open your PR
> +against the appropriate GitGitGadget/Git branch.
> +
> +If you're using `git
> +send-email`, you can use it the same way as before, but you should generate your

Early line break on this line inside the `git send-email` command.

> +diffs from `<topic>..<mybranch>` and base your work on `<topic>` instead of
> +`master`.
> --
> 2.21.0.593.g511ec345e18-goog
>

Re: [PATCH v4] documentation: add tutorial for first contribution

[Jonathan Tan]

Sorry for not looking at this sooner. 

Firstly, I'm not sure if this file should be named without the ".txt",
like SubmittingPatches.

As for my other comments below, the Makefile comment below is the only
one I feel strongly about; feel free to disagree with the rest (which I
think are subjective).

> diff --git a/Documentation/Makefile b/Documentation/Makefile
> index 26a2342bea..fddc3c3c95 100644
> --- a/Documentation/Makefile
> +++ b/Documentation/Makefile
> @@ -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

Any reason not to keep this alphabetized?

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

I would rename the header to "Clone the Git repository" instead, since
"pull" has a specific meaning. Also, I think that "one of the best
places" is unnecessary (I would just say "Clone the Git repository from
one of its many mirrors, e.g.:"), but perhaps you want to leave it in
there to maintain the informal tone.

> +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);
> +----

I was going to say to not include the "extern", but I see that builtin.h
has them already, so it's probably better to leave it there for
consistency.

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

For an international audience, it might be better to replace "cheating
off" with its literal meaning. It took me a while to understand that
"cheating off" was meant to evoke a so-called cheat sheet.

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

I think the last sentence is confusing - didn't we already add the
context? (And if it's meant more along the lines of "if you want to
change your commit message for whatever reason, use --amend", I don't
think that's necessary here, since we are assuming that the user knows
how to use Git.)

> +=== 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 : "");

Follow the Git style by not using braces around the single-line `for`
block.

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

Same comment about "cheat off" as previously.

> +----
> +$ git send-email --to=target@example.com
> +----

Hmm...don't you need to specify a directory?

> +You will also need to go and find the Message-Id of your previous cover letter.
> +You can either note it when you send the first series, from the output of `git
> +send-email`, or you can look it up on the
> +https://public-inbox.org/git[mailing list]. Find your cover letter in the
> +archives, click on it, then click "permalink" or "raw" to reveal the Message-Id
> +header. It should match:
> +
> +----
> +Message-Id: <foo.12345.author@example.com>
> +----
> +
> +Your Message-Id is `<foo.12345.author@example.com>`. This example will be used
> +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.

I think it's better to describe the message ID as without the angle
brackets. Reading the RFC (https://tools.ietf.org/html/rfc2392), the
message-id doesn't have them.

[snip]

> +----
> +$ git send-email --to=target@example.com
> +		 --in-reply-to=<foo.12345.author@example.com>
> +----

The angle brackets can be omitted. Also, directory (or glob expression
in this case)?

> +=== Bonus Chapter: One-Patch Changes

This is not truly a bonus - the mailing list prefers this if the patch
set contains only one patch.

> +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
> +meaningful and explain the at a high level the purpose (what is happening and
> +why) of your patch, but if you need to supply even more context, you can do so
> +below the `---` in your patch. Take the example below, generated with
> +`git format-patch` on a single commit:

It's not clear to me how `git format-patch` can generate the extra
paragraph below. The user would either have to include "---" in the
commit message (in which case there would be an extra "---" below the
extra paragraph, which is perfectly safe) or edit the email *after*
`git-format-patch` has generated the email.

> +----
> +From 1345bbb3f7ac74abde040c12e737204689a72723 Mon Sep 17 00:00:00 2001
> +From: A U Thor <author@example.com>
> +Date: Thu, 18 Apr 2019 15:11:02 -0700
> +Subject: [PATCH] README: change the grammar
> +
> +I think it looks better this way. This part of the commit message will
> +end up in the commit-log.
> +
> +Signed-off-by: A U Thor <author@example.com>
> +---
> +Let's have a wild discussion about grammar on the mailing list. This
> +part of my email will never end up in the commit log. Here is where I
> +can add additional context to the mailing list about my intent, outside
> +of the context of the commit log.
> +
> + README.md | 2 +-
> + 1 file changed, 1 insertion(+), 1 deletion(-)
> +
> +diff --git a/README.md b/README.md
> +index 88f126184c..38da593a60 100644

[snip]

There's also the issue of titles having Capital Initials raised in
another review [1]. I think it's better to use sentence case, like in
SubmittingPatches.

[1] https://public-inbox.org/git/CABURp0rE23SCxB4VD0-kVWp6OfS7-4O6biyD7zMqSUQvR_RZxg@mail.gmail.com/

Overall, thanks for writing this. I think it's a good overview of what a
contributor should do when they write a set of patches for inclusion in
Git.

I had a meta-concern about the length of this document, but I think most
(if not all) of the information contained herein is useful, so I think
that the length is fine.

The other meta-concern is maintaining the informal tone when we update
this document (for example, when we add features like range-diff which
can be used when sending v2 - well, somebody can add information about
that to this document once it has been merged); but I don't think that
is a concern in practice (either we keep the tone or there is a slight
tone mismatch, and I don't think that either is a big deal).

Re: [PATCH v4] documentation: add tutorial for first contribution

[Emily Shaffer]

On Thu, May 02, 2019 at 07:11:04PM -0700, Phil Hord wrote:
> On Tue, Apr 23, 2019 at 12:35 PM Emily Shaffer <emilyshaffer@google.com> wrote:
> >
> > 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.
> >
> 
> Thanks for working on this.  It's very nicely done.

:)

> > +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
> > +----
> > +
> > +You will be presented with your editor in order to write a 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
> 
> This part sounds a little ambiguous to me, as I'm expected to include
> the "Why" in my 50-column subject line.  I don't want to go overboard,
> but maybe direct them further to
> 
>     After this, insert a blank line (always required) and then some
> text describing
>     your change.  Remember to be explicit and ...
> 

Done. I agree it's ambiguous about how much is supposed to go into the
subject versus the body, so I've hopefully clarified by explaining that
the body "should provide the bulk of the context".

> > +----
> > +$ make all doc
> > +$ man Documentation/git-psuh.1
> > +----
> > +
> > +or
> > +
> > +----
> > +$ make -C Documentation/git-psuh.1
> 
> There's an unwanted slash here. This should be `make -C Documentation
> git-psuh.1`.

Done, thanks. Nice catch.

> > +=== Overview of Testing Structure
> > +
> > +The tests in Git live in `t/` and are named with a 4-decimal digit, according to
> 
> This doesn't parse.  How about this?
> 
>     named with a 4-decimal digit number using the schema shown in ...
> 

I think we've both managed to miss that I've swapped "decimal" and
"digit" by accident. :) How about "named with a 4-digit decimal number
using the schema"?

Very pleased that you caught this, since all the once-overs in the world
from the cooked-brain author and the cooked-brain second- or tenth-pass
reviewers wouldn't have caught this mistake. Thanks!

> > +== Sending Patches via GitGitGadget
> > +
> > +One option for sending patches is to follow a typical pull request workflow and
> > +send your patches out via GitGitGadget. 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. It also runs the Git continuous integration
> 
> nit: "send" them out for you.

Done, thanks.

> 
> > +suite for you. It's documented at http://gitgitgadget.github.io.
> > +
> > +=== Forking git/git on GitHub
> > +
> > +Before you can send your patch off to be reviewed using GitGitGadget, you will
> > +need to fork the Git project and upload your changes. First thing - make sure
> > +you have a GitHub account.
> > +
> > +Head to the https://github.com/git/git[GitHub mirror] and look for the Fork
> > +button. Place your fork wherever you deem appropriate and create it.
> > +
> > +=== Uploading To Your Own Fork
> 
> I noticed some of your titles Use Capital Initials and others do not.
> I suppose either is fine, but consistency is appreciated.
>

Nice catch. I've gone through and fixed up the titles throughout; as a
result I also caught a missed monospace.

> > +=== Sending Your Patches
> > +
> > +Now that your CI is passing and someone has granted you permission to use
> > +GitGitGadget with the `/allow` command,  sending out for review is as simple as
> 
> nit: extra space before "sending"
> 
Done.

> > +Next, go look at your pull request against GitGitGadget; you should see the CI
> > +has been  kicked off again. Now while the CI is running is a good time for you
> 
> nit: extra spaces before "kicked"
> 
Done.

> > +Make sure you retain the ``[PATCH 0/X]'' part; that's what indicates to the Git
> > +community that this email is the beginning of a review, and many reviewers
> > +filter their email for this type of flag.
> > +
> > +You'll need to add some extra
> 
> Early line break on this line.
> 

Done.

> > +Now send the emails again, paying close attention to which messages you pass in
> > +to the command:
> > +
> > +----
> > +$ git send-email --to=target@example.com
> > +                --in-reply-to=<foo.12345.author@example.com>
> 
> You probably need quotes around this message-id argument to avoid the
> shell interpreting it as redirection.
> 

Indeed. And it looks like I also missed, here and above, specifying the
actual patch files to mail. Whoops... :)

> > +----
> > +
> > +=== 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
> > +meaningful and explain the at a high level the purpose (what is happening and
> 
> typo: "explain at a high level"
> 

Done.

> > +If the topic has already been merged to `next`, rather than modifying your
> > +patches with `git rebase -i`, you should make further changes incrementally -
> > +that is, with another commit, based on top of of the maintainer's topic branch
> 
> typo: "of of"
> 

Done.

> > +as detailed in https://github.com/gitster/git. Your work is still in the same
> > +topic but is now incremental, rather than a wholesale rewrite of the topic
> > +branch.
> > +
> > +The topic branches in the maintainer's GitHub are mirrored in GitGitGadget, so
> > +if you're sending your reviews out that way, you should be sure to open your PR
> > +against the appropriate GitGitGadget/Git branch.
> > +
> > +If you're using `git
> > +send-email`, you can use it the same way as before, but you should generate your
> 
> Early line break on this line inside the `git send-email` command.
> 

Done.

Thanks very much for the thorough review, Phil! I appreciate it!

Re: [PATCH v4] documentation: add tutorial for first contribution

[Emily Shaffer]

On Mon, May 06, 2019 at 03:28:44PM -0700, Jonathan Tan wrote:
> Sorry for not looking at this sooner. 
> 
> Firstly, I'm not sure if this file should be named without the ".txt",
> like SubmittingPatches.

I should mention that during this change's life as a GitGitGadget PR,
dscho performed a review in GitHub, which included a recommendation to
name this SubmittingPatches.txt. This obviates quite a bit of
boilerplate within the Makefile as there are rules for handling *.txt
documentation generation already. You can check out Johannes's review:
https://github.com/gitgitgadget/git/pull/177

I keep forgetting to add a Reviewed-by line to my commit. I'll do that
before pushing based on your comments, as well as Josh and Phil's.

> 
> As for my other comments below, the Makefile comment below is the only
> one I feel strongly about; feel free to disagree with the rest (which I
> think are subjective).
> 
> > diff --git a/Documentation/Makefile b/Documentation/Makefile
> > index 26a2342bea..fddc3c3c95 100644
> > --- a/Documentation/Makefile
> > +++ b/Documentation/Makefile
> > @@ -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
> 
> Any reason not to keep this alphabetized?

No reason, done.

> > +=== 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
> > +----
> 
> I would rename the header to "Clone the Git repository" instead, since
> "pull" has a specific meaning. Also, I think that "one of the best
> places" is unnecessary (I would just say "Clone the Git repository from
> one of its many mirrors, e.g.:"), but perhaps you want to leave it in
> there to maintain the informal tone.

I've merged the language from both and added that the GH mirror at
git/git is official.

"Git is mirrored in a number of locations. Clone the repository from one
of them; https://git-scm.com/downloads suggests one of the best places
to clone from is the official mirror on GitHub."

> > +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);
> > +----
> 
> I was going to say to not include the "extern", but I see that builtin.h
> has them already, so it's probably better to leave it there for
> consistency.
> 

This was brought up in an earlier review and there's also a review
pending to remove them, which seems to have turned into a discussion
about how to maintain a script to remove them :) I'm going to avoid
politics and also remove the extern here, because it looks like that's
the direction the codebase is heading anyway.

> > +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.
> 
> For an international audience, it might be better to replace "cheating
> off" with its literal meaning. It took me a while to understand that
> "cheating off" was meant to evoke a so-called cheat sheet.

You're right; I leaned too far towards casual voice here and included a
colloquialism. I've modified this to "let's keep mimicking `push`" as I
feel it means the same thing, without the slang but with a similar tone.

I also considered "copying from `push`" but didn't want to indicate we
would be copy-pasting lines of code. If anybody's got a better
suggestion for a verb here I'm happy to hear it; "cheating from X" is a
phrase I'm trying to stop using anyways :)

> > +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`.
> 
> I think the last sentence is confusing - didn't we already add the
> context? (And if it's meant more along the lines of "if you want to
> change your commit message for whatever reason, use --amend", I don't
> think that's necessary here, since we are assuming that the user knows
> how to use Git.)

I think you're right. Removed. This seems like a holdover from the first
iteration, where I provided oneline commit messages for each commit,
instead of good practice examples.

> > +=== 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 : "");
> 
> Follow the Git style by not using braces around the single-line `for`
> block.

Done.

> > +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`.
> 
> Same comment about "cheat off" as previously.

Done. Again used s/cheat off of/mimic.

> > +----
> > +$ git send-email --to=target@example.com
> > +----
> 
> Hmm...don't you need to specify a directory?

Fixed...

> > +You will also need to go and find the Message-Id of your previous cover letter.
> > +You can either note it when you send the first series, from the output of `git
> > +send-email`, or you can look it up on the
> > +https://public-inbox.org/git[mailing list]. Find your cover letter in the
> > +archives, click on it, then click "permalink" or "raw" to reveal the Message-Id
> > +header. It should match:
> > +
> > +----
> > +Message-Id: <foo.12345.author@example.com>
> > +----
> > +
> > +Your Message-Id is `<foo.12345.author@example.com>`. This example will be used
> > +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.
> 
> I think it's better to describe the message ID as without the angle
> brackets. Reading the RFC (https://tools.ietf.org/html/rfc2392), the
> message-id doesn't have them.
> 
> [snip]

Junio argued the opposite here:
https://public-inbox.org/git/xmqqr29vbpge.fsf@gitster-ct.c.googlers.com/
and it looks like the RFC (possibly poorly-worded) also indicates the
angle brackets are part of the Message-ID spec (the ID without the
brackets is a '"mid" URL'):

   A "cid" URL is converted to the corresponding Content-ID message
   header [MIME] by removing the "cid:" prefix, converting the % encoded
   character to their equivalent US-ASCII characters, and enclosing the
   remaining parts with an angle bracket pair, "<" and ">".

   ...

   A "mid" URL is converted to a Message-ID or Message-ID/Content-ID
   pair in a similar fashion.

So I'll leave this the way it is.

> 
> > +----
> > +$ git send-email --to=target@example.com
> > +		 --in-reply-to=<foo.12345.author@example.com>
> > +----
> 
> The angle brackets can be omitted. Also, directory (or glob expression
> in this case)?

See above re: angle brackets. I've added the argument "psuh/v2*" to
include the v2 patches.

> 
> > +=== Bonus Chapter: One-Patch Changes
> 
> This is not truly a bonus - the mailing list prefers this if the patch
> set contains only one patch.

In the context specifically of this tutorial, I sort of think it is -
since the tutorial doesn't send out a one-patch changeset, this seems
like an aside to me. That is, I feel like the flow of the tutorial says,
"First you do A, then B, then C (and by the way, if you're doing C', you
would do it like this)."

I also liked the phrasing as a bonus because it covers something that
GitGitGadget does not support, so it's "extra content" compared to the
analogous chapter on using GGG.

If you feel very strongly, I could change it, but for now I disagree.

> > +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
> > +meaningful and explain the at a high level the purpose (what is happening and
> > +why) of your patch, but if you need to supply even more context, you can do so
> > +below the `---` in your patch. Take the example below, generated with
> > +`git format-patch` on a single commit:
> 
> It's not clear to me how `git format-patch` can generate the extra
> paragraph below. The user would either have to include "---" in the
> commit message (in which case there would be an extra "---" below the
> extra paragraph, which is perfectly safe) or edit the email *after*
> `git-format-patch` has generated the email.
 
I will clarify the wording to indicate that I mean the user should edit
the patch after generating. Brevity got in the way of completeness here.
Thanks.

I've modified the sentence to include that there was a second step here:
"generated with `git format-patch` on a single commit, and then edited
to add the content between the `---` and the diffstat."

I've also added a sentence to the note in the commit at the end, "This
section was added after `git format-patch` was run, by editing the patch
file in a text editor."

> > +----
> > +From 1345bbb3f7ac74abde040c12e737204689a72723 Mon Sep 17 00:00:00 2001
> > +From: A U Thor <author@example.com>
> > +Date: Thu, 18 Apr 2019 15:11:02 -0700
> > +Subject: [PATCH] README: change the grammar
> > +
> > +I think it looks better this way. This part of the commit message will
> > +end up in the commit-log.
> > +
> > +Signed-off-by: A U Thor <author@example.com>
> > +---
> > +Let's have a wild discussion about grammar on the mailing list. This
> > +part of my email will never end up in the commit log. Here is where I
> > +can add additional context to the mailing list about my intent, outside
> > +of the context of the commit log.
> > +
> > + README.md | 2 +-
> > + 1 file changed, 1 insertion(+), 1 deletion(-)
> > +
> > +diff --git a/README.md b/README.md
> > +index 88f126184c..38da593a60 100644
> 
> [snip]
> 
> There's also the issue of titles having Capital Initials raised in
> another review [1]. I think it's better to use sentence case, like in
> SubmittingPatches.

Phil Hord pointed this out too. I've combed through the titles, and
caught one which missed a monospace formatting.

> 
> [1] https://public-inbox.org/git/CABURp0rE23SCxB4VD0-kVWp6OfS7-4O6biyD7zMqSUQvR_RZxg@mail.gmail.com/
> 
> Overall, thanks for writing this. I think it's a good overview of what a
> contributor should do when they write a set of patches for inclusion in
> Git.
> 
> I had a meta-concern about the length of this document, but I think most
> (if not all) of the information contained herein is useful, so I think
> that the length is fine.

Thanks. I wondered about that too, but mostly regarding review velocity.
I'm not sure that it makes sense to split this into parts, but I wonder
if it's worth it to add anchors to each chapter so that it'd be easier
to send a specific section to someone who had a question. For example,
in the standup last week, dscho suggested to vishal that they have a
look at this patch, and named a specific section. It'd be easier if
dscho could link something like
git-scm.org/docs/MyFirstContribution.html#adding-tests.

I've convinced myself that this is a good idea, so I'll add them before
I push v5.

> The other meta-concern is maintaining the informal tone when we update
> this document (for example, when we add features like range-diff which
> can be used when sending v2 - well, somebody can add information about
> that to this document once it has been merged); but I don't think that
> is a concern in practice (either we keep the tone or there is a slight
> tone mismatch, and I don't think that either is a big deal).

I see your concern. I'm not sure whether it would really be a big deal
as long as folks who are editing the document remember that this is a
tutorial, not a reference document. That is, with your range-diff
example, an editor should mention something like "An alternative is to
use `range-diff`; you can first run `foo` against your new commit and
old diff, and then you can run `bar` to send it." rather than "Or, use
`range-diff`. Usage: `git range-diff [foo] [bar] <baz>`." And hopefully
that kind of tone difference should be pretty clear in the context of
the rest of the document.

The one concern I do have with the informal tone is that it may be
exclusionary to international or ESL contributors in ways that I can't
understand as a native US speaker. It looks like you caught one such
instance in your review this time. I'm not sure whether it makes sense
to reword the entire document, because I was hoping to keep it from
being intimidating by being overly formal/technical. It seems like so
far folks on the list have been comfortable reading it, so maybe it's
fine the way it is?


Thanks a bunch for your review, Jonathan.

 - Emily

Re: [PATCH v4] documentation: add tutorial for first contribution

[Jonathan Tan]

> On Mon, May 06, 2019 at 03:28:44PM -0700, Jonathan Tan wrote:
> > Sorry for not looking at this sooner. 
> > 
> > Firstly, I'm not sure if this file should be named without the ".txt",
> > like SubmittingPatches.
> 
> I should mention that during this change's life as a GitGitGadget PR,
> dscho performed a review in GitHub, which included a recommendation to
> name this SubmittingPatches.txt. This obviates quite a bit of
> boilerplate within the Makefile as there are rules for handling *.txt
> documentation generation already. You can check out Johannes's review:
> https://github.com/gitgitgadget/git/pull/177

Ah, thanks.

> > > +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.
> > 
> > For an international audience, it might be better to replace "cheating
> > off" with its literal meaning. It took me a while to understand that
> > "cheating off" was meant to evoke a so-called cheat sheet.
> 
> You're right; I leaned too far towards casual voice here and included a
> colloquialism. I've modified this to "let's keep mimicking `push`" as I
> feel it means the same thing, without the slang but with a similar tone.
> 
> I also considered "copying from `push`" but didn't want to indicate we
> would be copy-pasting lines of code. If anybody's got a better
> suggestion for a verb here I'm happy to hear it; "cheating from X" is a
> phrase I'm trying to stop using anyways :)

"Mimicking" sounds good to me.

> > I think it's better to describe the message ID as without the angle
> > brackets. Reading the RFC (https://tools.ietf.org/html/rfc2392), the
> > message-id doesn't have them.
> > 
> > [snip]
> 
> Junio argued the opposite here:
> https://public-inbox.org/git/xmqqr29vbpge.fsf@gitster-ct.c.googlers.com/
> and it looks like the RFC (possibly poorly-worded) also indicates the
> angle brackets are part of the Message-ID spec (the ID without the
> brackets is a '"mid" URL'):
> 
>    A "cid" URL is converted to the corresponding Content-ID message
>    header [MIME] by removing the "cid:" prefix, converting the % encoded
>    character to their equivalent US-ASCII characters, and enclosing the
>    remaining parts with an angle bracket pair, "<" and ">".
> 
>    ...
> 
>    A "mid" URL is converted to a Message-ID or Message-ID/Content-ID
>    pair in a similar fashion.
> 
> So I'll leave this the way it is.

OK, that's fine.

> > > +=== Bonus Chapter: One-Patch Changes
> > 
> > This is not truly a bonus - the mailing list prefers this if the patch
> > set contains only one patch.
> 
> In the context specifically of this tutorial, I sort of think it is -
> since the tutorial doesn't send out a one-patch changeset, this seems
> like an aside to me. That is, I feel like the flow of the tutorial says,
> "First you do A, then B, then C (and by the way, if you're doing C', you
> would do it like this)."
> 
> I also liked the phrasing as a bonus because it covers something that
> GitGitGadget does not support, so it's "extra content" compared to the
> analogous chapter on using GGG.
> 
> If you feel very strongly, I could change it, but for now I disagree.

Those are good points.

> > > +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
> > > +meaningful and explain the at a high level the purpose (what is happening and
> > > +why) of your patch, but if you need to supply even more context, you can do so
> > > +below the `---` in your patch. Take the example below, generated with
> > > +`git format-patch` on a single commit:
> > 
> > It's not clear to me how `git format-patch` can generate the extra
> > paragraph below. The user would either have to include "---" in the
> > commit message (in which case there would be an extra "---" below the
> > extra paragraph, which is perfectly safe) or edit the email *after*
> > `git-format-patch` has generated the email.
>  
> I will clarify the wording to indicate that I mean the user should edit
> the patch after generating. Brevity got in the way of completeness here.
> Thanks.
> 
> I've modified the sentence to include that there was a second step here:
> "generated with `git format-patch` on a single commit, and then edited
> to add the content between the `---` and the diffstat."
> 
> I've also added a sentence to the note in the commit at the end, "This
> section was added after `git format-patch` was run, by editing the patch
> file in a text editor."

Sounds good.

> > The other meta-concern is maintaining the informal tone when we update
> > this document (for example, when we add features like range-diff which
> > can be used when sending v2 - well, somebody can add information about
> > that to this document once it has been merged); but I don't think that
> > is a concern in practice (either we keep the tone or there is a slight
> > tone mismatch, and I don't think that either is a big deal).
> 
> I see your concern. I'm not sure whether it would really be a big deal
> as long as folks who are editing the document remember that this is a
> tutorial, not a reference document. That is, with your range-diff
> example, an editor should mention something like "An alternative is to
> use `range-diff`; you can first run `foo` against your new commit and
> old diff, and then you can run `bar` to send it." rather than "Or, use
> `range-diff`. Usage: `git range-diff [foo] [bar] <baz>`." And hopefully
> that kind of tone difference should be pretty clear in the context of
> the rest of the document.

I agree - the main thing is to remember that this is meant for the
newcomer who wants to start with a small-scoped project instead of the
experienced contributor who wants to know all there is about a topic.
(Which I think you've done very well, and should not be a problem for
the rest of the project to keep in mind too with the "My First
Contribution" name.)

> The one concern I do have with the informal tone is that it may be
> exclusionary to international or ESL contributors in ways that I can't
> understand as a native US speaker. It looks like you caught one such
> instance in your review this time. I'm not sure whether it makes sense
> to reword the entire document, because I was hoping to keep it from
> being intimidating by being overly formal/technical. It seems like so
> far folks on the list have been comfortable reading it, so maybe it's
> fine the way it is?

I agree that it's fine the way it is, and that the informal tone does
make this document (and by extension, the project) more accessible to
newcomers, which is a good thing.

I think that Emily is planning to send out a v5 with the Makefile
alphabetization, section header link targets, and some other textual
changes, and once she sends that out, I think that this is ready to be
merged in. So here's my reviewed-by:

Reviewed-by: Jonathan Tan <jonathantanmy@google.com>

[PATCH v5 0/2] documentation: add lab for first contribution

[Emily Shaffer]

Since v4, I've made one major change and a handful of minor changes. The
major change is contained entirely in patch 2/2; patch 1/2 has only nit
fixes compared to v4.

Major:
- I've added anchors to each section. These anchors are custom-named in
  order to be compatible with asciidoc as well as asciidoctor. I figured
  it would be easier to review the naming choices if the anchors stood
  alone from the main introductory patch.

Minor:
- Alphabetized Documentation/Makefile
- Fixup headers - a few renames for clarity, casing, and a missed
  monospace, based on Phil Hord & Jonathan Tan comments.
- Removed 'extern' from the addition to builtin.h
- Replace "cheating off" with "mimicking" in a few places
- Clarify instructions for writing commit message to remove ambiguity
  and include requirement for newline after subject
- Remove unnecessary explanation of `git commit --amend`
- Remove braces to bring code sample into Git style
- Typo, word-reversal, and early line break fixes
- Add neglected argument to `git send-email` samples to actually include
  patches

Emily Shaffer (2):
  documentation: add tutorial for first contribution
  documentation: add anchors to MyFirstContribution

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

-- 
2.21.0.1020.gf2820cf01a-goog

[PATCH v5 1/2] documentation: add tutorial for first contribution

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

Reviewed-by: Johannes Schindelin <johannes.schindelin@gmx.de>
Reviewed-by: Jonathan Tan <jonathantanmy@google.com>
Signed-off-by: Emily Shaffer <emilyshaffer@google.com>
---
 Documentation/Makefile                |    1 +
 Documentation/MyFirstContribution.txt | 1075 +++++++++++++++++++++++++
 2 files changed, 1076 insertions(+)
 create mode 100644 Documentation/MyFirstContribution.txt

diff --git a/Documentation/Makefile b/Documentation/Makefile
index 6d738f831e..360c8051e2 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -73,6 +73,7 @@ SP_ARTICLES += howto/maintain-git
 API_DOCS = $(patsubst %.txt,%,$(filter-out technical/api-index-skel.txt technical/api-index.txt, $(wildcard technical/api-*.txt)))
 SP_ARTICLES += $(API_DOCS)
 
+TECH_DOCS += MyFirstContribution
 TECH_DOCS += SubmittingPatches
 TECH_DOCS += technical/hash-function-transition
 TECH_DOCS += technical/http-protocol
diff --git a/Documentation/MyFirstContribution.txt b/Documentation/MyFirstContribution.txt
new file mode 100644
index 0000000000..0f9a7fed93
--- /dev/null
+++ b/Documentation/MyFirstContribution.txt
@@ -0,0 +1,1075 @@
+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
+
+=== Clone the Git Repository
+
+Git is mirrored in a number of locations. Clone the repository from one of them;
+https://git-scm.com/downloads suggests one of the best places to clone from is
+the official mirror on 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 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:
+
+----
+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 mimicking `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
+----
+
+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
+----
+
+You will be presented with your editor in order to write a commit message. Start
+the commit with a 50-column or less subject line, including the name of the
+component you're working on, followed by a blank line (always required) and then
+the body of your commit message, which should provide the bulk of the context.
+Remember to be explicit and provide the "Why" of 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 <author@example.com>
+----
+
+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).
+
+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 mimic 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:
+
+----
+$ make all doc
+$ man Documentation/git-psuh.1
+----
+
+or
+
+----
+$ make -C Documentation/ git-psuh.1
+$ 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
+* Prove the current behavior matches the expected behavior
+* Ensure the externally-visible behavior isn't broken in later changes
+
+So let's write some tests.
+
+Related reading: `t/README`
+
+=== Overview of Testing Structure
+
+The tests in Git live in `t/` and are named with a 4-digit decimal number using
+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
+and `git send-email`.
+
+== Sending Patches via GitGitGadget
+
+One option for sending patches is to follow a typical pull request workflow and
+send your patches out via GitGitGadget. 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 send them out for you. It also runs the Git continuous integration
+suite for you. It's documented at http://gitgitgadget.github.io.
+
+=== Forking `git/git` on GitHub
+
+Before you can send your patch off to be reviewed using GitGitGadget, you will
+need to fork the Git project and upload your changes. First thing - make sure
+you have a GitHub account.
+
+Head to the https://github.com/git/git[GitHub mirror] and look for the Fork
+button. Place your fork wherever you deem appropriate and create it.
+
+=== Uploading to Your Own Fork
+
+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 git@github.com: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`.
+
+////
+TODO https://github.com/gitgitgadget/gitgitgadget/issues/83
+It'd be nice to be able to verify that the patch looks good before sending it
+to everyone on Git mailing list.
+=== Check Your Work
+////
+
+=== Sending Your Patches
+
+Now that your CI is passing and someone has granted you permission to use
+GitGitGadget with the `/allow` command, sending out for review is as simple as
+commenting on your PR with `/submit`.
+
+=== Updating With Comments
+
+Skip ahead to <<reviewing,Responding to Reviews>> for information on how to
+reply to review comments you will receive on the mailing list.
+
+Once you have your branch again in the shape you want following all review
+comments, you can submit again:
+
+----
+$ git push -f remotename psuh
+----
+
+Next, go look at your pull request against GitGitGadget; you should see the CI
+has been kicked off again. Now while the CI is running is a good time for you
+to modify your description at the top of the pull request thread; it will be
+used again as the cover letter. You should use this space to describe what
+has changed since your previous version, so that your reviewers have some idea
+of what they're looking at. When the CI is done running, you can comment once
+more with `/submit` - GitGitGadget will automatically add a v2 mark to your
+changes.
+
+== Sending Patches with `git send-email`
+
+If you don't want to use GitGitGadget, you can also use Git itself to mail your
+patches. Some benefits of using Git this way include finer grained control of
+subject line (for example, being able to use the tag [RFC PATCH] in the subject)
+and being able to send a ``dry run'' mail to yourself to ensure it all looks
+good before going out to the list.
+
+=== Prerequisite: Setting Up `git send-email`
+
+Configuration for `send-email` can vary based on your operating system and email
+provider, and so will not be covered in this tutorial, beyond stating that in
+many distributions of Linux, `git-send-email` is not packaged alongside the
+typical `git` install. You may need to install this additional package; there
+are a number of resources online to help you do so. You will also need to
+determine the right way to configure it to use your SMTP server; again, as this
+configuration can change significantly based on your system and email setup, it
+is out of scope for the context of this tutorial.
+
+=== Preparing Initial Patchset
+
+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 --cover-letter -o psuh/ master..psuh
+----
+
+The `--cover-letter` parameter tells `format-patch` to create a cover letter
+template for you. You will need to fill in the template before you're ready
+to send - but for now, the template will be next to your other patches.
+
+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.
+
+`master..psuh` tells `format-patch` to generate patches for the difference
+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.
+
+NOTE: Optionally, you can also use the `--rfc` flag to prefix your patch subject
+with ``[RFC PATCH]'' instead of ``[PATCH]''. RFC stands for ``request for
+comments'' and indicates that while your code isn't quite ready for submission,
+you'd like to begin the code review process. This can also be used when your
+patch is a proposal, but you aren't sure whether the community wants to solve
+the problem with that approach or not - to conduct a sort of design review. You
+may also see on the list patches marked ``WIP'' - this means they are incomplete
+but want reviewers to look at what they have so far. You can add this flag with
+`--subject-prefix=WIP`.
+
+Check and make sure that your patches and cover letter template exist in the
+directory you specified - you're nearly ready to send out your review!
+
+=== Preparing Email
+
+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). Since you invoked `format-patch`
+with `--cover-letter`, you've already got a template ready. Open it up in your
+favorite editor.
+
+You should see a number of headers present already. Check that your `From:`
+header is correct. Then modify your `Subject:` to something which succinctly
+covers the purpose of your entire topic branch, for example:
+
+----
+Subject: [PATCH 0/7] adding the 'psuh' command
+----
+
+Make sure you retain the ``[PATCH 0/X]'' part; that's what indicates to the Git
+community that this email is the beginning of a review, and many reviewers
+filter their email for this type of flag.
+
+You'll need to add some extra parameters when you invoke `git send-email` to add
+the cover letter.
+
+Next you'll have to fill out the body of your cover letter. This is an important
+component of change submission as it explains to the community from a high level
+what you're trying to do, and why, in a way that's more apparent than just
+looking at your diff. Be sure to explain anything your diff doesn't make clear
+on its own.
+
+Here's an example body for `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 tutorial and should not
+be merged.
+----
+
+The template created by `git format-patch --cover-letter` includes a diffstat.
+This gives reviewers a summary of what they're in for when reviewing your topic.
+The one generated for `psuh` from the sample implementation looks like this:
+
+----
+ Documentation/git-psuh.txt | 40 +++++++++++++++++++++
+ Makefile                   |  1 +
+ builtin.h                  |  1 +
+ builtin/psuh.c             | 73 ++++++++++++++++++++++++++++++++++++++
+ git.c                      |  1 +
+ t/t9999-psuh-tutorial.sh   | 12 +++++++
+ 6 files changed, 128 insertions(+)
+ create mode 100644 Documentation/git-psuh.txt
+ create mode 100644 builtin/psuh.c
+ create mode 100755 t/t9999-psuh-tutorial.sh
+----
+
+Finally, the letter will include the version of Git used to generate the
+patches. You can leave that string alone.
+
+=== Sending Email
+
+At this point you should have a directory `psuh/` which is filled with your
+patches and a cover letter. Time to mail it out! You can send it like this:
+
+----
+$ git send-email --to=target@example.com psuh/*.patch
+----
+
+NOTE: Check `git help send-email` for some other options which you may find
+valuable, such as changing the Reply-to address or adding more CC and BCC lines.
+
+NOTE: When you are sending a real patch, it will go to git@vger.kernel.org - but
+please don't send your patchset from the tutorial to the real mailing list! For
+now, you can send it to yourself, to make sure you understand how it will look.
+
+After you run the command above, 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 be sent! Congratulations!
+
+Awesome, now the community will drop everything and review your changes. (Just
+kidding - be patient!)
+
+=== Sending v2
+
+Skip ahead to <<reviewing,Responding to Reviews>> for information on how to
+handle comments from reviewers. Continue this section when your topic branch is
+shaped the way you want it to look for your patchset v2.
+
+When you're ready with the next iteration of your patch, the process is fairly
+similar.
+
+First, generate your v2 patches again:
+
+----
+$ git format-patch -v2 --cover-letter -o psuh/ master..psuh
+----
+
+This will add your v2 patches, all named like `v2-000n-my-commit-subject.patch`,
+to the `psuh/` directory. You may notice that they are sitting alongside the v1
+patches; that's fine, but be careful when you are ready to send them.
+
+Edit your cover letter again. Now is a good time to mention what's different
+between your last version and now, if it's something significant. You do not
+need the exact same body in your second cover letter; focus on explaining to
+reviewers the changes you've made that may not be as visible.
+
+You will also need to go and find the Message-Id of your previous cover letter.
+You can either note it when you send the first series, from the output of `git
+send-email`, or you can look it up on the
+https://public-inbox.org/git[mailing list]. Find your cover letter in the
+archives, click on it, then click "permalink" or "raw" to reveal the Message-Id
+header. It should match:
+
+----
+Message-Id: <foo.12345.author@example.com>
+----
+
+Your Message-Id is `<foo.12345.author@example.com>`. This example will be used
+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.
+
+While you're looking at the email, you should also note who is CC'd, as it's
+common practice in the mailing list to keep all CCs on a thread. You can add
+these CC lines directly to your cover letter with a line like so in the header
+(before the Subject line):
+
+----
+CC: author@example.com, Othe R <other@example.com>
+----
+
+Now send the emails again, paying close attention to which messages you pass in
+to the command:
+
+----
+$ git send-email --to=target@example.com
+		 --in-reply-to="<foo.12345.author@example.com>"
+		 psuh/v2*
+----
+
+=== 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
+meaningful and explain at a high level the purpose (what is happening and why)
+of your patch, but if you need to supply even more context, you can do so below
+the `---` in your patch. Take the example below, which was generated with `git
+format-patch` on a single commit, and then edited to add the content between
+the `---` and the diffstat.
+
+----
+From 1345bbb3f7ac74abde040c12e737204689a72723 Mon Sep 17 00:00:00 2001
+From: A U Thor <author@example.com>
+Date: Thu, 18 Apr 2019 15:11:02 -0700
+Subject: [PATCH] README: change the grammar
+
+I think it looks better this way. This part of the commit message will
+end up in the commit-log.
+
+Signed-off-by: A U Thor <author@example.com>
+---
+Let's have a wild discussion about grammar on the mailing list. This
+part of my email will never end up in the commit log. Here is where I
+can add additional context to the mailing list about my intent, outside
+of the context of the commit log. This section was added after `git
+format-patch` was run, by editing the patch file in a text editor.
+
+ README.md | 2 +-
+ 1 file changed, 1 insertion(+), 1 deletion(-)
+
+diff --git a/README.md b/README.md
+index 88f126184c..38da593a60 100644
+--- a/README.md
++++ b/README.md
+@@ -3,7 +3,7 @@
+ Git - fast, scalable, distributed revision control system
+ =========================================================
+
+-Git is a fast, scalable, distributed revision control system with an
++Git is a fast, scalable, and distributed revision control system with an
+ unusually rich command set that provides both high-level operations
+ and full access to internals.
+
+--
+2.21.0.392.gf8f6787159e-goog
+----
+
+== My Patch Got Emailed - Now What?
+
+[[reviewing]]
+=== Responding to Reviews
+
+After a few days, you will hopefully receive a reply to your patchset with some
+comments. Woohoo! Now you can get back to work.
+
+It's good manners to reply to each comment, notifying the reviewer that you have
+made the change requested, feel the original is better, or that the comment
+inspired you to do something a new way which is superior to both the original
+and the suggested change. This way reviewers don't need to inspect your v2 to
+figure out whether you implemented their comment or not.
+
+If you are going to push back on a comment, be polite and explain why you feel
+your original is better; be prepared that the reviewer may still disagree with
+you, and the rest of the community may weigh in on one side or the other. As
+with all code reviews, it's important to keep an open mind to doing something a
+different way than you originally planned; other reviewers have a different
+perspective on the project than you do, and may be thinking of a valid side
+effect which had not occurred to you. It is always okay to ask for clarification
+if you aren't sure why a change was suggested, or what the reviewer is asking
+you to do.
+
+Make sure your email client has a plaintext email mode and it is turned on; 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.
+
+When you're making changes to your code, it is cleanest - that is, the resulting
+commits are easiest to look at - if you use `git rebase -i` (interactive
+rebase). Take a look at this
+https://www.oreilly.com/library/view/git-pocket-guide/9781449327507/ch10.html[overview]
+from O'Reilly. The general idea is to modify each commit which requires changes;
+this way, instead of having a patch A with a mistake, a patch B which was fine
+and required no upstream reviews in v1, and a patch C which fixes patch A for
+v2, you can just ship a v2 with a correct patch A and correct patch B. This is
+changing history, but since it's local history which you haven't shared with
+anyone, that is okay for now! (Later, it may not make sense to do this; take a
+look at the section below this one for some context.)
+
+=== After Review Approval
+
+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.
+
+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 merge your topic branch to `next` and life is good.
+
+However, if you discover it isn't so perfect after this point, you may need to
+take some special steps depending on where you are in the process.
+
+If the maintainer has announced in the "What's cooking in git.git" email that
+your topic is marked for `next` - that is, that they plan to merge it to `next`
+but have not yet done so - you should send an email asking the maintainer to
+wait a little longer: "I've sent v4 of my series and you marked it for `next`,
+but I need to change this and that - please wait for v5 before you merge it."
+
+If the topic has already been merged to `next`, rather than modifying your
+patches with `git rebase -i`, you should make further changes incrementally -
+that is, with another commit, based on top of the maintainer's topic branch as
+detailed in https://github.com/gitster/git. Your work is still in the same topic
+but is now incremental, rather than a wholesale rewrite of the topic branch.
+
+The topic branches in the maintainer's GitHub are mirrored in GitGitGadget, so
+if you're sending your reviews out that way, you should be sure to open your PR
+against the appropriate GitGitGadget/Git branch.
+
+If you're using `git send-email`, you can use it the same way as before, but you
+should generate your diffs from `<topic>..<mybranch>` and base your work on
+`<topic>` instead of `master`.
-- 
2.21.0.1020.gf2820cf01a-goog

[PATCH v5 2/2] documentation: add anchors to MyFirstContribution

[Emily Shaffer]

During the course of review for MyFirstContribution.txt, the suggestion
came up to include anchors to make it easier for veteran contributors to
link specific sections of this documents to newbies. To make life easier
for reviewers, add these anchors in their own commit. See review context
here: https://public-inbox.org/git/20190507195938.GD220818@google.com/

AsciiDoc does not support :sectanchors: and the anchors are not
discoverable, but they are referenceable. So a link to
"foo.com/MyFirstContribution.html#prerequisites" will still work if that
file was generated with AsciiDoc. The inclusion of :sectanchors: does
not create warnings or errors while compiling directly with `asciidoc -b
html5 Documentation/MyFirstContribution.txt` or while compiling with
`make doc`.

AsciiDoctor does support :sectanchors: and displays a paragraph link on
mouseover. When the anchor is included above or inline with a section
(as in this change), the link provided points to the custom ID contained
within [[]] instead of to an autogenerated ID. Practically speaking,
this means we have .../MyFirstContribution.html#summary instead of
.../MyFirstContribution.html#_summary. In addition to being prettier,
the custom IDs also enable anchor linking to work with
asciidoc-generated pages. This change compiles with no warnings using
`asciidoctor -b html5 Documentation/MyFirstContribution.txt`.

Signed-off-by: Emily Shaffer <emilyshaffer@google.com>
---
 Documentation/MyFirstContribution.txt | 35 +++++++++++++++++++++++++++
 1 file changed, 35 insertions(+)

diff --git a/Documentation/MyFirstContribution.txt b/Documentation/MyFirstContribution.txt
index 0f9a7fed93..a0380d5dc8 100644
--- a/Documentation/MyFirstContribution.txt
+++ b/Documentation/MyFirstContribution.txt
@@ -1,16 +1,20 @@
 My First Contribution to the Git Project
 ========================================
+:sectanchors:
 
+[[summary]]
 == 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]]
 === 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]]
 === Related Reading
 
 This tutorial aims to summarize the following documents, but the reader may find
@@ -19,8 +23,10 @@ useful additional context:
 - `Documentation/SubmittingPatches`
 - `Documentation/howto/new-command.txt`
 
+[[getting-started]]
 == Getting Started
 
+[[cloning]]
 === Clone the Git Repository
 
 Git is mirrored in a number of locations. Clone the repository from one of them;
@@ -31,6 +37,7 @@ the official mirror on GitHub.
 $ git clone https://github.com/git/git git
 ----
 
+[[identify-problem]]
 === Identify Problem to Solve
 
 ////
@@ -44,6 +51,7 @@ 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`.)
 
+[[setup-workspace]]
 === Set Up Your Workspace
 
 Let's start by making a development branch to work on our changes. Per
@@ -62,11 +70,13 @@ $ 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]]
 == Code It Up!
 
 NOTE: A reference implementation can be found at
 https://github.com/nasamuffin/git/tree/psuh.
 
+[[add-new-command]]
 === Adding a New Command
 
 Lots of the subcommands are written as builtins, which means they are
@@ -195,6 +205,7 @@ 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]]
 === Implementation
 
 It's probably useful to do at least something besides printing out a string.
@@ -359,6 +370,7 @@ about. Neat! Let's commit that as well.
 $ git commit -sm "psuh: display the top of origin/master"
 ----
 
+[[add-documentation]]
 === Adding Documentation
 
 Awesome! You've got a fantastic new command that you're ready to share with the
@@ -446,6 +458,7 @@ sees that your command has been implemented as well as documented) by running
 
 Go ahead and commit your new documentation change.
 
+[[add-usage]]
 === Adding Usage Text
 
 Try and run `./bin-wrappers/git psuh -h`. Your command should crash at the end.
@@ -502,6 +515,7 @@ your command terminated before anything else interesting happens. Great!
 
 Go ahead and commit this one, too.
 
+[[testing]]
 == Testing
 
 It's important to test your code - even for a little toy command like this one.
@@ -516,11 +530,13 @@ So let's write some tests.
 
 Related reading: `t/README`
 
+[[overview-test-structure]]
 === Overview of Testing Structure
 
 The tests in Git live in `t/` and are named with a 4-digit decimal number using
 the schema shown in the Naming Tests section of `t/README`.
 
+[[write-new-test]]
 === Writing Your Test
 
 Since this a toy command, let's go ahead and name the test with t9999. However,
@@ -569,6 +585,7 @@ 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.
 
+[[local-test]]
 === Running Locally
 
 Let's try and run locally:
@@ -592,6 +609,7 @@ dependencies. `prove` also makes the output nicer.
 
 Go ahead and commit this change, as well.
 
+[[ready-to-share]]
 == Getting Ready to Share
 
 You may have noticed already that the Git project performs its code reviews via
@@ -614,6 +632,7 @@ 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
 and `git send-email`.
 
+[[howto-ggg]]
 == Sending Patches via GitGitGadget
 
 One option for sending patches is to follow a typical pull request workflow and
@@ -624,6 +643,7 @@ mirror of the Git project, and does some magic to turn the PR into a set of
 emails and send them out for you. It also runs the Git continuous integration
 suite for you. It's documented at http://gitgitgadget.github.io.
 
+[[create-fork]]
 === Forking `git/git` on GitHub
 
 Before you can send your patch off to be reviewed using GitGitGadget, you will
@@ -633,6 +653,7 @@ you have a GitHub account.
 Head to the https://github.com/git/git[GitHub mirror] and look for the Fork
 button. Place your fork wherever you deem appropriate and create it.
 
+[[upload-to-fork]]
 === Uploading to Your Own Fork
 
 To upload your branch to your own fork, you'll need to add the new fork as a
@@ -678,6 +699,7 @@ $ git push remotename psuh
 
 Now you should be able to go and check out your newly created branch on GitHub.
 
+[[send-pr-ggg]]
 === Sending a PR to GitGitGadget
 
 In order to have your code tested and formatted for review, you need to start by
@@ -689,6 +711,7 @@ 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.
 
+[[run-ci-ggg]]
 === Running CI and Getting Ready to Send
 
 If it's your first time using GitGitGadget (which is likely, as you're using
@@ -713,15 +736,18 @@ your patch is accepted into `next`.
 TODO https://github.com/gitgitgadget/gitgitgadget/issues/83
 It'd be nice to be able to verify that the patch looks good before sending it
 to everyone on Git mailing list.
+[[check-work-ggg]]
 === Check Your Work
 ////
 
+[[send-mail-ggg]]
 === Sending Your Patches
 
 Now that your CI is passing and someone has granted you permission to use
 GitGitGadget with the `/allow` command, sending out for review is as simple as
 commenting on your PR with `/submit`.
 
+[[responding-ggg]]
 === Updating With Comments
 
 Skip ahead to <<reviewing,Responding to Reviews>> for information on how to
@@ -743,6 +769,7 @@ of what they're looking at. When the CI is done running, you can comment once
 more with `/submit` - GitGitGadget will automatically add a v2 mark to your
 changes.
 
+[[howto-git-send-email]]
 == Sending Patches with `git send-email`
 
 If you don't want to use GitGitGadget, you can also use Git itself to mail your
@@ -751,6 +778,7 @@ subject line (for example, being able to use the tag [RFC PATCH] in the subject)
 and being able to send a ``dry run'' mail to yourself to ensure it all looks
 good before going out to the list.
 
+[[setup-git-send-email]]
 === Prerequisite: Setting Up `git send-email`
 
 Configuration for `send-email` can vary based on your operating system and email
@@ -762,6 +790,7 @@ determine the right way to configure it to use your SMTP server; again, as this
 configuration can change significantly based on your system and email setup, it
 is out of scope for the context of this tutorial.
 
+[[format-patch]]
 === Preparing Initial Patchset
 
 Sending emails with Git is a two-part process; before you can prepare the emails
@@ -800,6 +829,7 @@ but want reviewers to look at what they have so far. You can add this flag with
 Check and make sure that your patches and cover letter template exist in the
 directory you specified - you're nearly ready to send out your review!
 
+[[cover-letter]]
 === Preparing Email
 
 In addition to an email per patch, the Git community also expects your patches
@@ -863,6 +893,7 @@ The one generated for `psuh` from the sample implementation looks like this:
 Finally, the letter will include the version of Git used to generate the
 patches. You can leave that string alone.
 
+[[sending-git-send-email]]
 === Sending Email
 
 At this point you should have a directory `psuh/` which is filled with your
@@ -887,6 +918,7 @@ press `y` or `a` at these prompts your emails will be sent! Congratulations!
 Awesome, now the community will drop everything and review your changes. (Just
 kidding - be patient!)
 
+[[v2-git-send-email]]
 === Sending v2
 
 Skip ahead to <<reviewing,Responding to Reviews>> for information on how to
@@ -945,6 +977,7 @@ $ git send-email --to=target@example.com
 		 psuh/v2*
 ----
 
+[[single-patch]]
 === Bonus Chapter: One-Patch Changes
 
 In some cases, your very small change may consist of only one patch. When that
@@ -992,6 +1025,7 @@ index 88f126184c..38da593a60 100644
 2.21.0.392.gf8f6787159e-goog
 ----
 
+[[now-what]]
 == My Patch Got Emailed - Now What?
 
 [[reviewing]]
@@ -1035,6 +1069,7 @@ changing history, but since it's local history which you haven't shared with
 anyone, that is okay for now! (Later, it may not make sense to do this; take a
 look at the section below this one for some context.)
 
+[[after-approval]]
 === After Review Approval
 
 The Git project has four integration branches: `pu`, `next`, `master`, and
-- 
2.21.0.1020.gf2820cf01a-goog

Re: [PATCH v5 1/2] documentation: add tutorial for first contribution

[Emily Shaffer]

> +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);
> +	}

Just noticed the braces here, too. I have removed them from my local
copy and will upload again if I hear other comments warranting a v6.

 - Emily

Re: [PATCH v4] documentation: add tutorial for first contribution

[Junio C Hamano]

Jonathan Tan <jonathantanmy@google.com> writes:

> Sorry for not looking at this sooner. 
>
> Firstly, I'm not sure if this file should be named without the ".txt",
> like SubmittingPatches.

SubmittingPatches has historical baggage but this does not, so its
source can be left as .txt (alternatively we could have added .txt
to SubmittingPatches and left a symlink to keep the historical name,
without introducing "copy X to produce X.txt" rule).

cf. http://public-inbox.org/git/xmqqbm15kxi0.fsf@gitster-ct.c.googlers.com/

>> diff --git a/Documentation/Makefile b/Documentation/Makefile
>> index 26a2342bea..fddc3c3c95 100644
>> --- a/Documentation/Makefile
>> +++ b/Documentation/Makefile
>> @@ -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
>
> Any reason not to keep this alphabetized?

I do not think the order matters to $(MAKE), and I do not know if
the order matters to humans---sane ordering is done to futureproof
when we know we will have many more, but I do not know if we will.

So I find it a borderline Meh, but let's not waste your finding, as
sorting them in alpha order would be the sensible default.

>> +=== 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
>> +----
>
> I would rename the header to "Clone the Git repository" instead, since
> "pull" has a specific meaning. Also, I think that "one of the best
> places" is unnecessary (I would just say "Clone the Git repository from
> one of its many mirrors, e.g.:"), but perhaps you want to leave it in
> there to maintain the informal tone.

I am guilty of the verbosity there---just did not want to give an
impression that that one is the single authoritative copy (the k.org
one is probably the one, if only that it is the one pushed to first
when a new development happens).  I personally feel that your
rephrasing is fine, too, and do not have strong preference between
the two.

>> +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);
>> +----
>
> I was going to say to not include the "extern", but I see that builtin.h
> has them already, so it's probably better to leave it there for
> consistency.

Yup, this was discussed before.  If we can have the "NEEDSWORK" in
the asciidoc source that is not rendered in the end result, it may
be worth leaving a note to say when we remove them from builtin.h we
need to update this example, or something like that.

>> +----
>> +$ git send-email --to=target@example.com
>> +----
>
> Hmm...don't you need to specify a directory?

Even better would be the directory/*.patch glob pattern, as we'll
show how to emit format-patch output for v2 into the same directory
in a later step.  Just giving the directory and letting readdir()
collect would work for v1 but not for later iterations.

>> +Your Message-Id is `<foo.12345.author@example.com>`. This example will be used
>> +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.
>
> I think it's better to describe the message ID as without the angle
> brackets. Reading the RFC (https://tools.ietf.org/html/rfc2392), the
> message-id doesn't have them.

See earlier review(s).
Your reading is probably wrong, as that directly contradicts my
earlier suggestion based on the same RFC ;-)

>> +----
>> +$ git send-email --to=target@example.com
>> +		 --in-reply-to=<foo.12345.author@example.com>
>> +----
>
> The angle brackets can be omitted. Also, directory (or glob expression
> in this case)?

Yeah, a glob would be appropriate.

>> +=== Bonus Chapter: One-Patch Changes
>
> This is not truly a bonus - the mailing list prefers this if the patch
> set contains only one patch.
>
>> +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
>> +meaningful and explain the at a high level the purpose (what is happening and
>> +why) of your patch, but if you need to supply even more context, you can do so
>> +below the `---` in your patch. Take the example below, generated with
>> +`git format-patch` on a single commit:
>
> It's not clear to me how `git format-patch` can generate the extra
> paragraph below. The user would either have to include "---" in the
> commit message (in which case there would be an extra "---" below the
> extra paragraph, which is perfectly safe) or edit the email *after*
> `git-format-patch` has generated the email.

Yes, I think the editions after v2 of this series has consistently
encouraged users to edit format-patch output in a separate editor
session (be it 0/n cover letter, or 1/1 single patch) before sending
it out, discouraging use of --compose in send-email or driving
format-patch from within a send-email session.

And the following example just shows how the finished result of such
an editing session would look like.

> The other meta-concern is maintaining the informal tone when we update
> this document (for example, when we add features like range-diff which
> can be used when sending v2 - well, somebody can add information about
> that to this document once it has been merged); but I don't think that
> is a concern in practice (either we keep the tone or there is a slight
> tone mismatch, and I don't think that either is a big deal).

I am OK as long as those who care about maintaining coherent tone
pay attention to changes proposed to this document in the future ;-)

Thanks for comments.  Let's finish this topic and merge it down
soonish.

Re: [PATCH v5 0/2] documentation: add lab for first contribution

[Junio C Hamano]

Emily Shaffer <emilyshaffer@google.com> writes:

> - Removed 'extern' from the addition to builtin.h

I said something that conflicts with this in my message to JTan, but
I am fine with this removal of extern, as it is reasonable that
Denton Liu's no-extern work would land soonish.

I agree with the spirit of all the other points listed in the cover
letter as well.  Thanks for working on this.

Re: [PATCH v5 1/2] documentation: add tutorial for first contribution

[Junio C Hamano]

Emily Shaffer <emilyshaffer@google.com> writes:

> +=== Clone the Git Repository
> +
> +Git is mirrored in a number of locations. Clone the repository from one of them;
> +https://git-scm.com/downloads suggests one of the best places to clone from is
> +the official mirror on GitHub.

I didn't want to have to get into fine-grained wordsmithing (let
alone bikeshedding) this late in the iteration of the topic, but
"the official mirror" is not something anybody suggested in the
recent reviews (JTan's rephrasing, which I already said that I am OK
with, said something like "one of the many mirrors").

And "official" is a phrase I have trouble with in this context.  A
mirror does not have to be blessed as official; that's the point of
a mirror---anybody can make one to help users with better
connectivity or availability, as long as its users trust the mirror
maintainer for mirror's correctness and freshness.

So perhaps "... clone from is the mirror maintained by GitHub folks"
or just simply "is the mirror on GitHub"?

> +$ git send-email --to=target@example.com
> +		 --in-reply-to="<foo.12345.author@example.com>"

Very nice attention to the detail here.  I like it (the earlier
round did not have dq around the message ID).

> +		 psuh/v2*
> +----

All other edits relative to the previous round look very sensible to
me.  Thanks.

Re: [PATCH v5 1/2] documentation: add tutorial for first contribution

[Emily Shaffer]

On Wed, May 08, 2019 at 12:46:47PM +0900, Junio C Hamano wrote:
> Emily Shaffer <emilyshaffer@google.com> writes:
> 
> > +=== Clone the Git Repository
> > +
> > +Git is mirrored in a number of locations. Clone the repository from one of them;
> > +https://git-scm.com/downloads suggests one of the best places to clone from is
> > +the official mirror on GitHub.
> 
> I didn't want to have to get into fine-grained wordsmithing (let
> alone bikeshedding) this late in the iteration of the topic, but
> "the official mirror" is not something anybody suggested in the
> recent reviews (JTan's rephrasing, which I already said that I am OK
> with, said something like "one of the many mirrors").

I should have waited longer on sending this round of patch out; as it
stands I sent the patch with this fix a few hours before your response
to JTan came out. Sorry for the confusion.

> And "official" is a phrase I have trouble with in this context.  A
> mirror does not have to be blessed as official; that's the point of
> a mirror---anybody can make one to help users with better
> connectivity or availability, as long as its users trust the mirror
> maintainer for mirror's correctness and freshness.

You're right and I'll remove it. However, I've seen at least one
instance of confusion over Git's lack of an "official" mirror (over on
#git on Freenode). I'd like to rephrase this to explain the reasoning
behind having multiple mirrors, none of which are official.

To that end, I propose replacing the phrase with "one of the best places
to clone from is this mirror on GitHub." followed by the clone command
to git/git, then followed by:

	NOTE: As Git is a distributed version control, the Git project also
	follows a distributed model. There is no central official mirror; any
	mirror which you can reasonably trust is being kept correct and fresh to
	the Git source distributed by the Git maintainer is fine to work from.

What do we think?

Alternatively, if the desire is to just be done with it, I have no
problem with Junio rewording however he feels is best and otherwise
applying this patch - if there is value in reducing the churn on the
mailing list for this patch.

> So perhaps "... clone from is the mirror maintained by GitHub folks"
> or just simply "is the mirror on GitHub"?
> 
> > +$ git send-email --to=target@example.com
> > +		 --in-reply-to="<foo.12345.author@example.com>"
> 
> Very nice attention to the detail here.  I like it (the earlier
> round did not have dq around the message ID).
> 
> > +		 psuh/v2*
> > +----
> 
> All other edits relative to the previous round look very sensible to
> me.  Thanks.

Re: [PATCH v5 1/2] documentation: add tutorial for first contribution

[Jonathan Tan]

> > And "official" is a phrase I have trouble with in this context.  A
> > mirror does not have to be blessed as official; that's the point of
> > a mirror---anybody can make one to help users with better
> > connectivity or availability, as long as its users trust the mirror
> > maintainer for mirror's correctness and freshness.
> 
> You're right and I'll remove it. However, I've seen at least one
> instance of confusion over Git's lack of an "official" mirror (over on
> #git on Freenode). I'd like to rephrase this to explain the reasoning
> behind having multiple mirrors, none of which are official.
> 
> To that end, I propose replacing the phrase with "one of the best places
> to clone from is this mirror on GitHub." followed by the clone command
> to git/git, then followed by:
> 
> 	NOTE: As Git is a distributed version control, the Git project also
> 	follows a distributed model. There is no central official mirror; any
> 	mirror which you can reasonably trust is being kept correct and fresh to
> 	the Git source distributed by the Git maintainer is fine to work from.
> 
> What do we think?

In the interest of avoiding mailing list churn, I think we should not
bother with explaining what an "official" mirror is right now, as long
as we already have steps that a newcomer can take (which we do). Someone
else can add it later if they wish.

For me, the "official" mirrors are whatever is listed in the latest "A
note from the maintainer" (e.g. [1]). Even if we want to link to this or
replicate part of its contents, I think we can do it after this patch is
merged.

(Also, with that paragraph, I don't think a newcomer should be expected
to know what mirror is reasonably trusted.)

[1] https://public-inbox.org/git/xmqqwolmcvyb.fsf@gitster-ct.c.googlers.com/

> Alternatively, if the desire is to just be done with it, I have no
> problem with Junio rewording however he feels is best and otherwise
> applying this patch - if there is value in reducing the churn on the
> mailing list for this patch.

This sounds good to me too.

[PATCH v6 0/2] documentation: add tutorial for first contribution

[Emily Shaffer]

Only minor changes since v5. Removed 'official' from the blurb about the
Github mirror, and removed some spurious braces around oneline code
branches.

Emily Shaffer (2):
  documentation: add tutorial for first contribution
  documentation: add anchors to MyFirstContribution

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

-- 
2.21.0.1020.gf2820cf01a-goog

[PATCH v6 1/2] documentation: add tutorial for first contribution

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

Reviewed-by: Johannes Schindelin <johannes.schindelin@gmx.de>
Reviewed-by: Jonathan Tan <jonathantanmy@google.com>
Signed-off-by: Emily Shaffer <emilyshaffer@google.com>
---
 Documentation/Makefile                |    1 +
 Documentation/MyFirstContribution.txt | 1074 +++++++++++++++++++++++++
 2 files changed, 1075 insertions(+)
 create mode 100644 Documentation/MyFirstContribution.txt

diff --git a/Documentation/Makefile b/Documentation/Makefile
index dbf5a0f276..76f2ecfc1b 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -76,6 +76,7 @@ SP_ARTICLES += howto/maintain-git
 API_DOCS = $(patsubst %.txt,%,$(filter-out technical/api-index-skel.txt technical/api-index.txt, $(wildcard technical/api-*.txt)))
 SP_ARTICLES += $(API_DOCS)
 
+TECH_DOCS += MyFirstContribution
 TECH_DOCS += SubmittingPatches
 TECH_DOCS += technical/hash-function-transition
 TECH_DOCS += technical/http-protocol
diff --git a/Documentation/MyFirstContribution.txt b/Documentation/MyFirstContribution.txt
new file mode 100644
index 0000000000..bc267c4931
--- /dev/null
+++ b/Documentation/MyFirstContribution.txt
@@ -0,0 +1,1074 @@
+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
+
+=== Clone the Git Repository
+
+Git is mirrored in a number of locations. Clone the repository from one of them;
+https://git-scm.com/downloads suggests one of the best places to clone from is
+the mirror on 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 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:
+
+----
+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 mimicking `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
+----
+
+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
+----
+
+You will be presented with your editor in order to write a commit message. Start
+the commit with a 50-column or less subject line, including the name of the
+component you're working on, followed by a blank line (always required) and then
+the body of your commit message, which should provide the bulk of the context.
+Remember to be explicit and provide the "Why" of 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 <author@example.com>
+----
+
+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).
+
+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 mimic 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:
+
+----
+$ make all doc
+$ man Documentation/git-psuh.1
+----
+
+or
+
+----
+$ make -C Documentation/ git-psuh.1
+$ 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
+* Prove the current behavior matches the expected behavior
+* Ensure the externally-visible behavior isn't broken in later changes
+
+So let's write some tests.
+
+Related reading: `t/README`
+
+=== Overview of Testing Structure
+
+The tests in Git live in `t/` and are named with a 4-digit decimal number using
+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
+and `git send-email`.
+
+== Sending Patches via GitGitGadget
+
+One option for sending patches is to follow a typical pull request workflow and
+send your patches out via GitGitGadget. 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 send them out for you. It also runs the Git continuous integration
+suite for you. It's documented at http://gitgitgadget.github.io.
+
+=== Forking `git/git` on GitHub
+
+Before you can send your patch off to be reviewed using GitGitGadget, you will
+need to fork the Git project and upload your changes. First thing - make sure
+you have a GitHub account.
+
+Head to the https://github.com/git/git[GitHub mirror] and look for the Fork
+button. Place your fork wherever you deem appropriate and create it.
+
+=== Uploading to Your Own Fork
+
+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 git@github.com: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`.
+
+////
+TODO https://github.com/gitgitgadget/gitgitgadget/issues/83
+It'd be nice to be able to verify that the patch looks good before sending it
+to everyone on Git mailing list.
+=== Check Your Work
+////
+
+=== Sending Your Patches
+
+Now that your CI is passing and someone has granted you permission to use
+GitGitGadget with the `/allow` command, sending out for review is as simple as
+commenting on your PR with `/submit`.
+
+=== Updating With Comments
+
+Skip ahead to <<reviewing,Responding to Reviews>> for information on how to
+reply to review comments you will receive on the mailing list.
+
+Once you have your branch again in the shape you want following all review
+comments, you can submit again:
+
+----
+$ git push -f remotename psuh
+----
+
+Next, go look at your pull request against GitGitGadget; you should see the CI
+has been kicked off again. Now while the CI is running is a good time for you
+to modify your description at the top of the pull request thread; it will be
+used again as the cover letter. You should use this space to describe what
+has changed since your previous version, so that your reviewers have some idea
+of what they're looking at. When the CI is done running, you can comment once
+more with `/submit` - GitGitGadget will automatically add a v2 mark to your
+changes.
+
+== Sending Patches with `git send-email`
+
+If you don't want to use GitGitGadget, you can also use Git itself to mail your
+patches. Some benefits of using Git this way include finer grained control of
+subject line (for example, being able to use the tag [RFC PATCH] in the subject)
+and being able to send a ``dry run'' mail to yourself to ensure it all looks
+good before going out to the list.
+
+=== Prerequisite: Setting Up `git send-email`
+
+Configuration for `send-email` can vary based on your operating system and email
+provider, and so will not be covered in this tutorial, beyond stating that in
+many distributions of Linux, `git-send-email` is not packaged alongside the
+typical `git` install. You may need to install this additional package; there
+are a number of resources online to help you do so. You will also need to
+determine the right way to configure it to use your SMTP server; again, as this
+configuration can change significantly based on your system and email setup, it
+is out of scope for the context of this tutorial.
+
+=== Preparing Initial Patchset
+
+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 --cover-letter -o psuh/ master..psuh
+----
+
+The `--cover-letter` parameter tells `format-patch` to create a cover letter
+template for you. You will need to fill in the template before you're ready
+to send - but for now, the template will be next to your other patches.
+
+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.
+
+`master..psuh` tells `format-patch` to generate patches for the difference
+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.
+
+NOTE: Optionally, you can also use the `--rfc` flag to prefix your patch subject
+with ``[RFC PATCH]'' instead of ``[PATCH]''. RFC stands for ``request for
+comments'' and indicates that while your code isn't quite ready for submission,
+you'd like to begin the code review process. This can also be used when your
+patch is a proposal, but you aren't sure whether the community wants to solve
+the problem with that approach or not - to conduct a sort of design review. You
+may also see on the list patches marked ``WIP'' - this means they are incomplete
+but want reviewers to look at what they have so far. You can add this flag with
+`--subject-prefix=WIP`.
+
+Check and make sure that your patches and cover letter template exist in the
+directory you specified - you're nearly ready to send out your review!
+
+=== Preparing Email
+
+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). Since you invoked `format-patch`
+with `--cover-letter`, you've already got a template ready. Open it up in your
+favorite editor.
+
+You should see a number of headers present already. Check that your `From:`
+header is correct. Then modify your `Subject:` to something which succinctly
+covers the purpose of your entire topic branch, for example:
+
+----
+Subject: [PATCH 0/7] adding the 'psuh' command
+----
+
+Make sure you retain the ``[PATCH 0/X]'' part; that's what indicates to the Git
+community that this email is the beginning of a review, and many reviewers
+filter their email for this type of flag.
+
+You'll need to add some extra parameters when you invoke `git send-email` to add
+the cover letter.
+
+Next you'll have to fill out the body of your cover letter. This is an important
+component of change submission as it explains to the community from a high level
+what you're trying to do, and why, in a way that's more apparent than just
+looking at your diff. Be sure to explain anything your diff doesn't make clear
+on its own.
+
+Here's an example body for `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 tutorial and should not
+be merged.
+----
+
+The template created by `git format-patch --cover-letter` includes a diffstat.
+This gives reviewers a summary of what they're in for when reviewing your topic.
+The one generated for `psuh` from the sample implementation looks like this:
+
+----
+ Documentation/git-psuh.txt | 40 +++++++++++++++++++++
+ Makefile                   |  1 +
+ builtin.h                  |  1 +
+ builtin/psuh.c             | 73 ++++++++++++++++++++++++++++++++++++++
+ git.c                      |  1 +
+ t/t9999-psuh-tutorial.sh   | 12 +++++++
+ 6 files changed, 128 insertions(+)
+ create mode 100644 Documentation/git-psuh.txt
+ create mode 100644 builtin/psuh.c
+ create mode 100755 t/t9999-psuh-tutorial.sh
+----
+
+Finally, the letter will include the version of Git used to generate the
+patches. You can leave that string alone.
+
+=== Sending Email
+
+At this point you should have a directory `psuh/` which is filled with your
+patches and a cover letter. Time to mail it out! You can send it like this:
+
+----
+$ git send-email --to=target@example.com psuh/*.patch
+----
+
+NOTE: Check `git help send-email` for some other options which you may find
+valuable, such as changing the Reply-to address or adding more CC and BCC lines.
+
+NOTE: When you are sending a real patch, it will go to git@vger.kernel.org - but
+please don't send your patchset from the tutorial to the real mailing list! For
+now, you can send it to yourself, to make sure you understand how it will look.
+
+After you run the command above, 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 be sent! Congratulations!
+
+Awesome, now the community will drop everything and review your changes. (Just
+kidding - be patient!)
+
+=== Sending v2
+
+Skip ahead to <<reviewing,Responding to Reviews>> for information on how to
+handle comments from reviewers. Continue this section when your topic branch is
+shaped the way you want it to look for your patchset v2.
+
+When you're ready with the next iteration of your patch, the process is fairly
+similar.
+
+First, generate your v2 patches again:
+
+----
+$ git format-patch -v2 --cover-letter -o psuh/ master..psuh
+----
+
+This will add your v2 patches, all named like `v2-000n-my-commit-subject.patch`,
+to the `psuh/` directory. You may notice that they are sitting alongside the v1
+patches; that's fine, but be careful when you are ready to send them.
+
+Edit your cover letter again. Now is a good time to mention what's different
+between your last version and now, if it's something significant. You do not
+need the exact same body in your second cover letter; focus on explaining to
+reviewers the changes you've made that may not be as visible.
+
+You will also need to go and find the Message-Id of your previous cover letter.
+You can either note it when you send the first series, from the output of `git
+send-email`, or you can look it up on the
+https://public-inbox.org/git[mailing list]. Find your cover letter in the
+archives, click on it, then click "permalink" or "raw" to reveal the Message-Id
+header. It should match:
+
+----
+Message-Id: <foo.12345.author@example.com>
+----
+
+Your Message-Id is `<foo.12345.author@example.com>`. This example will be used
+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.
+
+While you're looking at the email, you should also note who is CC'd, as it's
+common practice in the mailing list to keep all CCs on a thread. You can add
+these CC lines directly to your cover letter with a line like so in the header
+(before the Subject line):
+
+----
+CC: author@example.com, Othe R <other@example.com>
+----
+
+Now send the emails again, paying close attention to which messages you pass in
+to the command:
+
+----
+$ git send-email --to=target@example.com
+		 --in-reply-to="<foo.12345.author@example.com>"
+		 psuh/v2*
+----
+
+=== 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
+meaningful and explain at a high level the purpose (what is happening and why)
+of your patch, but if you need to supply even more context, you can do so below
+the `---` in your patch. Take the example below, which was generated with `git
+format-patch` on a single commit, and then edited to add the content between
+the `---` and the diffstat.
+
+----
+From 1345bbb3f7ac74abde040c12e737204689a72723 Mon Sep 17 00:00:00 2001
+From: A U Thor <author@example.com>
+Date: Thu, 18 Apr 2019 15:11:02 -0700
+Subject: [PATCH] README: change the grammar
+
+I think it looks better this way. This part of the commit message will
+end up in the commit-log.
+
+Signed-off-by: A U Thor <author@example.com>
+---
+Let's have a wild discussion about grammar on the mailing list. This
+part of my email will never end up in the commit log. Here is where I
+can add additional context to the mailing list about my intent, outside
+of the context of the commit log. This section was added after `git
+format-patch` was run, by editing the patch file in a text editor.
+
+ README.md | 2 +-
+ 1 file changed, 1 insertion(+), 1 deletion(-)
+
+diff --git a/README.md b/README.md
+index 88f126184c..38da593a60 100644
+--- a/README.md
++++ b/README.md
+@@ -3,7 +3,7 @@
+ Git - fast, scalable, distributed revision control system
+ =========================================================
+
+-Git is a fast, scalable, distributed revision control system with an
++Git is a fast, scalable, and distributed revision control system with an
+ unusually rich command set that provides both high-level operations
+ and full access to internals.
+
+--
+2.21.0.392.gf8f6787159e-goog
+----
+
+== My Patch Got Emailed - Now What?
+
+[[reviewing]]
+=== Responding to Reviews
+
+After a few days, you will hopefully receive a reply to your patchset with some
+comments. Woohoo! Now you can get back to work.
+
+It's good manners to reply to each comment, notifying the reviewer that you have
+made the change requested, feel the original is better, or that the comment
+inspired you to do something a new way which is superior to both the original
+and the suggested change. This way reviewers don't need to inspect your v2 to
+figure out whether you implemented their comment or not.
+
+If you are going to push back on a comment, be polite and explain why you feel
+your original is better; be prepared that the reviewer may still disagree with
+you, and the rest of the community may weigh in on one side or the other. As
+with all code reviews, it's important to keep an open mind to doing something a
+different way than you originally planned; other reviewers have a different
+perspective on the project than you do, and may be thinking of a valid side
+effect which had not occurred to you. It is always okay to ask for clarification
+if you aren't sure why a change was suggested, or what the reviewer is asking
+you to do.
+
+Make sure your email client has a plaintext email mode and it is turned on; 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.
+
+When you're making changes to your code, it is cleanest - that is, the resulting
+commits are easiest to look at - if you use `git rebase -i` (interactive
+rebase). Take a look at this
+https://www.oreilly.com/library/view/git-pocket-guide/9781449327507/ch10.html[overview]
+from O'Reilly. The general idea is to modify each commit which requires changes;
+this way, instead of having a patch A with a mistake, a patch B which was fine
+and required no upstream reviews in v1, and a patch C which fixes patch A for
+v2, you can just ship a v2 with a correct patch A and correct patch B. This is
+changing history, but since it's local history which you haven't shared with
+anyone, that is okay for now! (Later, it may not make sense to do this; take a
+look at the section below this one for some context.)
+
+=== After Review Approval
+
+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.
+
+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 merge your topic branch to `next` and life is good.
+
+However, if you discover it isn't so perfect after this point, you may need to
+take some special steps depending on where you are in the process.
+
+If the maintainer has announced in the "What's cooking in git.git" email that
+your topic is marked for `next` - that is, that they plan to merge it to `next`
+but have not yet done so - you should send an email asking the maintainer to
+wait a little longer: "I've sent v4 of my series and you marked it for `next`,
+but I need to change this and that - please wait for v5 before you merge it."
+
+If the topic has already been merged to `next`, rather than modifying your
+patches with `git rebase -i`, you should make further changes incrementally -
+that is, with another commit, based on top of the maintainer's topic branch as
+detailed in https://github.com/gitster/git. Your work is still in the same topic
+but is now incremental, rather than a wholesale rewrite of the topic branch.
+
+The topic branches in the maintainer's GitHub are mirrored in GitGitGadget, so
+if you're sending your reviews out that way, you should be sure to open your PR
+against the appropriate GitGitGadget/Git branch.
+
+If you're using `git send-email`, you can use it the same way as before, but you
+should generate your diffs from `<topic>..<mybranch>` and base your work on
+`<topic>` instead of `master`.
-- 
2.21.0.1020.gf2820cf01a-goog

[PATCH v6 2/2] documentation: add anchors to MyFirstContribution

[Emily Shaffer]

During the course of review for MyFirstContribution.txt, the suggestion
came up to include anchors to make it easier for veteran contributors to
link specific sections of this documents to newbies. To make life easier
for reviewers, add these anchors in their own commit. See review context
here: https://public-inbox.org/git/20190507195938.GD220818@google.com/

AsciiDoc does not support :sectanchors: and the anchors are not
discoverable, but they are referenceable. So a link to
"foo.com/MyFirstContribution.html#prerequisites" will still work if that
file was generated with AsciiDoc. The inclusion of :sectanchors: does
not create warnings or errors while compiling directly with `asciidoc -b
html5 Documentation/MyFirstContribution.txt` or while compiling with
`make doc`.

AsciiDoctor does support :sectanchors: and displays a paragraph link on
mouseover. When the anchor is included above or inline with a section
(as in this change), the link provided points to the custom ID contained
within [[]] instead of to an autogenerated ID. Practically speaking,
this means we have .../MyFirstContribution.html#summary instead of
.../MyFirstContribution.html#_summary. In addition to being prettier,
the custom IDs also enable anchor linking to work with
asciidoc-generated pages. This change compiles with no warnings using
`asciidoctor -b html5 Documentation/MyFirstContribution.txt`.

Signed-off-by: Emily Shaffer <emilyshaffer@google.com>
---
 Documentation/MyFirstContribution.txt | 35 +++++++++++++++++++++++++++
 1 file changed, 35 insertions(+)

diff --git a/Documentation/MyFirstContribution.txt b/Documentation/MyFirstContribution.txt
index bc267c4931..274df8575b 100644
--- a/Documentation/MyFirstContribution.txt
+++ b/Documentation/MyFirstContribution.txt
@@ -1,16 +1,20 @@
 My First Contribution to the Git Project
 ========================================
+:sectanchors:
 
+[[summary]]
 == 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]]
 === 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]]
 === Related Reading
 
 This tutorial aims to summarize the following documents, but the reader may find
@@ -19,8 +23,10 @@ useful additional context:
 - `Documentation/SubmittingPatches`
 - `Documentation/howto/new-command.txt`
 
+[[getting-started]]
 == Getting Started
 
+[[cloning]]
 === Clone the Git Repository
 
 Git is mirrored in a number of locations. Clone the repository from one of them;
@@ -31,6 +37,7 @@ the mirror on GitHub.
 $ git clone https://github.com/git/git git
 ----
 
+[[identify-problem]]
 === Identify Problem to Solve
 
 ////
@@ -44,6 +51,7 @@ 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`.)
 
+[[setup-workspace]]
 === Set Up Your Workspace
 
 Let's start by making a development branch to work on our changes. Per
@@ -62,11 +70,13 @@ $ 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]]
 == Code It Up!
 
 NOTE: A reference implementation can be found at
 https://github.com/nasamuffin/git/tree/psuh.
 
+[[add-new-command]]
 === Adding a New Command
 
 Lots of the subcommands are written as builtins, which means they are
@@ -195,6 +205,7 @@ 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]]
 === Implementation
 
 It's probably useful to do at least something besides printing out a string.
@@ -358,6 +369,7 @@ about. Neat! Let's commit that as well.
 $ git commit -sm "psuh: display the top of origin/master"
 ----
 
+[[add-documentation]]
 === Adding Documentation
 
 Awesome! You've got a fantastic new command that you're ready to share with the
@@ -445,6 +457,7 @@ sees that your command has been implemented as well as documented) by running
 
 Go ahead and commit your new documentation change.
 
+[[add-usage]]
 === Adding Usage Text
 
 Try and run `./bin-wrappers/git psuh -h`. Your command should crash at the end.
@@ -501,6 +514,7 @@ your command terminated before anything else interesting happens. Great!
 
 Go ahead and commit this one, too.
 
+[[testing]]
 == Testing
 
 It's important to test your code - even for a little toy command like this one.
@@ -515,11 +529,13 @@ So let's write some tests.
 
 Related reading: `t/README`
 
+[[overview-test-structure]]
 === Overview of Testing Structure
 
 The tests in Git live in `t/` and are named with a 4-digit decimal number using
 the schema shown in the Naming Tests section of `t/README`.
 
+[[write-new-test]]
 === Writing Your Test
 
 Since this a toy command, let's go ahead and name the test with t9999. However,
@@ -568,6 +584,7 @@ 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.
 
+[[local-test]]
 === Running Locally
 
 Let's try and run locally:
@@ -591,6 +608,7 @@ dependencies. `prove` also makes the output nicer.
 
 Go ahead and commit this change, as well.
 
+[[ready-to-share]]
 == Getting Ready to Share
 
 You may have noticed already that the Git project performs its code reviews via
@@ -613,6 +631,7 @@ 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
 and `git send-email`.
 
+[[howto-ggg]]
 == Sending Patches via GitGitGadget
 
 One option for sending patches is to follow a typical pull request workflow and
@@ -623,6 +642,7 @@ mirror of the Git project, and does some magic to turn the PR into a set of
 emails and send them out for you. It also runs the Git continuous integration
 suite for you. It's documented at http://gitgitgadget.github.io.
 
+[[create-fork]]
 === Forking `git/git` on GitHub
 
 Before you can send your patch off to be reviewed using GitGitGadget, you will
@@ -632,6 +652,7 @@ you have a GitHub account.
 Head to the https://github.com/git/git[GitHub mirror] and look for the Fork
 button. Place your fork wherever you deem appropriate and create it.
 
+[[upload-to-fork]]
 === Uploading to Your Own Fork
 
 To upload your branch to your own fork, you'll need to add the new fork as a
@@ -677,6 +698,7 @@ $ git push remotename psuh
 
 Now you should be able to go and check out your newly created branch on GitHub.
 
+[[send-pr-ggg]]
 === Sending a PR to GitGitGadget
 
 In order to have your code tested and formatted for review, you need to start by
@@ -688,6 +710,7 @@ 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.
 
+[[run-ci-ggg]]
 === Running CI and Getting Ready to Send
 
 If it's your first time using GitGitGadget (which is likely, as you're using
@@ -712,15 +735,18 @@ your patch is accepted into `next`.
 TODO https://github.com/gitgitgadget/gitgitgadget/issues/83
 It'd be nice to be able to verify that the patch looks good before sending it
 to everyone on Git mailing list.
+[[check-work-ggg]]
 === Check Your Work
 ////
 
+[[send-mail-ggg]]
 === Sending Your Patches
 
 Now that your CI is passing and someone has granted you permission to use
 GitGitGadget with the `/allow` command, sending out for review is as simple as
 commenting on your PR with `/submit`.
 
+[[responding-ggg]]
 === Updating With Comments
 
 Skip ahead to <<reviewing,Responding to Reviews>> for information on how to
@@ -742,6 +768,7 @@ of what they're looking at. When the CI is done running, you can comment once
 more with `/submit` - GitGitGadget will automatically add a v2 mark to your
 changes.
 
+[[howto-git-send-email]]
 == Sending Patches with `git send-email`
 
 If you don't want to use GitGitGadget, you can also use Git itself to mail your
@@ -750,6 +777,7 @@ subject line (for example, being able to use the tag [RFC PATCH] in the subject)
 and being able to send a ``dry run'' mail to yourself to ensure it all looks
 good before going out to the list.
 
+[[setup-git-send-email]]
 === Prerequisite: Setting Up `git send-email`
 
 Configuration for `send-email` can vary based on your operating system and email
@@ -761,6 +789,7 @@ determine the right way to configure it to use your SMTP server; again, as this
 configuration can change significantly based on your system and email setup, it
 is out of scope for the context of this tutorial.
 
+[[format-patch]]
 === Preparing Initial Patchset
 
 Sending emails with Git is a two-part process; before you can prepare the emails
@@ -799,6 +828,7 @@ but want reviewers to look at what they have so far. You can add this flag with
 Check and make sure that your patches and cover letter template exist in the
 directory you specified - you're nearly ready to send out your review!
 
+[[cover-letter]]
 === Preparing Email
 
 In addition to an email per patch, the Git community also expects your patches
@@ -862,6 +892,7 @@ The one generated for `psuh` from the sample implementation looks like this:
 Finally, the letter will include the version of Git used to generate the
 patches. You can leave that string alone.
 
+[[sending-git-send-email]]
 === Sending Email
 
 At this point you should have a directory `psuh/` which is filled with your
@@ -886,6 +917,7 @@ press `y` or `a` at these prompts your emails will be sent! Congratulations!
 Awesome, now the community will drop everything and review your changes. (Just
 kidding - be patient!)
 
+[[v2-git-send-email]]
 === Sending v2
 
 Skip ahead to <<reviewing,Responding to Reviews>> for information on how to
@@ -944,6 +976,7 @@ $ git send-email --to=target@example.com
 		 psuh/v2*
 ----
 
+[[single-patch]]
 === Bonus Chapter: One-Patch Changes
 
 In some cases, your very small change may consist of only one patch. When that
@@ -991,6 +1024,7 @@ index 88f126184c..38da593a60 100644
 2.21.0.392.gf8f6787159e-goog
 ----
 
+[[now-what]]
 == My Patch Got Emailed - Now What?
 
 [[reviewing]]
@@ -1034,6 +1068,7 @@ changing history, but since it's local history which you haven't shared with
 anyone, that is okay for now! (Later, it may not make sense to do this; take a
 look at the section below this one for some context.)
 
+[[after-approval]]
 === After Review Approval
 
 The Git project has four integration branches: `pu`, `next`, `master`, and
-- 
2.21.0.1020.gf2820cf01a-goog

Re: [PATCH v6 1/2] documentation: add tutorial for first contribution

[Christian Couder]

On Fri, May 17, 2019 at 11:48 PM Emily Shaffer <emilyshaffer@google.com> wrote:
>
> 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.

Very nice, thanks! I tried it and I liked it very much.

I noted a few nits that might help improve it a bit.

> +----
> +$ git clone https://github.com/git/git git

Nit: maybe add "$ cd git" after that.

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

Nit: when building a "git-psuh" binary is created at the root of the
repo which will pollute the `git status` output. The usual way we deal
with that is by adding "/git-psuh" to the ".gitignore" at the root of
the repo.

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

Nit: maybe it could be a bit more clear that the previous printf()
call should be kept as is, otherwise the test added later will fail.

> +----
> +       const char *cfg_name;
> +
> +...
> +
> +       git_config(git_default_config, NULL)

Nit: a ";" is missing at the end of the above line.

> +Let's commit this as well.
> +
> +----
> +$ git commit -sm "psuh: print the current branch"

Nit: maybe add "builtin/psuh.c" at the end of the above line, so that
a `git add builtin/psuh.c` is not needed.

> +....
> +git-psuh(1)
> +===========
> +
> +NAME
> +----
> +git-psuh - Delight users' typo with a shy horse
> +
> +
> +SYNOPSIS
> +--------
> +[verse]
> +'git-psuh'
> +
> +DESCRIPTION
> +-----------
> +...
> +
> +OPTIONS[[OPTIONS]]
> +------------------
> +...
> +
> +OUTPUT
> +------
> +...
> +
> +

Nit: it seems that the above newline could be removed.

Thanks,
Christian.

Re: [PATCH v6 1/2] documentation: add tutorial for first contribution

[Emily Shaffer]

On Sun, May 26, 2019 at 09:48:26AM +0200, Christian Couder wrote:
> On Fri, May 17, 2019 at 11:48 PM Emily Shaffer <emilyshaffer@google.com> wrote:
> >
> > 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.
> 
> Very nice, thanks! I tried it and I liked it very much.
> 
> I noted a few nits that might help improve it a bit.
> 
> > +----
> > +$ git clone https://github.com/git/git git
> 
> Nit: maybe add "$ cd git" after that.

Sure, done.

> 
> > +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
> > +----
> 
> Nit: when building a "git-psuh" binary is created at the root of the
> repo which will pollute the `git status` output. The usual way we deal
> with that is by adding "/git-psuh" to the ".gitignore" at the root of
> the repo.

Right you are - good catch. I'll add a paragraph about adding to the
gitignore.
> 
> > +=== 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:
> 
> Nit: maybe it could be a bit more clear that the previous printf()
> call should be kept as is, otherwise the test added later will fail.

Done.

> 
> > +----
> > +       const char *cfg_name;
> > +
> > +...
> > +
> > +       git_config(git_default_config, NULL)
> 
> Nit: a ";" is missing at the end of the above line.

Yikes, done.

> 
> > +Let's commit this as well.
> > +
> > +----
> > +$ git commit -sm "psuh: print the current branch"
> 
> Nit: maybe add "builtin/psuh.c" at the end of the above line, so that
> a `git add builtin/psuh.c` is not needed.

This is purely personal preference, but I prefer manually adding files
first. I didn't add any indication about staging the changes to psuh.c
though, so I'm adding a line to `git add builtin/psuh.c`. I found one
other place where the commit line was shown without the add line, so I
included the add there too.

> 
> > +....
> > +git-psuh(1)
> > +===========
> > +
> > +NAME
> > +----
> > +git-psuh - Delight users' typo with a shy horse
> > +
> > +
> > +SYNOPSIS
> > +--------
> > +[verse]
> > +'git-psuh'
> > +
> > +DESCRIPTION
> > +-----------
> > +...
> > +
> > +OPTIONS[[OPTIONS]]
> > +------------------
> > +...
> > +
> > +OUTPUT
> > +------
> > +...
> > +
> > +
> 
> Nit: it seems that the above newline could be removed.


Sure, why not.

> 
> Thanks,
> Christian.

Thanks for trying it out and for your thorough review, Christian. I
appreciate it! Since this is checked into next already, I'll be sending
a follow-on patch in reply to my last version in this thread which is
based on the tip of next.

 - Emily

[PATCH] doc: add some nit fixes to MyFirstContribution

[Emily Shaffer]

A trial run-through of the tutorial revealed a few typos and missing
commands in the tutorial itself. This commit fixes typos, clarifies
which lines to keep or modify in some places, and adds a section on
putting the git-psuh binary into the gitignore.

Signed-off-by: Emily Shaffer <emilyshaffer@google.com>
---
This patch is based on next, as the doc hasn't made it to master yet.

- Missing `cd git` after cloning the repo
- Documented how to add git-psuh to the gitignore
- Documented the need to leave prior printfs in place during the
  tutorial
- Typos: missing ;, stray newline
- Missing `git add builtin/psuh.c` in a couple of places; this could
  also have been done by adding the filename to the end of the commit
  call, but I don't think that's a good habit (as opposed to staging all
  changes, inspecting the wt state, and then committing). Open for
  debate.

Big thanks to Christian for the trial run and review.

 - Emily

 Documentation/MyFirstContribution.txt | 31 +++++++++++++++++++++++----
 1 file changed, 27 insertions(+), 4 deletions(-)

diff --git a/Documentation/MyFirstContribution.txt b/Documentation/MyFirstContribution.txt
index 274df8575b..895b7cfd4f 100644
--- a/Documentation/MyFirstContribution.txt
+++ b/Documentation/MyFirstContribution.txt
@@ -35,6 +35,7 @@ the mirror on GitHub.
 
 ----
 $ git clone https://github.com/git/git git
+$ cd git
 ----
 
 [[identify-problem]]
@@ -164,8 +165,28 @@ $ ./bin-wrappers/git psuh
 
 Check it out! You've got a command! Nice work! Let's commit this.
 
+`git status` reveals modified `Makefile`, `builtin.h`, and `git.c` as well as
+untracked `builtin/psuh.c` and `git-psuh`. First, let's take care of the binary,
+which should be ignored. Open `.gitignore` in your editor, find `/git-push`, and
+add an entry for your new command in alphabetical order:
+
+----
+...
+/git-prune-packed
+/git-psuh
+/git-pull
+/git-push
+/git-quiltimport
+/git-range-diff
+...
+----
+
+Checking `git status` again should show that `git-psuh` has been removed from
+the untracked list and `.gitignore` has been added to the modified list. Now we
+can stage and commit:
+
 ----
-$ git add Makefile builtin.h builtin/psuh.c git.c
+$ git add Makefile builtin.h builtin/psuh.c git.c .gitignore
 $ git commit -s
 ----
 
@@ -211,7 +232,8 @@ on the reference implementation linked at the top of this document.
 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:
+Modify your `cmd_psuh` implementation to dump the args you're passed, keeping
+existing `printf()` calls in place:
 
 ----
 	int i;
@@ -243,7 +265,7 @@ function body:
 
 ...
 
-	git_config(git_default_config, NULL)
+	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
@@ -315,6 +337,7 @@ Run it again. Check it out - here's the (verbose) name of your current branch!
 Let's commit this as well.
 
 ----
+$ git add builtin/psuh.c
 $ git commit -sm "psuh: print the current branch"
 ----
 
@@ -366,6 +389,7 @@ see the subject line of the most recent commit in `origin/master` that you know
 about. Neat! Let's commit that as well.
 
 ----
+$ git add builtin/psuh.c
 $ git commit -sm "psuh: display the top of origin/master"
 ----
 
@@ -418,7 +442,6 @@ OUTPUT
 ------
 ...
 
-
 GIT
 ---
 Part of the linkgit:git[1] suite
-- 
2.22.0.rc1.257.g3120a18244-goog

Re: [PATCH v6 1/2] documentation: add tutorial for first contribution

[SZEDER Gábor]

On Fri, May 17, 2019 at 12:07:02PM -0700, Emily Shaffer wrote:
> +=== 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 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:
> +
> +----
> +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 mimicking `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.

Just leaving a quick note here: an entry about the new command should
be added to 'command-list.txt' as well, so it will be included in the
list of available commands in 'git help -a' or even in 'git help'
and in completion, if the command is marked with the necessary
attributes.
 

Re: [PATCH v6 1/2] documentation: add tutorial for first contribution

[Emily Shaffer]

On Fri, Oct 18, 2019 at 06:40:27PM +0200, SZEDER Gábor wrote:
> 
> Just leaving a quick note here: an entry about the new command should
> be added to 'command-list.txt' as well, so it will be included in the
> list of available commands in 'git help -a' or even in 'git help'
> and in completion, if the command is marked with the necessary
> attributes.
>  

Yeah, I agree - I didn't know about this until fairly recently, and I
want to highlight it!

I have at least one other change I want to send for this document in the
coming week, so I'll try and make a change for this too. Thanks for the
callout, SZEDER.

 - Emily