| Message ID | 8b71fe78719aa40feee509e6a6229775daa79a2f.1555007520.git.gitgitgadget@gmail.com (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
| Series | documentation: add lab for first contribution | expand |
"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.
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 <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.
> >> ... 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.
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?)