From: Emily Shaffer <firstname.lastname@example.org> To: Heba Waly via GitGitGadget <email@example.com> Cc: firstname.lastname@example.org, Heba Waly <email@example.com>, Junio C Hamano <firstname.lastname@example.org> Subject: Re: [PATCH v2 1/1] config: move documentation to config.h Date: Tue, 22 Oct 2019 13:59:41 -0700 [thread overview] Message-ID: <20191022205941.GD9323@google.com> (raw) In-Reply-To: <email@example.com> On Tue, Oct 22, 2019 at 07:05:06AM +0000, Heba Waly via GitGitGadget wrote: > From: Heba Waly <firstname.lastname@example.org> > > Move the documentation from Documentation/technical/api-config.txt into > config.h This is still a little thin for what we usually want from commit messages. Try to imagine that five years from now, you find this commit by running `git blame` on config.h and then examining the commit which introduced all these comments with `git show <commit-id>` - what would you want to know? Typically we want to know "why" the change was made, because the diff shows "what". We can see from the diff that you're moving comments from A to B, but if you explain why you did so (not "because my Outreachy mentor told me to" ;) but "because it is useful to see usage information next to code" or "this is best practice as described by blah blah") - I wouldn't be able to know that reasoning just from looking at your diff. > diff --git a/config.h b/config.h > index f0ed464004..02f78ffc2b 100644 > --- a/config.h > +++ b/config.h > @@ -4,6 +4,23 @@ > #include "hashmap.h" > #include "string-list.h" > > + > +/** > + * The config API gives callers a way to access Git configuration files > + * (and files which have the same syntax). See linkgit:git-config for a Ah, here's another place where the Asciidoc link isn't going to do anything anymore. Otherwise I didn't still see anything jumping out. When the commit message is cleaned up I'm ready to add my Reviewed-by line. - Emily
next prev parent reply other threads:[~2019-10-22 20:59 UTC|newest] Thread overview: 16+ messages / expand[flat|nested] mbox.gz Atom feed top 2019-10-18 0:06 [PATCH 0/1] config: add " Heba Waly via GitGitGadget 2019-10-18 0:06 ` [PATCH 1/1] " Heba Waly via GitGitGadget 2019-10-18 22:07 ` Jonathan Tan 2019-10-20 8:05 ` Heba Waly 2019-10-18 22:51 ` Emily Shaffer 2019-10-20 8:35 ` Heba Waly 2019-10-22 20:42 ` Emily Shaffer 2019-10-22 7:05 ` [PATCH v2 0/1] [Outreachy] config: move " Heba Waly via GitGitGadget 2019-10-22 7:05 ` [PATCH v2 1/1] " Heba Waly via GitGitGadget 2019-10-22 20:59 ` Emily Shaffer [this message] 2019-10-23 2:14 ` Junio C Hamano 2019-10-23 4:55 ` Heba Waly 2019-10-23 5:30 ` [PATCH v3 0/1] [Outreachy] " Heba Waly via GitGitGadget 2019-10-23 5:30 ` [PATCH v3 1/1] " Heba Waly via GitGitGadget 2019-10-23 21:38 ` Emily Shaffer 2019-10-24 2:14 ` Junio C Hamano
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 * Reply using the --to, --cc, and --in-reply-to switches of git-send-email(1): git send-email \ --in-reply-to=20191022205941.GD9323@google.com \ --email@example.com \ --firstname.lastname@example.org \ --email@example.com \ --firstname.lastname@example.org \ --email@example.com \ --subject='Re: [PATCH v2 1/1] config: move documentation to config.h' \ /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
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 NNTP newsgroup(s).