doc: fix the stale link to api-builtin.txt
PATCH 1/1 doc: fix the stale link to api-builtin.txt
From: Kazuo Yagi <[email protected]>
ec14d4e had moved documentation from api-builtin.txt to builtin.h. This patch updates new-command.txt to reflect that change.
---
Fixed unavailable link in Documentation/howto/new-command.txt along…
… with the changeset history.
Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-git-647%2Fkyagi%2Ffix-unavailable-link-v1
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-647/kyagi/fix-unavailable-link-v1
Pull-Request: https://github.com/git/git/pull/647
Documentation/howto/new-command.txt | 6 +++--- builtin.h | 25 +++++++++++++++++++++++++ 2 files changed, 28 insertions(+), 3 deletions(-)
Documentation/howto/new-command.txt +3 -3
@@ -1,13 +1,13 @@ From: Eric S. Raymond <[email protected]> Abstract: This is how-to documentation for people who want to add extension - commands to Git. It should be read alongside api-builtin.txt. + commands to Git. It should be read alongside builtin.h. Content-type: text/asciidoc How to integrate new subcommands ================================ This is how-to documentation for people who want to add extension -commands to Git. It should be read alongside api-builtin.txt. +commands to Git. It should be read alongside builtin.h. Runtime environment -------------------
@@ -48,7 +48,7 @@ binary); this organization makes it easy for people reading the code to find things. See the CodingGuidelines document for other guidance on what we consider -good practice in C and shell, and api-builtin.txt for the support +good practice in C and shell, and builtin.h for the support functions available to built-in commands written in C. What every extension command needs
builtin.h +25 -0
@@ -92,6 +92,31 @@* * The return value from `cmd_foo()` becomes the exit status of the * command. +* +* Changeset History +* ----------------- +* +* The following describes how the documentation has finally been placed +* in this file, over the related changesets. +* +* +-----------------+ *OLD LINK* +-----------------+ +* | api-builtin.txt | <~~~~~~~~~~ | api-command.txt | +* +-----------------+ +-----------------+ +* | ~ * | +* | deleted, ~ N | moved and renamed from +* | contents is taken over ~ E | Documentation/technical/ +* | by builtin.h ~ W | to +* | (this file) ~ | Documentation/howto/ +* | ~ L | +* | ~ I | +* v ~ N v +* +-----------+ ~ K +-----------------+ +* | builtin.h | <~~~~~~~~~~~~ * | new-command.txt | +* +-----------+ +-----------------+ +* +* ---> moved to(or renamed to) +* ~~~> refers to +* */ #define DEFAULT_MERGE_LOG_LEN 20
base-commit: 3cb8921f74354a3a4aeaa932869acb7e6aabe630
Signature · 1 line
gitgitgadget
(+Emily Shaffer, author of the related MyFirstContribution tutorial) Hi,
Quoted 4 lines · Kazuo Yagi
From: Kazuo Yagi <[email protected]>
Subject: doc: fix the stale link to api-builtin.txtec14d4e had moved documentation from api-builtin.txt to
builtin.h.
Micronits:
- use "git log -1 --format=reference"
- changes due to previous commits go in the simple past tense, like "Commit ec14d4e moved [...]"
Quoted 1 line
This patch updates new-command.txt to reflect that change.
nit: describe what your patch does as though you are giving orders to the codebase to change. Focus on what benefit you are trying to bring about.
Quoted 2 lines
Signed-off-by Kazuo Yagi <[email protected]>---
[...]
Quoted 1 line
along with the changeset history.
This part didn't make it into the commit message, but I think you intended it to do so. Putting that all together would make
new-command doc: fix stale link to api-builtin.txt
ec14d4ecb55 (builtin.h: take over documentation from api-builtin.txt, 2017-08-02) moved the documentation for Git's builtin API to the header file. Update the "new command" how-to doc to reflect that change.
While we're here, add a historical note to builtin.h.
[...]
Documentation/howto/new-command.txt line 3
Quoted 7 lines
Documentation/howto/new-command.txt +1
-1@@ -1,13 +1,13 @@ From: Eric S. Raymond <[email protected]> Abstract: This is how-to documentation for people who want to add extension - commands to Git. It should be read alongside api-builtin.txt. + commands to Git. It should be read alongside builtin.h.
Makes sense.
[...]
Documentation/howto/new-command.txt line 10
Quoted 6 lines
Documentation/howto/new-command.txt +1
-1How to integrate new subcommands ================================ This is how-to documentation for people who want to add extension -commands to Git. It should be read alongside api-builtin.txt. +commands to Git. It should be read alongside builtin.h.
Likewise. It's probably worth pointing to Documentation/MyFirstContribution as well, which is a tutorial covering this subject in more detail.
(Actually, would it make sense to incorporate the information from howto/new-command.txt into that page and then to retire the old new-command doc?)
[...]
Documentation/howto/new-command.txt binary); this organization makes it easy for people reading the code · line 52
Quoted 7 lines
Documentation/howto/new-command.txt +1
-1@@ -48,7 +48,7 @@ binary); this organization makes it easy for people reading the code to find things. See the CodingGuidelines document for other guidance on what we consider -good practice in C and shell, and api-builtin.txt for the support +good practice in C and shell, and builtin.h for the support functions available to built-in commands written in C.
Most support functions are part of other APIs, so this was a strange pointer in the first place. But the change makes sense.
It's also a bit odd that this doc doesn't mention SubmittingPatches.
[...]
builtin.h line 100
Quoted 12 lines
builtin.h +6
-0@@ -92,6 +92,31 @@* * The return value from `cmd_foo()` becomes the exit status of the * command. +* +* Changeset History +* ----------------- +* +* The following describes how the documentation has finally been placed +* in this file, over the related changesets.
*puzzled* Why is this information being added to the builtin.h file? What is the reader trying to do when they read it?
Thanks and hope that helps,
Jonathan
Quoted 22 lines
builtin.h +19
-0+* +* +-----------------+ *OLD LINK* +-----------------+ +* | api-builtin.txt | <~~~~~~~~~~ | api-command.txt | +* +-----------------+ +-----------------+ +* | ~ * | +* | deleted, ~ N | moved and renamed from +* | contents is taken over ~ E | Documentation/technical/ +* | by builtin.h ~ W | to +* | (this file) ~ | Documentation/howto/ +* | ~ L | +* | ~ I | +* v ~ N v +* +-----------+ ~ K +-----------------+ +* | builtin.h | <~~~~~~~~~~~~ * | new-command.txt | +* +-----------+ +-----------------+ +* +* ---> moved to(or renamed to) +* ~~~> refers to +* */ #define DEFAULT_MERGE_LOG_LEN 20
Quoted 8 lines · Jonathan Nieder
Quoted 5 lines
+ * Changeset History
+ * -----------------
+ *
+ * The following describes how the documentation has finally been placed
+ * in this file, over the related changesets.*puzzled* Why is this information being added to the
builtin.hfile? What is the reader trying to do when they read it?
Thanks for an excellent review, but you are being a bit too subtle and/or diplomatic here.
A good rule of thumb to use when judging if a comment is appropriate to have in the tracked data is if it talks about what used to be the case in order to explain why it is in the current shape. Often, such description is useless for people going forward starting from the current codebase, and is better described in the log message, and I think that this is a prime example. As an explanation to justify why it is good to refer to builtin.h from the current documentation that teaches what needs to be done to add a new command, instead of api-builtin.txt, it is valuable to know how the description of the API used to support builtin commands moved over time from place to place (preferrably with references to the commits that did so), and it belongs to the log message of this commit that updates the reference to api-builtin.txt to builtin.h.