documentation: add anchors to MyFirstContribution
During the course of review for MyFirstContribution.txt, the suggestion came up to include anchors to make it easier for veteran contributors to link specific sections of this documents to newbies. To make life easier for reviewers, add these anchors in their own commit. See review context here: https://public-inbox.org/git/20190507195938.GD220818@google.com/ AsciiDoc does not support :sectanchors: and the anchors are not discoverable, but they are referenceable. So a link to "foo.com/MyFirstContribution.html#prerequisites" will still work if that file was generated with AsciiDoc. The inclusion of :sectanchors: does not create warnings or errors while compiling directly with `asciidoc -b html5 Documentation/MyFirstContribution.txt` or while compiling with `make doc`. AsciiDoctor does support :sectanchors: and displays a paragraph link on mouseover. When the anchor is included above or inline with a section (as in this change), the link provided points to the custom ID contained within [[]] instead of to an autogenerated ID. Practically speaking, this means we have .../MyFirstContribution.html#summary instead of .../MyFirstContribution.html#_summary. In addition to being prettier, the custom IDs also enable anchor linking to work with asciidoc-generated pages. This change compiles with no warnings using `asciidoctor -b html5 Documentation/MyFirstContribution.txt`. Signed-off-by: Emily Shaffer <emilyshaffer@google.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Emily Shaffer committed
May 17, 2019 at 12:07 UTC
5ef811ac5d60f9f6aa4300606d85ff780d2f402a
1 file changed
+35
Documentation/MyFirstContribution.txt
+35
@@ -1,16 +1,20 @@
1
My First Contribution to the Git Project
2
========================================
3
+:sectanchors:
4
5
+[[summary]]
6
== Summary
7
8
This is a tutorial demonstrating the end-to-end workflow of creating a change to
9
the Git tree, sending it for review, and making changes based on comments.
10
11
+[[prerequisites]]
12
=== Prerequisites
13
14
This tutorial assumes you're already fairly familiar with using Git to manage
15
source code. The Git workflow steps will largely remain unexplained.
16
17
+[[related-reading]]
18
=== Related Reading
19
20
This tutorial aims to summarize the following documents, but the reader may find
@@ -19,8 +23,10 @@ useful additional context:
23
- `Documentation/SubmittingPatches`
24
- `Documentation/howto/new-command.txt`
25
26
+[[getting-started]]
27
== Getting Started
28
29
+[[cloning]]
30
=== Clone the Git Repository
31
32
Git is mirrored in a number of locations. Clone the repository from one of them;
@@ -31,6 +37,7 @@ the mirror on GitHub.
37
$ git clone https://github.com/git/git git
38
----
39
40
+[[identify-problem]]
41
=== Identify Problem to Solve
42
43
////
@@ -44,6 +51,7 @@ of invocation during users' typical daily workflow.
51
(We've seen some other effort in this space with the implementation of popular
52
commands such as `sl`.)
53
54
+[[setup-workspace]]
55
=== Set Up Your Workspace
56
57
Let's start by making a development branch to work on our changes. Per
@@ -62,11 +70,13 @@ $ git checkout -b psuh origin/master
70
We'll make a number of commits here in order to demonstrate how to send a topic
71
with multiple patches up for review simultaneously.
72
73
+[[code-it-up]]
74
== Code It Up!
75
76
NOTE: A reference implementation can be found at
77
https://github.com/nasamuffin/git/tree/psuh.
78
79
+[[add-new-command]]
80
=== Adding a New Command
81
82
Lots of the subcommands are written as builtins, which means they are
@@ -195,6 +205,7 @@ For the remainder of the tutorial, the subject line only will be listed for the
205
sake of brevity. However, fully-fleshed example commit messages are available
206
on the reference implementation linked at the top of this document.
207
208
+[[implementation]]
209
=== Implementation
210
211
It's probably useful to do at least something besides printing out a string.
@@ -358,6 +369,7 @@ about. Neat! Let's commit that as well.
369
$ git commit -sm "psuh: display the top of origin/master"
370
----
371
372
+[[add-documentation]]
373
=== Adding Documentation
374
375
Awesome! You've got a fantastic new command that you're ready to share with the
@@ -445,6 +457,7 @@ sees that your command has been implemented as well as documented) by running
457
458
Go ahead and commit your new documentation change.
459
460
+[[add-usage]]
461
=== Adding Usage Text
462
463
Try and run `./bin-wrappers/git psuh -h`. Your command should crash at the end.
@@ -501,6 +514,7 @@ your command terminated before anything else interesting happens. Great!
514
515
Go ahead and commit this one, too.
516
517
+[[testing]]
518
== Testing
519
520
It's important to test your code - even for a little toy command like this one.
@@ -515,11 +529,13 @@ So let's write some tests.
529
530
Related reading: `t/README`
531
532
+[[overview-test-structure]]
533
=== Overview of Testing Structure
534
535
The tests in Git live in `t/` and are named with a 4-digit decimal number using
536
the schema shown in the Naming Tests section of `t/README`.
537
538
+[[write-new-test]]
539
=== Writing Your Test
540
541
Since this a toy command, let's go ahead and name the test with t9999. However,
@@ -568,6 +584,7 @@ You can get an idea of whether you created your new test script successfully
584
by running `make -C t test-lint`, which will check for things like test number
585
uniqueness, executable bit, and so on.
586
587
+[[local-test]]
588
=== Running Locally
589
590
Let's try and run locally:
@@ -591,6 +608,7 @@ dependencies. `prove` also makes the output nicer.
608
609
Go ahead and commit this change, as well.
610
611
+[[ready-to-share]]
612
== Getting Ready to Share
613
614
You may have noticed already that the Git project performs its code reviews via
@@ -613,6 +631,7 @@ Regardless of which method you choose, your engagement with reviewers will be
631
the same; the review process will be covered after the sections on GitGitGadget
632
and `git send-email`.
633
634
+[[howto-ggg]]
635
== Sending Patches via GitGitGadget
636
637
One option for sending patches is to follow a typical pull request workflow and
@@ -623,6 +642,7 @@ mirror of the Git project, and does some magic to turn the PR into a set of
642
emails and send them out for you. It also runs the Git continuous integration
643
suite for you. It's documented at http://gitgitgadget.github.io.
644
645
+[[create-fork]]
646
=== Forking `git/git` on GitHub
647
648
Before you can send your patch off to be reviewed using GitGitGadget, you will
@@ -632,6 +652,7 @@ you have a GitHub account.
652
Head to the https://github.com/git/git[GitHub mirror] and look for the Fork
653
button. Place your fork wherever you deem appropriate and create it.
654
655
+[[upload-to-fork]]
656
=== Uploading to Your Own Fork
657
658
To upload your branch to your own fork, you'll need to add the new fork as a
@@ -677,6 +698,7 @@ $ git push remotename psuh
698
699
Now you should be able to go and check out your newly created branch on GitHub.
700
701
+[[send-pr-ggg]]
702
=== Sending a PR to GitGitGadget
703
704
In order to have your code tested and formatted for review, you need to start by
@@ -688,6 +710,7 @@ appear with the name of your newly pushed branch.
710
Review the PR's title and description, as it's used by GitGitGadget as the cover
711
letter for your change. When you're happy, submit your pull request.
712
713
+[[run-ci-ggg]]
714
=== Running CI and Getting Ready to Send
715
716
If it's your first time using GitGitGadget (which is likely, as you're using
@@ -712,15 +735,18 @@ your patch is accepted into `next`.
735
TODO https://github.com/gitgitgadget/gitgitgadget/issues/83
736
It'd be nice to be able to verify that the patch looks good before sending it
737
to everyone on Git mailing list.
738
+[[check-work-ggg]]
739
=== Check Your Work
740
////
741
742
+[[send-mail-ggg]]
743
=== Sending Your Patches
744
745
Now that your CI is passing and someone has granted you permission to use
746
GitGitGadget with the `/allow` command, sending out for review is as simple as
747
commenting on your PR with `/submit`.
748
749
+[[responding-ggg]]
750
=== Updating With Comments
751
752
Skip ahead to <<reviewing,Responding to Reviews>> for information on how to
@@ -742,6 +768,7 @@ of what they're looking at. When the CI is done running, you can comment once
768
more with `/submit` - GitGitGadget will automatically add a v2 mark to your
769
changes.
770
771
+[[howto-git-send-email]]
772
== Sending Patches with `git send-email`
773
774
If you don't want to use GitGitGadget, you can also use Git itself to mail your
@@ -750,6 +777,7 @@ subject line (for example, being able to use the tag [RFC PATCH] in the subject)
777
and being able to send a ``dry run'' mail to yourself to ensure it all looks
778
good before going out to the list.
779
780
+[[setup-git-send-email]]
781
=== Prerequisite: Setting Up `git send-email`
782
783
Configuration for `send-email` can vary based on your operating system and email
@@ -761,6 +789,7 @@ determine the right way to configure it to use your SMTP server; again, as this
789
configuration can change significantly based on your system and email setup, it
790
is out of scope for the context of this tutorial.
791
792
+[[format-patch]]
793
=== Preparing Initial Patchset
794
795
Sending emails with Git is a two-part process; before you can prepare the emails
@@ -799,6 +828,7 @@ but want reviewers to look at what they have so far. You can add this flag with
828
Check and make sure that your patches and cover letter template exist in the
829
directory you specified - you're nearly ready to send out your review!
830
831
+[[cover-letter]]
832
=== Preparing Email
833
834
In addition to an email per patch, the Git community also expects your patches
@@ -862,6 +892,7 @@ The one generated for `psuh` from the sample implementation looks like this:
892
Finally, the letter will include the version of Git used to generate the
893
patches. You can leave that string alone.
894
895
+[[sending-git-send-email]]
896
=== Sending Email
897
898
At this point you should have a directory `psuh/` which is filled with your
@@ -886,6 +917,7 @@ press `y` or `a` at these prompts your emails will be sent! Congratulations!
917
Awesome, now the community will drop everything and review your changes. (Just
918
kidding - be patient!)
919
920
+[[v2-git-send-email]]
921
=== Sending v2
922
923
Skip ahead to <<reviewing,Responding to Reviews>> for information on how to
@@ -944,6 +976,7 @@ $ git send-email --to=target@example.com
976
psuh/v2*
977
----
978
979
+[[single-patch]]
980
=== Bonus Chapter: One-Patch Changes
981
982
In some cases, your very small change may consist of only one patch. When that
@@ -991,6 +1024,7 @@ index 88f126184c..38da593a60 100644
1024
2.21.0.392.gf8f6787159e-goog
1025
----
1026
1027
+[[now-what]]
1028
== My Patch Got Emailed - Now What?
1029
1030
[[reviewing]]
@@ -1034,6 +1068,7 @@ changing history, but since it's local history which you haven't shared with
1068
anyone, that is okay for now! (Later, it may not make sense to do this; take a
1069
look at the section below this one for some context.)
1070
1071
+[[after-approval]]
1072
=== After Review Approval
1073
1074
The Git project has four integration branches: `pu`, `next`, `master`, and