From: Emily Shaffer <emilyshaffer@google.com>
To: git@vger.kernel.org
Cc: Emily Shaffer <emilyshaffer@google.com>
Subject: [PATCH v6 2/2] documentation: add anchors to MyFirstContribution
Date: Fri, 17 May 2019 12:07:04 -0700 [thread overview]
Message-ID: <20190517190701.49722-3-emilyshaffer@google.com> (raw)
In-Reply-To: <20190517190359.21676-1-emilyshaffer@google.com>
During the course of review for MyFirstContribution.txt, the suggestion
came up to include anchors to make it easier for veteran contributors to
link specific sections of this documents to newbies. To make life easier
for reviewers, add these anchors in their own commit. See review context
here: https://public-inbox.org/git/20190507195938.GD220818@google.com/
AsciiDoc does not support :sectanchors: and the anchors are not
discoverable, but they are referenceable. So a link to
"foo.com/MyFirstContribution.html#prerequisites" will still work if that
file was generated with AsciiDoc. The inclusion of :sectanchors: does
not create warnings or errors while compiling directly with `asciidoc -b
html5 Documentation/MyFirstContribution.txt` or while compiling with
`make doc`.
AsciiDoctor does support :sectanchors: and displays a paragraph link on
mouseover. When the anchor is included above or inline with a section
(as in this change), the link provided points to the custom ID contained
within [[]] instead of to an autogenerated ID. Practically speaking,
this means we have .../MyFirstContribution.html#summary instead of
.../MyFirstContribution.html#_summary. In addition to being prettier,
the custom IDs also enable anchor linking to work with
asciidoc-generated pages. This change compiles with no warnings using
`asciidoctor -b html5 Documentation/MyFirstContribution.txt`.
Signed-off-by: Emily Shaffer <emilyshaffer@google.com>
---
Documentation/MyFirstContribution.txt | 35 +++++++++++++++++++++++++++
1 file changed, 35 insertions(+)
diff --git a/Documentation/MyFirstContribution.txt b/Documentation/MyFirstContribution.txt
index bc267c4931..274df8575b 100644
--- a/Documentation/MyFirstContribution.txt
+++ b/Documentation/MyFirstContribution.txt
@@ -1,16 +1,20 @@
My First Contribution to the Git Project
========================================
+:sectanchors:
+[[summary]]
== Summary
This is a tutorial demonstrating the end-to-end workflow of creating a change to
the Git tree, sending it for review, and making changes based on comments.
+[[prerequisites]]
=== Prerequisites
This tutorial assumes you're already fairly familiar with using Git to manage
source code. The Git workflow steps will largely remain unexplained.
+[[related-reading]]
=== Related Reading
This tutorial aims to summarize the following documents, but the reader may find
@@ -19,8 +23,10 @@ useful additional context:
- `Documentation/SubmittingPatches`
- `Documentation/howto/new-command.txt`
+[[getting-started]]
== Getting Started
+[[cloning]]
=== Clone the Git Repository
Git is mirrored in a number of locations. Clone the repository from one of them;
@@ -31,6 +37,7 @@ the mirror on GitHub.
$ git clone https://github.com/git/git git
----
+[[identify-problem]]
=== Identify Problem to Solve
////
@@ -44,6 +51,7 @@ of invocation during users' typical daily workflow.
(We've seen some other effort in this space with the implementation of popular
commands such as `sl`.)
+[[setup-workspace]]
=== Set Up Your Workspace
Let's start by making a development branch to work on our changes. Per
@@ -62,11 +70,13 @@ $ git checkout -b psuh origin/master
We'll make a number of commits here in order to demonstrate how to send a topic
with multiple patches up for review simultaneously.
+[[code-it-up]]
== Code It Up!
NOTE: A reference implementation can be found at
https://github.com/nasamuffin/git/tree/psuh.
+[[add-new-command]]
=== Adding a New Command
Lots of the subcommands are written as builtins, which means they are
@@ -195,6 +205,7 @@ For the remainder of the tutorial, the subject line only will be listed for the
sake of brevity. However, fully-fleshed example commit messages are available
on the reference implementation linked at the top of this document.
+[[implementation]]
=== Implementation
It's probably useful to do at least something besides printing out a string.
@@ -358,6 +369,7 @@ about. Neat! Let's commit that as well.
$ git commit -sm "psuh: display the top of origin/master"
----
+[[add-documentation]]
=== Adding Documentation
Awesome! You've got a fantastic new command that you're ready to share with the
@@ -445,6 +457,7 @@ sees that your command has been implemented as well as documented) by running
Go ahead and commit your new documentation change.
+[[add-usage]]
=== Adding Usage Text
Try and run `./bin-wrappers/git psuh -h`. Your command should crash at the end.
@@ -501,6 +514,7 @@ your command terminated before anything else interesting happens. Great!
Go ahead and commit this one, too.
+[[testing]]
== Testing
It's important to test your code - even for a little toy command like this one.
@@ -515,11 +529,13 @@ So let's write some tests.
Related reading: `t/README`
+[[overview-test-structure]]
=== Overview of Testing Structure
The tests in Git live in `t/` and are named with a 4-digit decimal number using
the schema shown in the Naming Tests section of `t/README`.
+[[write-new-test]]
=== Writing Your Test
Since this a toy command, let's go ahead and name the test with t9999. However,
@@ -568,6 +584,7 @@ You can get an idea of whether you created your new test script successfully
by running `make -C t test-lint`, which will check for things like test number
uniqueness, executable bit, and so on.
+[[local-test]]
=== Running Locally
Let's try and run locally:
@@ -591,6 +608,7 @@ dependencies. `prove` also makes the output nicer.
Go ahead and commit this change, as well.
+[[ready-to-share]]
== Getting Ready to Share
You may have noticed already that the Git project performs its code reviews via
@@ -613,6 +631,7 @@ Regardless of which method you choose, your engagement with reviewers will be
the same; the review process will be covered after the sections on GitGitGadget
and `git send-email`.
+[[howto-ggg]]
== Sending Patches via GitGitGadget
One option for sending patches is to follow a typical pull request workflow and
@@ -623,6 +642,7 @@ mirror of the Git project, and does some magic to turn the PR into a set of
emails and send them out for you. It also runs the Git continuous integration
suite for you. It's documented at http://gitgitgadget.github.io.
+[[create-fork]]
=== Forking `git/git` on GitHub
Before you can send your patch off to be reviewed using GitGitGadget, you will
@@ -632,6 +652,7 @@ you have a GitHub account.
Head to the https://github.com/git/git[GitHub mirror] and look for the Fork
button. Place your fork wherever you deem appropriate and create it.
+[[upload-to-fork]]
=== Uploading to Your Own Fork
To upload your branch to your own fork, you'll need to add the new fork as a
@@ -677,6 +698,7 @@ $ git push remotename psuh
Now you should be able to go and check out your newly created branch on GitHub.
+[[send-pr-ggg]]
=== Sending a PR to GitGitGadget
In order to have your code tested and formatted for review, you need to start by
@@ -688,6 +710,7 @@ appear with the name of your newly pushed branch.
Review the PR's title and description, as it's used by GitGitGadget as the cover
letter for your change. When you're happy, submit your pull request.
+[[run-ci-ggg]]
=== Running CI and Getting Ready to Send
If it's your first time using GitGitGadget (which is likely, as you're using
@@ -712,15 +735,18 @@ your patch is accepted into `next`.
TODO https://github.com/gitgitgadget/gitgitgadget/issues/83
It'd be nice to be able to verify that the patch looks good before sending it
to everyone on Git mailing list.
+[[check-work-ggg]]
=== Check Your Work
////
+[[send-mail-ggg]]
=== Sending Your Patches
Now that your CI is passing and someone has granted you permission to use
GitGitGadget with the `/allow` command, sending out for review is as simple as
commenting on your PR with `/submit`.
+[[responding-ggg]]
=== Updating With Comments
Skip ahead to <<reviewing,Responding to Reviews>> for information on how to
@@ -742,6 +768,7 @@ of what they're looking at. When the CI is done running, you can comment once
more with `/submit` - GitGitGadget will automatically add a v2 mark to your
changes.
+[[howto-git-send-email]]
== Sending Patches with `git send-email`
If you don't want to use GitGitGadget, you can also use Git itself to mail your
@@ -750,6 +777,7 @@ subject line (for example, being able to use the tag [RFC PATCH] in the subject)
and being able to send a ``dry run'' mail to yourself to ensure it all looks
good before going out to the list.
+[[setup-git-send-email]]
=== Prerequisite: Setting Up `git send-email`
Configuration for `send-email` can vary based on your operating system and email
@@ -761,6 +789,7 @@ determine the right way to configure it to use your SMTP server; again, as this
configuration can change significantly based on your system and email setup, it
is out of scope for the context of this tutorial.
+[[format-patch]]
=== Preparing Initial Patchset
Sending emails with Git is a two-part process; before you can prepare the emails
@@ -799,6 +828,7 @@ but want reviewers to look at what they have so far. You can add this flag with
Check and make sure that your patches and cover letter template exist in the
directory you specified - you're nearly ready to send out your review!
+[[cover-letter]]
=== Preparing Email
In addition to an email per patch, the Git community also expects your patches
@@ -862,6 +892,7 @@ The one generated for `psuh` from the sample implementation looks like this:
Finally, the letter will include the version of Git used to generate the
patches. You can leave that string alone.
+[[sending-git-send-email]]
=== Sending Email
At this point you should have a directory `psuh/` which is filled with your
@@ -886,6 +917,7 @@ press `y` or `a` at these prompts your emails will be sent! Congratulations!
Awesome, now the community will drop everything and review your changes. (Just
kidding - be patient!)
+[[v2-git-send-email]]
=== Sending v2
Skip ahead to <<reviewing,Responding to Reviews>> for information on how to
@@ -944,6 +976,7 @@ $ git send-email --to=target@example.com
psuh/v2*
----
+[[single-patch]]
=== Bonus Chapter: One-Patch Changes
In some cases, your very small change may consist of only one patch. When that
@@ -991,6 +1024,7 @@ index 88f126184c..38da593a60 100644
2.21.0.392.gf8f6787159e-goog
----
+[[now-what]]
== My Patch Got Emailed - Now What?
[[reviewing]]
@@ -1034,6 +1068,7 @@ changing history, but since it's local history which you haven't shared with
anyone, that is okay for now! (Later, it may not make sense to do this; take a
look at the section below this one for some context.)
+[[after-approval]]
=== After Review Approval
The Git project has four integration branches: `pu`, `next`, `master`, and
--
2.21.0.1020.gf2820cf01a-goog
next prev parent reply other threads:[~2019-05-17 19:08 UTC|newest]
Thread overview: 44+ messages / expand[flat|nested] mbox.gz Atom feed top
2019-04-11 18:32 [PATCH 0/1] documentation: add lab for first contribution Emily Shaffer via GitGitGadget
2019-04-11 18:32 ` [PATCH 1/1] " Emily Shaffer via GitGitGadget
2019-04-12 3:20 ` Junio C Hamano
2019-04-12 22:03 ` Emily Shaffer
2019-04-13 5:39 ` Junio C Hamano
2019-04-15 17:26 ` Emily Shaffer
2019-04-11 21:03 ` [PATCH 0/1] " Josh Steadmon
2019-04-12 2:35 ` Junio C Hamano
2019-04-12 22:58 ` Emily Shaffer
2019-04-16 20:26 ` [PATCH v2 " Emily Shaffer via GitGitGadget
2019-04-16 20:26 ` [PATCH v2 1/1] " Emily Shaffer via GitGitGadget
2019-04-17 5:32 ` Junio C Hamano
2019-04-17 8:07 ` Eric Sunshine
2019-04-18 0:05 ` Junio C Hamano
2019-04-17 23:16 ` Emily Shaffer
2019-04-16 21:13 ` [PATCH v2 0/1] " Emily Shaffer
2019-04-19 16:57 ` [PATCH v3] " Emily Shaffer
2019-04-21 10:52 ` Junio C Hamano
2019-04-22 22:27 ` Emily Shaffer
2019-04-23 19:34 ` [PATCH v4] documentation: add tutorial " Emily Shaffer
2019-04-30 18:59 ` Josh Steadmon
2019-05-02 0:57 ` Emily Shaffer
2019-05-03 2:11 ` Phil Hord
2019-05-07 19:05 ` Emily Shaffer
2019-05-06 22:28 ` Jonathan Tan
2019-05-07 19:59 ` Emily Shaffer
2019-05-07 20:32 ` Jonathan Tan
2019-05-08 2:45 ` Junio C Hamano
2019-05-07 21:30 ` [PATCH v5 0/2] documentation: add lab " Emily Shaffer
2019-05-07 21:30 ` [PATCH v5 1/2] documentation: add tutorial " Emily Shaffer
2019-05-07 23:25 ` Emily Shaffer
2019-05-08 3:46 ` Junio C Hamano
2019-05-08 18:58 ` Emily Shaffer
2019-05-08 19:53 ` Jonathan Tan
2019-05-07 21:30 ` [PATCH v5 2/2] documentation: add anchors to MyFirstContribution Emily Shaffer
2019-05-08 3:30 ` [PATCH v5 0/2] documentation: add lab for first contribution Junio C Hamano
2019-05-17 19:03 ` [PATCH v6 0/2] documentation: add tutorial " Emily Shaffer
2019-05-17 19:07 ` [PATCH v6 1/2] " Emily Shaffer
2019-05-26 7:48 ` Christian Couder
2019-05-29 20:09 ` Emily Shaffer
2019-10-18 16:40 ` SZEDER Gábor
2019-10-18 22:54 ` Emily Shaffer
2019-05-17 19:07 ` Emily Shaffer [this message]
2019-05-29 20:18 ` [PATCH] doc: add some nit fixes to MyFirstContribution Emily Shaffer
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
List information: http://vger.kernel.org/majordomo-info.html
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20190517190701.49722-3-emilyshaffer@google.com \
--to=emilyshaffer@google.com \
--cc=git@vger.kernel.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this public inbox
https://80x24.org/mirrors/git.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).