76644e3268 · matheusbsbs/matheus-bagliano

@@ -0,0 +1,1074 @@

1 +My First Contribution to the Git Project

2 +========================================

3 +

4 +== Summary

5 +

6 +This is a tutorial demonstrating the end-to-end workflow of creating a change to

7 +the Git tree, sending it for review, and making changes based on comments.

8 +

9 +=== Prerequisites

10 +

11 +This tutorial assumes you're already fairly familiar with using Git to manage

12 +source code. The Git workflow steps will largely remain unexplained.

13 +

14 +=== Related Reading

15 +

16 +This tutorial aims to summarize the following documents, but the reader may find

17 +useful additional context:

18 +

19 +- `Documentation/SubmittingPatches`

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

21 +

22 +== Getting Started

23 +

24 +=== Clone the Git Repository

25 +

26 +Git is mirrored in a number of locations. Clone the repository from one of them;

27 +https://git-scm.com/downloads suggests one of the best places to clone from is

28 +the mirror on GitHub.

29 +

30 +----

31 +$ git clone https://github.com/git/git git

32 +----

33 +

34 +=== Identify Problem to Solve

35 +

36 +////

37 +Use + to indicate fixed-width here; couldn't get ` to work nicely with the

38 +quotes around "Pony Saying 'Um, Hello'".

39 +////

40 +In this tutorial, we will add a new command, +git psuh+, short for ``Pony Saying

41 +`Um, Hello''' - a feature which has gone unimplemented despite a high frequency

42 +of invocation during users' typical daily workflow.

43 +

44 +(We've seen some other effort in this space with the implementation of popular

45 +commands such as `sl`.)

46 +

47 +=== Set Up Your Workspace

48 +

49 +Let's start by making a development branch to work on our changes. Per

50 +`Documentation/SubmittingPatches`, since a brand new command is a new feature,

51 +it's fine to base your work on `master`. However, in the future for bugfixes,

52 +etc., you should check that document and base it on the appropriate branch.

53 +

54 +For the purposes of this document, we will base all our work on the `master`

55 +branch of the upstream project. Create the `psuh` branch you will use for

56 +development like so:

57 +

58 +----

59 +$ git checkout -b psuh origin/master

60 +----

61 +

62 +We'll make a number of commits here in order to demonstrate how to send a topic

63 +with multiple patches up for review simultaneously.

64 +

65 +== Code It Up!

66 +

67 +NOTE: A reference implementation can be found at

68 +https://github.com/nasamuffin/git/tree/psuh.

69 +

70 +=== Adding a New Command

71 +

72 +Lots of the subcommands are written as builtins, which means they are

73 +implemented in C and compiled into the main `git` executable. Implementing the

74 +very simple `psuh` command as a built-in will demonstrate the structure of the

75 +codebase, the internal API, and the process of working together as a contributor

76 +with the reviewers and maintainer to integrate this change into the system.

77 +

78 +Built-in subcommands are typically implemented in a function named "cmd_"

79 +followed by the name of the subcommand, in a source file named after the

80 +subcommand and contained within `builtin/`. So it makes sense to implement your

81 +command in `builtin/psuh.c`. Create that file, and within it, write the entry

82 +point for your command in a function matching the style and signature:

83 +

84 +----

85 +int cmd_psuh(int argc, const char **argv, const char *prefix)

86 +----

87 +

88 +We'll also need to add the declaration of psuh; open up `builtin.h`, find the

89 +declaration for `cmd_push`, and add a new line for `psuh` immediately before it,

90 +in order to keep the declarations sorted:

91 +

92 +----

93 +int cmd_psuh(int argc, const char **argv, const char *prefix);

94 +----

95 +

96 +Be sure to `#include "builtin.h"` in your `psuh.c`.

97 +

98 +Go ahead and add some throwaway printf to that function. This is a decent

99 +starting point as we can now add build rules and register the command.

100 +

101 +NOTE: Your throwaway text, as well as much of the text you will be adding over

102 +the course of this tutorial, is user-facing. That means it needs to be

103 +localizable. Take a look at `po/README` under "Marking strings for translation".

104 +Throughout the tutorial, we will mark strings for translation as necessary; you

105 +should also do so when writing your user-facing commands in the future.

106 +

107 +----

108 +int cmd_psuh(int argc, const char **argv, const char *prefix)

109 +{

110 + printf(_("Pony saying hello goes here.\n"));

111 + return 0;

112 +}

113 +----

114 +

115 +Let's try to build it. Open `Makefile`, find where `builtin/push.o` is added

116 +to `BUILTIN_OBJS`, and add `builtin/psuh.o` in the same way next to it in

117 +alphabetical order. Once you've done so, move to the top-level directory and

118 +build simply with `make`. Also add the `DEVELOPER=1` variable to turn on

119 +some additional warnings:

120 +

121 +----

122 +$ echo DEVELOPER=1 >config.mak

123 +$ make

124 +----

125 +

126 +NOTE: When you are developing the Git project, it's preferred that you use the

127 +`DEVELOPER` flag; if there's some reason it doesn't work for you, you can turn

128 +it off, but it's a good idea to mention the problem to the mailing list.

129 +

130 +NOTE: The Git build is parallelizable. `-j#` is not included above but you can

131 +use it as you prefer, here and elsewhere.

132 +

133 +Great, now your new command builds happily on its own. But nobody invokes it.

134 +Let's change that.

135 +

136 +The list of commands lives in `git.c`. We can register a new command by adding

137 +a `cmd_struct` to the `commands[]` array. `struct cmd_struct` takes a string

138 +with the command name, a function pointer to the command implementation, and a

139 +setup option flag. For now, let's keep mimicking `push`. Find the line where

140 +`cmd_push` is registered, copy it, and modify it for `cmd_psuh`, placing the new

141 +line in alphabetical order.

142 +

143 +The options are documented in `builtin.h` under "Adding a new built-in." Since

144 +we hope to print some data about the user's current workspace context later,

145 +we need a Git directory, so choose `RUN_SETUP` as your only option.

146 +

147 +Go ahead and build again. You should see a clean build, so let's kick the tires

148 +and see if it works. There's a binary you can use to test with in the

149 +`bin-wrappers` directory.

150 +

151 +----

152 +$ ./bin-wrappers/git psuh

153 +----

154 +

155 +Check it out! You've got a command! Nice work! Let's commit this.

156 +

157 +----

158 +$ git add Makefile builtin.h builtin/psuh.c git.c

159 +$ git commit -s

160 +----

161 +

162 +You will be presented with your editor in order to write a commit message. Start

163 +the commit with a 50-column or less subject line, including the name of the

164 +component you're working on, followed by a blank line (always required) and then

165 +the body of your commit message, which should provide the bulk of the context.

166 +Remember to be explicit and provide the "Why" of your change, especially if it

167 +couldn't easily be understood from your diff. When editing your commit message,

168 +don't remove the Signed-off-by line which was added by `-s` above.

169 +

170 +----

171 +psuh: add a built-in by popular demand

172 +

173 +Internal metrics indicate this is a command many users expect to be

174 +present. So here's an implementation to help drive customer

175 +satisfaction and engagement: a pony which doubtfully greets the user,

176 +or, a Pony Saying "Um, Hello" (PSUH).

177 +

178 +This commit message is intentionally formatted to 72 columns per line,

179 +starts with a single line as "commit message subject" that is written as

180 +if to command the codebase to do something (add this, teach a command

181 +that). The body of the message is designed to add information about the

182 +commit that is not readily deduced from reading the associated diff,

183 +such as answering the question "why?".

184 +

185 +Signed-off-by: A U Thor <author@example.com>

186 +----

187 +

188 +Go ahead and inspect your new commit with `git show`. "psuh:" indicates you

189 +have modified mainly the `psuh` command. The subject line gives readers an idea

190 +of what you've changed. The sign-off line (`-s`) indicates that you agree to

191 +the Developer's Certificate of Origin 1.1 (see the

192 +`Documentation/SubmittingPatches` +++[[dco]]+++ header).

193 +

194 +For the remainder of the tutorial, the subject line only will be listed for the

195 +sake of brevity. However, fully-fleshed example commit messages are available

196 +on the reference implementation linked at the top of this document.

197 +

198 +=== Implementation

199 +

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

201 +Let's start by having a look at everything we get.

202 +

203 +Modify your `cmd_psuh` implementation to dump the args you're passed:

204 +

205 +----

206 + int i;

207 +

208 + ...

209 +

210 + printf(Q_("Your args (there is %d):\n",

211 + "Your args (there are %d):\n",

212 + argc),

213 + argc);

214 + for (i = 0; i < argc; i++)

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

216 +

217 + printf(_("Your current working directory:\n<top-level>%s%s\n"),

218 + prefix ? "/" : "", prefix ? prefix : "");

219 +

220 +----

221 +

222 +Build and try it. As you may expect, there's pretty much just whatever we give

223 +on the command line, including the name of our command. (If `prefix` is empty

224 +for you, try `cd Documentation/ && ../bin-wrappers/git psuh`). That's not so

225 +helpful. So what other context can we get?

226 +

227 +Add a line to `#include "config.h"`. Then, add the following bits to the

228 +function body:

229 +

230 +----

231 + const char *cfg_name;

232 +

233 +...

234 +

235 + git_config(git_default_config, NULL)

236 + if (git_config_get_string_const("user.name", &cfg_name) > 0)

237 + printf(_("No name is found in config\n"));

238 + else

239 + printf(_("Your name: %s\n"), cfg_name);

240 +----

241 +

242 +`git_config()` will grab the configuration from config files known to Git and

243 +apply standard precedence rules. `git_config_get_string_const()` will look up

244 +a specific key ("user.name") and give you the value. There are a number of

245 +single-key lookup functions like this one; you can see them all (and more info

246 +about how to use `git_config()`) in `Documentation/technical/api-config.txt`.

247 +

248 +You should see that the name printed matches the one you see when you run:

249 +

250 +----

251 +$ git config --get user.name

252 +----

253 +

254 +Great! Now we know how to check for values in the Git config. Let's commit this

255 +too, so we don't lose our progress.

256 +

257 +----

258 +$ git add builtin/psuh.c

259 +$ git commit -sm "psuh: show parameters & config opts"

260 +----

261 +

262 +NOTE: Again, the above is for sake of brevity in this tutorial. In a real change

263 +you should not use `-m` but instead use the editor to write a meaningful

264 +message.

265 +

266 +Still, it'd be nice to know what the user's working context is like. Let's see

267 +if we can print the name of the user's current branch. We can mimic the

268 +`git status` implementation; the printer is located in `wt-status.c` and we can

269 +see that the branch is held in a `struct wt_status`.

270 +

271 +`wt_status_print()` gets invoked by `cmd_status()` in `builtin/commit.c`.

272 +Looking at that implementation we see the status config being populated like so:

273 +

274 +----

275 +status_init_config(&s, git_status_config);

276 +----

277 +

278 +But as we drill down, we can find that `status_init_config()` wraps a call

279 +to `git_config()`. Let's modify the code we wrote in the previous commit.

280 +

281 +Be sure to include the header to allow you to use `struct wt_status`:

282 +----

283 +#include "wt-status.h"

284 +----

285 +

286 +Then modify your `cmd_psuh` implementation to declare your `struct wt_status`,

287 +prepare it, and print its contents:

288 +

289 +----

290 + struct wt_status status;

291 +

292 +...

293 +

294 + wt_status_prepare(the_repository, &status);

295 + git_config(git_default_config, &status);

296 +

297 +...

298 +

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

300 +----

301 +

302 +Run it again. Check it out - here's the (verbose) name of your current branch!

303 +

304 +Let's commit this as well.

305 +

306 +----

307 +$ git commit -sm "psuh: print the current branch"

308 +----

309 +

310 +Now let's see if we can get some info about a specific commit.

311 +

312 +Luckily, there are some helpers for us here. `commit.h` has a function called

313 +`lookup_commit_reference_by_name` to which we can simply provide a hardcoded

314 +string; `pretty.h` has an extremely handy `pp_commit_easy()` call which doesn't

315 +require a full format object to be passed.

316 +

317 +Add the following includes:

318 +

319 +----

320 +#include "commit.h"

321 +#include "pretty.h"

322 +----

323 +

324 +Then, add the following lines within your implementation of `cmd_psuh()` near

325 +the declarations and the logic, respectively.

326 +

327 +----

328 + struct commit *c = NULL;

329 + struct strbuf commitline = STRBUF_INIT;

330 +

331 +...

332 +

333 + c = lookup_commit_reference_by_name("origin/master");

334 +

335 + if (c != NULL) {

336 + pp_commit_easy(CMIT_FMT_ONELINE, c, &commitline);

337 + printf(_("Current commit: %s\n"), commitline.buf);

338 + }

339 +----

340 +

341 +The `struct strbuf` provides some safety belts to your basic `char*`, one of

342 +which is a length member to prevent buffer overruns. It needs to be initialized

343 +nicely with `STRBUF_INIT`. Keep it in mind when you need to pass around `char*`.

344 +

345 +`lookup_commit_reference_by_name` resolves the name you pass it, so you can play

346 +with the value there and see what kind of things you can come up with.

347 +

348 +`pp_commit_easy` is a convenience wrapper in `pretty.h` that takes a single

349 +format enum shorthand, rather than an entire format struct. It then

350 +pretty-prints the commit according to that shorthand. These are similar to the

351 +formats available with `--pretty=FOO` in many Git commands.

352 +

353 +Build it and run, and if you're using the same name in the example, you should

354 +see the subject line of the most recent commit in `origin/master` that you know

355 +about. Neat! Let's commit that as well.

356 +

357 +----

358 +$ git commit -sm "psuh: display the top of origin/master"

359 +----

360 +

361 +=== Adding Documentation

362 +

363 +Awesome! You've got a fantastic new command that you're ready to share with the

364 +community. But hang on just a minute - this isn't very user-friendly. Run the

365 +following:

366 +

367 +----

368 +$ ./bin-wrappers/git help psuh

369 +----

370 +

371 +Your new command is undocumented! Let's fix that.

372 +

373 +Take a look at `Documentation/git-*.txt`. These are the manpages for the

374 +subcommands that Git knows about. You can open these up and take a look to get

375 +acquainted with the format, but then go ahead and make a new file

376 +`Documentation/git-psuh.txt`. Like with most of the documentation in the Git

377 +project, help pages are written with AsciiDoc (see CodingGuidelines, "Writing

378 +Documentation" section). Use the following template to fill out your own

379 +manpage:

380 +

381 +// Surprisingly difficult to embed AsciiDoc source within AsciiDoc.

382 +[listing]

383 +....

384 +git-psuh(1)

385 +===========

386 +

387 +NAME

388 +----

389 +git-psuh - Delight users' typo with a shy horse

390 +

391 +

392 +SYNOPSIS

393 +--------

394 +[verse]

395 +'git-psuh'

396 +

397 +DESCRIPTION

398 +-----------

399 +...

400 +

401 +OPTIONS[[OPTIONS]]

402 +------------------

403 +...

404 +

405 +OUTPUT

406 +------

407 +...

408 +

409 +

410 +GIT

411 +---

412 +Part of the linkgit:git[1] suite

413 +....

414 +

415 +The most important pieces of this to note are the file header, underlined by =,

416 +the NAME section, and the SYNOPSIS, which would normally contain the grammar if

417 +your command took arguments. Try to use well-established manpage headers so your

418 +documentation is consistent with other Git and UNIX manpages; this makes life

419 +easier for your user, who can skip to the section they know contains the

420 +information they need.

421 +

422 +Now that you've written your manpage, you'll need to build it explicitly. We

423 +convert your AsciiDoc to troff which is man-readable like so:

424 +

425 +----

426 +$ make all doc

427 +$ man Documentation/git-psuh.1

428 +----

429 +

430 +or

431 +

432 +----

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

434 +$ man Documentation/git-psuh.1

435 +----

436 +

437 +NOTE: You may need to install the package `asciidoc` to get this to work.

438 +

439 +While this isn't as satisfying as running through `git help`, you can at least

440 +check that your help page looks right.

441 +

442 +You can also check that the documentation coverage is good (that is, the project

443 +sees that your command has been implemented as well as documented) by running

444 +`make check-docs` from the top-level.

445 +

446 +Go ahead and commit your new documentation change.

447 +

448 +=== Adding Usage Text

449 +

450 +Try and run `./bin-wrappers/git psuh -h`. Your command should crash at the end.

451 +That's because `-h` is a special case which your command should handle by

452 +printing usage.

453 +

454 +Take a look at `Documentation/technical/api-parse-options.txt`. This is a handy

455 +tool for pulling out options you need to be able to handle, and it takes a

456 +usage string.

457 +

458 +In order to use it, we'll need to prepare a NULL-terminated usage string and a

459 +`builtin_psuh_options` array. Add a line to `#include "parse-options.h"`.

460 +

461 +At global scope, add your usage:

462 +

463 +----

464 +static const char * const psuh_usage[] = {

465 + N_("git psuh"),

466 + NULL,

467 +};

468 +----

469 +

470 +Then, within your `cmd_psuh()` implementation, we can declare and populate our

471 +`option` struct. Ours is pretty boring but you can add more to it if you want to

472 +explore `parse_options()` in more detail:

473 +

474 +----

475 + struct option options[] = {

476 + OPT_END()

477 + };

478 +----

479 +

480 +Finally, before you print your args and prefix, add the call to

481 +`parse-options()`:

482 +

483 +----

484 + argc = parse_options(argc, argv, prefix, options, psuh_usage, 0);

485 +----

486 +

487 +This call will modify your `argv` parameter. It will strip the options you

488 +specified in `options` from `argv` and the locations pointed to from `options`

489 +entries will be updated. Be sure to replace your `argc` with the result from

490 +`parse_options()`, or you will be confused if you try to parse `argv` later.

491 +

492 +It's worth noting the special argument `--`. As you may be aware, many Unix

493 +commands use `--` to indicate "end of named parameters" - all parameters after

494 +the `--` are interpreted merely as positional arguments. (This can be handy if

495 +you want to pass as a parameter something which would usually be interpreted as

496 +a flag.) `parse_options()` will terminate parsing when it reaches `--` and give

497 +you the rest of the options afterwards, untouched.

498 +

499 +Build again. Now, when you run with `-h`, you should see your usage printed and

500 +your command terminated before anything else interesting happens. Great!

501 +

502 +Go ahead and commit this one, too.

503 +

504 +== Testing

505 +

506 +It's important to test your code - even for a little toy command like this one.

507 +Moreover, your patch won't be accepted into the Git tree without tests. Your

508 +tests should:

509 +

510 +* Illustrate the current behavior of the feature

511 +* Prove the current behavior matches the expected behavior

512 +* Ensure the externally-visible behavior isn't broken in later changes

513 +

514 +So let's write some tests.

515 +

516 +Related reading: `t/README`

517 +

518 +=== Overview of Testing Structure

519 +

520 +The tests in Git live in `t/` and are named with a 4-digit decimal number using

521 +the schema shown in the Naming Tests section of `t/README`.

522 +

523 +=== Writing Your Test

524 +

525 +Since this a toy command, let's go ahead and name the test with t9999. However,

526 +as many of the family/subcmd combinations are full, best practice seems to be

527 +to find a command close enough to the one you've added and share its naming

528 +space.

529 +

530 +Create a new file `t/t9999-psuh-tutorial.sh`. Begin with the header as so (see

531 +"Writing Tests" and "Source 'test-lib.sh'" in `t/README`):

532 +

533 +----

534 +#!/bin/sh

535 +

536 +test_description='git-psuh test

537 +

538 +This test runs git-psuh and makes sure it does not crash.'

539 +

540 +. ./test-lib.sh

541 +----

542 +

543 +Tests are framed inside of a `test_expect_success` in order to output TAP

544 +formatted results. Let's make sure that `git psuh` doesn't exit poorly and does

545 +mention the right animal somewhere:

546 +

547 +----

548 +test_expect_success 'runs correctly with no args and good output' '

549 + git psuh >actual &&

550 + test_i18ngrep Pony actual

551 +'

552 +----

553 +

554 +Indicate that you've run everything you wanted by adding the following at the

555 +bottom of your script:

556 +

557 +----

558 +test_done

559 +----

560 +

561 +Make sure you mark your test script executable:

562 +

563 +----

564 +$ chmod +x t/t9999-psuh-tutorial.sh

565 +----

566 +

567 +You can get an idea of whether you created your new test script successfully

568 +by running `make -C t test-lint`, which will check for things like test number

569 +uniqueness, executable bit, and so on.

570 +

571 +=== Running Locally

572 +

573 +Let's try and run locally:

574 +

575 +----

576 +$ make

577 +$ cd t/ && prove t9999-psuh-tutorial.sh

578 +----

579 +

580 +You can run the full test suite and ensure `git-psuh` didn't break anything:

581 +

582 +----

583 +$ cd t/

584 +$ prove -j$(nproc) --shuffle t[0-9]*.sh

585 +----

586 +

587 +NOTE: You can also do this with `make test` or use any testing harness which can

588 +speak TAP. `prove` can run concurrently. `shuffle` randomizes the order the

589 +tests are run in, which makes them resilient against unwanted inter-test

590 +dependencies. `prove` also makes the output nicer.

591 +

592 +Go ahead and commit this change, as well.

593 +

594 +== Getting Ready to Share

595 +

596 +You may have noticed already that the Git project performs its code reviews via

597 +emailed patches, which are then applied by the maintainer when they are ready

598 +and approved by the community. The Git project does not accept patches from

599 +pull requests, and the patches emailed for review need to be formatted a

600 +specific way. At this point the tutorial diverges, in order to demonstrate two

601 +different methods of formatting your patchset and getting it reviewed.

602 +

603 +The first method to be covered is GitGitGadget, which is useful for those

604 +already familiar with GitHub's common pull request workflow. This method

605 +requires a GitHub account.

606 +

607 +The second method to be covered is `git send-email`, which can give slightly

608 +more fine-grained control over the emails to be sent. This method requires some

609 +setup which can change depending on your system and will not be covered in this

610 +tutorial.

611 +

612 +Regardless of which method you choose, your engagement with reviewers will be

613 +the same; the review process will be covered after the sections on GitGitGadget

614 +and `git send-email`.

615 +

616 +== Sending Patches via GitGitGadget

617 +

618 +One option for sending patches is to follow a typical pull request workflow and

619 +send your patches out via GitGitGadget. GitGitGadget is a tool created by

620 +Johannes Schindelin to make life as a Git contributor easier for those used to

621 +the GitHub PR workflow. It allows contributors to open pull requests against its

622 +mirror of the Git project, and does some magic to turn the PR into a set of

623 +emails and send them out for you. It also runs the Git continuous integration

624 +suite for you. It's documented at http://gitgitgadget.github.io.

625 +

626 +=== Forking `git/git` on GitHub

627 +

628 +Before you can send your patch off to be reviewed using GitGitGadget, you will

629 +need to fork the Git project and upload your changes. First thing - make sure

630 +you have a GitHub account.

631 +

632 +Head to the https://github.com/git/git[GitHub mirror] and look for the Fork

633 +button. Place your fork wherever you deem appropriate and create it.

634 +

635 +=== Uploading to Your Own Fork

636 +

637 +To upload your branch to your own fork, you'll need to add the new fork as a

638 +remote. You can use `git remote -v` to show the remotes you have added already.

639 +From your new fork's page on GitHub, you can press "Clone or download" to get

640 +the URL; then you need to run the following to add, replacing your own URL and

641 +remote name for the examples provided:

642 +

643 +----

644 +$ git remote add remotename git@github.com:remotename/git.git

645 +----

646 +

647 +or to use the HTTPS URL:

648 +

649 +----

650 +$ git remote add remotename https://github.com/remotename/git/.git

651 +----

652 +

653 +Run `git remote -v` again and you should see the new remote showing up.

654 +`git fetch remotename` (with the real name of your remote replaced) in order to

655 +get ready to push.

656 +

657 +Next, double-check that you've been doing all your development in a new branch

658 +by running `git branch`. If you didn't, now is a good time to move your new

659 +commits to their own branch.

660 +

661 +As mentioned briefly at the beginning of this document, we are basing our work

662 +on `master`, so go ahead and update as shown below, or using your preferred

663 +workflow.

664 +

665 +----

666 +$ git checkout master

667 +$ git pull -r

668 +$ git rebase master psuh

669 +----

670 +

671 +Finally, you're ready to push your new topic branch! (Due to our branch and

672 +command name choices, be careful when you type the command below.)

673 +

674 +----

675 +$ git push remotename psuh

676 +----

677 +

678 +Now you should be able to go and check out your newly created branch on GitHub.

679 +

680 +=== Sending a PR to GitGitGadget

681 +

682 +In order to have your code tested and formatted for review, you need to start by

683 +opening a Pull Request against `gitgitgadget/git`. Head to

684 +https://github.com/gitgitgadget/git and open a PR either with the "New pull

685 +request" button or the convenient "Compare & pull request" button that may

686 +appear with the name of your newly pushed branch.

687 +

688 +Review the PR's title and description, as it's used by GitGitGadget as the cover

689 +letter for your change. When you're happy, submit your pull request.

690 +

691 +=== Running CI and Getting Ready to Send

692 +

693 +If it's your first time using GitGitGadget (which is likely, as you're using

694 +this tutorial) then someone will need to give you permission to use the tool.

695 +As mentioned in the GitGitGadget documentation, you just need someone who

696 +already uses it to comment on your PR with `/allow <username>`. GitGitGadget

697 +will automatically run your PRs through the CI even without the permission given

698 +but you will not be able to `/submit` your changes until someone allows you to

699 +use the tool.

700 +

701 +If the CI fails, you can update your changes with `git rebase -i` and push your

702 +branch again:

703 +

704 +----

705 +$ git push -f remotename psuh

706 +----

707 +

708 +In fact, you should continue to make changes this way up until the point when

709 +your patch is accepted into `next`.

710 +

711 +////

712 +TODO https://github.com/gitgitgadget/gitgitgadget/issues/83

713 +It'd be nice to be able to verify that the patch looks good before sending it

714 +to everyone on Git mailing list.

715 +=== Check Your Work

716 +////

717 +

718 +=== Sending Your Patches

719 +

720 +Now that your CI is passing and someone has granted you permission to use

721 +GitGitGadget with the `/allow` command, sending out for review is as simple as

722 +commenting on your PR with `/submit`.

723 +

724 +=== Updating With Comments

725 +

726 +Skip ahead to <<reviewing,Responding to Reviews>> for information on how to

727 +reply to review comments you will receive on the mailing list.

728 +

729 +Once you have your branch again in the shape you want following all review

730 +comments, you can submit again:

731 +

732 +----

733 +$ git push -f remotename psuh

734 +----

735 +

736 +Next, go look at your pull request against GitGitGadget; you should see the CI

737 +has been kicked off again. Now while the CI is running is a good time for you

738 +to modify your description at the top of the pull request thread; it will be

739 +used again as the cover letter. You should use this space to describe what

740 +has changed since your previous version, so that your reviewers have some idea

741 +of what they're looking at. When the CI is done running, you can comment once

742 +more with `/submit` - GitGitGadget will automatically add a v2 mark to your

743 +changes.

744 +

745 +== Sending Patches with `git send-email`

746 +

747 +If you don't want to use GitGitGadget, you can also use Git itself to mail your

748 +patches. Some benefits of using Git this way include finer grained control of

749 +subject line (for example, being able to use the tag [RFC PATCH] in the subject)

750 +and being able to send a ``dry run'' mail to yourself to ensure it all looks

751 +good before going out to the list.

752 +

753 +=== Prerequisite: Setting Up `git send-email`

754 +

755 +Configuration for `send-email` can vary based on your operating system and email

756 +provider, and so will not be covered in this tutorial, beyond stating that in

757 +many distributions of Linux, `git-send-email` is not packaged alongside the

758 +typical `git` install. You may need to install this additional package; there

759 +are a number of resources online to help you do so. You will also need to

760 +determine the right way to configure it to use your SMTP server; again, as this

761 +configuration can change significantly based on your system and email setup, it

762 +is out of scope for the context of this tutorial.

763 +

764 +=== Preparing Initial Patchset

765 +

766 +Sending emails with Git is a two-part process; before you can prepare the emails

767 +themselves, you'll need to prepare the patches. Luckily, this is pretty simple:

768 +

769 +----

770 +$ git format-patch --cover-letter -o psuh/ master..psuh

771 +----

772 +

773 +The `--cover-letter` parameter tells `format-patch` to create a cover letter

774 +template for you. You will need to fill in the template before you're ready

775 +to send - but for now, the template will be next to your other patches.

776 +

777 +The `-o psuh/` parameter tells `format-patch` to place the patch files into a

778 +directory. This is useful because `git send-email` can take a directory and

779 +send out all the patches from there.

780 +

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

782 +between `master` and `psuh`. It will make one patch file per commit. After you

783 +run, you can go have a look at each of the patches with your favorite text

784 +editor and make sure everything looks alright; however, it's not recommended to

785 +make code fixups via the patch file. It's a better idea to make the change the

786 +normal way using `git rebase -i` or by adding a new commit than by modifying a

787 +patch.

788 +

789 +NOTE: Optionally, you can also use the `--rfc` flag to prefix your patch subject

790 +with ``[RFC PATCH]'' instead of ``[PATCH]''. RFC stands for ``request for

791 +comments'' and indicates that while your code isn't quite ready for submission,

792 +you'd like to begin the code review process. This can also be used when your

793 +patch is a proposal, but you aren't sure whether the community wants to solve

794 +the problem with that approach or not - to conduct a sort of design review. You

795 +may also see on the list patches marked ``WIP'' - this means they are incomplete

796 +but want reviewers to look at what they have so far. You can add this flag with

797 +`--subject-prefix=WIP`.

798 +

799 +Check and make sure that your patches and cover letter template exist in the

800 +directory you specified - you're nearly ready to send out your review!

801 +

802 +=== Preparing Email

803 +

804 +In addition to an email per patch, the Git community also expects your patches

805 +to come with a cover letter, typically with a subject line [PATCH 0/x] (where

806 +x is the number of patches you're sending). Since you invoked `format-patch`

807 +with `--cover-letter`, you've already got a template ready. Open it up in your

808 +favorite editor.

809 +

810 +You should see a number of headers present already. Check that your `From:`

811 +header is correct. Then modify your `Subject:` to something which succinctly

812 +covers the purpose of your entire topic branch, for example:

813 +

814 +----

815 +Subject: [PATCH 0/7] adding the 'psuh' command

816 +----

817 +

818 +Make sure you retain the ``[PATCH 0/X]'' part; that's what indicates to the Git

819 +community that this email is the beginning of a review, and many reviewers

820 +filter their email for this type of flag.

821 +

822 +You'll need to add some extra parameters when you invoke `git send-email` to add

823 +the cover letter.

824 +

825 +Next you'll have to fill out the body of your cover letter. This is an important

826 +component of change submission as it explains to the community from a high level

827 +what you're trying to do, and why, in a way that's more apparent than just

828 +looking at your diff. Be sure to explain anything your diff doesn't make clear

829 +on its own.

830 +

831 +Here's an example body for `psuh`:

832 +

833 +----

834 +Our internal metrics indicate widespread interest in the command

835 +git-psuh - that is, many users are trying to use it, but finding it is

836 +unavailable, using some unknown workaround instead.

837 +

838 +The following handful of patches add the psuh command and implement some

839 +handy features on top of it.

840 +

841 +This patchset is part of the MyFirstContribution tutorial and should not

842 +be merged.

843 +----

844 +

845 +The template created by `git format-patch --cover-letter` includes a diffstat.

846 +This gives reviewers a summary of what they're in for when reviewing your topic.

847 +The one generated for `psuh` from the sample implementation looks like this:

848 +

849 +----

850 + Documentation/git-psuh.txt | 40 +++++++++++++++++++++

851 + Makefile | 1 +

852 + builtin.h | 1 +

853 + builtin/psuh.c | 73 ++++++++++++++++++++++++++++++++++++++

854 + git.c | 1 +

855 + t/t9999-psuh-tutorial.sh | 12 +++++++

856 + 6 files changed, 128 insertions(+)

857 + create mode 100644 Documentation/git-psuh.txt

858 + create mode 100644 builtin/psuh.c

859 + create mode 100755 t/t9999-psuh-tutorial.sh

860 +----

861 +

862 +Finally, the letter will include the version of Git used to generate the

863 +patches. You can leave that string alone.

864 +

865 +=== Sending Email

866 +

867 +At this point you should have a directory `psuh/` which is filled with your

868 +patches and a cover letter. Time to mail it out! You can send it like this:

869 +

870 +----

871 +$ git send-email --to=target@example.com psuh/*.patch

872 +----

873 +

874 +NOTE: Check `git help send-email` for some other options which you may find

875 +valuable, such as changing the Reply-to address or adding more CC and BCC lines.

876 +

877 +NOTE: When you are sending a real patch, it will go to git@vger.kernel.org - but

878 +please don't send your patchset from the tutorial to the real mailing list! For

879 +now, you can send it to yourself, to make sure you understand how it will look.

880 +

881 +After you run the command above, you will be presented with an interactive

882 +prompt for each patch that's about to go out. This gives you one last chance to

883 +edit or quit sending something (but again, don't edit code this way). Once you

884 +press `y` or `a` at these prompts your emails will be sent! Congratulations!

885 +

886 +Awesome, now the community will drop everything and review your changes. (Just

887 +kidding - be patient!)

888 +

889 +=== Sending v2

890 +

891 +Skip ahead to <<reviewing,Responding to Reviews>> for information on how to

892 +handle comments from reviewers. Continue this section when your topic branch is

893 +shaped the way you want it to look for your patchset v2.

894 +

895 +When you're ready with the next iteration of your patch, the process is fairly

896 +similar.

897 +

898 +First, generate your v2 patches again:

899 +

900 +----

901 +$ git format-patch -v2 --cover-letter -o psuh/ master..psuh

902 +----

903 +

904 +This will add your v2 patches, all named like `v2-000n-my-commit-subject.patch`,

905 +to the `psuh/` directory. You may notice that they are sitting alongside the v1

906 +patches; that's fine, but be careful when you are ready to send them.

907 +

908 +Edit your cover letter again. Now is a good time to mention what's different

909 +between your last version and now, if it's something significant. You do not

910 +need the exact same body in your second cover letter; focus on explaining to

911 +reviewers the changes you've made that may not be as visible.

912 +

913 +You will also need to go and find the Message-Id of your previous cover letter.

914 +You can either note it when you send the first series, from the output of `git

915 +send-email`, or you can look it up on the

916 +https://public-inbox.org/git[mailing list]. Find your cover letter in the

917 +archives, click on it, then click "permalink" or "raw" to reveal the Message-Id

918 +header. It should match:

919 +

920 +----

921 +Message-Id: <foo.12345.author@example.com>

922 +----

923 +

924 +Your Message-Id is `<foo.12345.author@example.com>`. This example will be used

925 +below as well; make sure to replace it with the correct Message-Id for your

926 +**previous cover letter** - that is, if you're sending v2, use the Message-Id

927 +from v1; if you're sending v3, use the Message-Id from v2.

928 +

929 +While you're looking at the email, you should also note who is CC'd, as it's

930 +common practice in the mailing list to keep all CCs on a thread. You can add

931 +these CC lines directly to your cover letter with a line like so in the header

932 +(before the Subject line):

933 +

934 +----

935 +CC: author@example.com, Othe R <other@example.com>

936 +----

937 +

938 +Now send the emails again, paying close attention to which messages you pass in

939 +to the command:

940 +

941 +----

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

943 + --in-reply-to="<foo.12345.author@example.com>"

944 + psuh/v2*

945 +----

946 +

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

948 +

949 +In some cases, your very small change may consist of only one patch. When that

950 +happens, you only need to send one email. Your commit message should already be

951 +meaningful and explain at a high level the purpose (what is happening and why)

952 +of your patch, but if you need to supply even more context, you can do so below

953 +the `---` in your patch. Take the example below, which was generated with `git

954 +format-patch` on a single commit, and then edited to add the content between

955 +the `---` and the diffstat.

956 +

957 +----

958 +From 1345bbb3f7ac74abde040c12e737204689a72723 Mon Sep 17 00:00:00 2001

959 +From: A U Thor <author@example.com>

960 +Date: Thu, 18 Apr 2019 15:11:02 -0700

961 +Subject: [PATCH] README: change the grammar

962 +

963 +I think it looks better this way. This part of the commit message will

964 +end up in the commit-log.

965 +

966 +Signed-off-by: A U Thor <author@example.com>

967 +---

968 +Let's have a wild discussion about grammar on the mailing list. This

969 +part of my email will never end up in the commit log. Here is where I

970 +can add additional context to the mailing list about my intent, outside

971 +of the context of the commit log. This section was added after `git

972 +format-patch` was run, by editing the patch file in a text editor.

973 +

974 + README.md | 2 +-

975 + 1 file changed, 1 insertion(+), 1 deletion(-)

976 +

977 +diff --git a/README.md b/README.md

978 +index 88f126184c..38da593a60 100644

979 +--- a/README.md

980 ++++ b/README.md

981 +@@ -3,7 +3,7 @@

982 + Git - fast, scalable, distributed revision control system

983 + =========================================================

984 +

985 +-Git is a fast, scalable, distributed revision control system with an

986 ++Git is a fast, scalable, and distributed revision control system with an

987 + unusually rich command set that provides both high-level operations

988 + and full access to internals.

989 +

990 +--

991 +2.21.0.392.gf8f6787159e-goog

992 +----

993 +

994 +== My Patch Got Emailed - Now What?

995 +

996 +[[reviewing]]

997 +=== Responding to Reviews

998 +

999 +After a few days, you will hopefully receive a reply to your patchset with some

1000 +comments. Woohoo! Now you can get back to work.

1001 +

1002 +It's good manners to reply to each comment, notifying the reviewer that you have

1003 +made the change requested, feel the original is better, or that the comment

1004 +inspired you to do something a new way which is superior to both the original

1005 +and the suggested change. This way reviewers don't need to inspect your v2 to

1006 +figure out whether you implemented their comment or not.

1007 +

1008 +If you are going to push back on a comment, be polite and explain why you feel

1009 +your original is better; be prepared that the reviewer may still disagree with

1010 +you, and the rest of the community may weigh in on one side or the other. As

1011 +with all code reviews, it's important to keep an open mind to doing something a

1012 +different way than you originally planned; other reviewers have a different

1013 +perspective on the project than you do, and may be thinking of a valid side

1014 +effect which had not occurred to you. It is always okay to ask for clarification

1015 +if you aren't sure why a change was suggested, or what the reviewer is asking

1016 +you to do.

1017 +

1018 +Make sure your email client has a plaintext email mode and it is turned on; the

1019 +Git list rejects HTML email. Please also follow the mailing list etiquette

1020 +outlined in the

1021 +https://kernel.googlesource.com/pub/scm/git/git/+/todo/MaintNotes[Maintainer's

1022 +Note], which are similar to etiquette rules in most open source communities

1023 +surrounding bottom-posting and inline replies.

1024 +

1025 +When you're making changes to your code, it is cleanest - that is, the resulting

1026 +commits are easiest to look at - if you use `git rebase -i` (interactive

1027 +rebase). Take a look at this

1028 +https://www.oreilly.com/library/view/git-pocket-guide/9781449327507/ch10.html[overview]

1029 +from O'Reilly. The general idea is to modify each commit which requires changes;

1030 +this way, instead of having a patch A with a mistake, a patch B which was fine

1031 +and required no upstream reviews in v1, and a patch C which fixes patch A for

1032 +v2, you can just ship a v2 with a correct patch A and correct patch B. This is

1033 +changing history, but since it's local history which you haven't shared with

1034 +anyone, that is okay for now! (Later, it may not make sense to do this; take a

1035 +look at the section below this one for some context.)

1036 +

1037 +=== After Review Approval

1038 +

1039 +The Git project has four integration branches: `pu`, `next`, `master`, and

1040 +`maint`. Your change will be placed into `pu` fairly early on by the maintainer

1041 +while it is still in the review process; from there, when it is ready for wider

1042 +testing, it will be merged into `next`. Plenty of early testers use `next` and

1043 +may report issues. Eventually, changes in `next` will make it to `master`,

1044 +which is typically considered stable. Finally, when a new release is cut,

1045 +`maint` is used to base bugfixes onto. As mentioned at the beginning of this

1046 +document, you can read `Documents/SubmittingPatches` for some more info about

1047 +the use of the various integration branches.

1048 +

1049 +Back to now: your code has been lauded by the upstream reviewers. It is perfect.

1050 +It is ready to be accepted. You don't need to do anything else; the maintainer

1051 +will merge your topic branch to `next` and life is good.

1052 +

1053 +However, if you discover it isn't so perfect after this point, you may need to

1054 +take some special steps depending on where you are in the process.

1055 +

1056 +If the maintainer has announced in the "What's cooking in git.git" email that

1057 +your topic is marked for `next` - that is, that they plan to merge it to `next`

1058 +but have not yet done so - you should send an email asking the maintainer to

1059 +wait a little longer: "I've sent v4 of my series and you marked it for `next`,

1060 +but I need to change this and that - please wait for v5 before you merge it."

1061 +

1062 +If the topic has already been merged to `next`, rather than modifying your

1063 +patches with `git rebase -i`, you should make further changes incrementally -

1064 +that is, with another commit, based on top of the maintainer's topic branch as

1065 +detailed in https://github.com/gitster/git. Your work is still in the same topic

1066 +but is now incremental, rather than a wholesale rewrite of the topic branch.

1067 +

1068 +The topic branches in the maintainer's GitHub are mirrored in GitGitGadget, so

1069 +if you're sending your reviews out that way, you should be sure to open your PR

1070 +against the appropriate GitGitGadget/Git branch.

1071 +

1072 +If you're using `git send-email`, you can use it the same way as before, but you

1073 +should generate your diffs from `<topic>..<mybranch>` and base your work on

1074 +`<topic>` instead of `master`.

documentation: add tutorial for first contribution