Re: [PATCH 2/2] Add Author and Documentation sections to git-for-each-ref.txt

Michael J Gruber [off-list ref] writes:

Just kidding!

(Jeff is the 2nd main f-e-r author, but Junio created it.)

Thanks for bringing this up.

In the very early days (like back when the project was only 12 months old)
it made sense to record that this and that command were primarily done by
that person.  But I don't think it is a good idea anymore.

For example, format-patch was my invention and all the code was mine back
when it was a script.  Later it was reimplemented in C by Dscho based on
my earlier work.  But a large part of the actual implementation was done
by using the generic revision traversal machinery, whose primary authors
back then were Linus and me.  The silly original UI design everybody hates
("format-patch <upstream>" is not similar to 'git log <upstream>..'") is
"owned" by me, the user facing main() implementation is "owned" by Dscho,
and the backend machinery is "owned" by Linus and me.

Who should we list, and more importantly, does it make sense to keep the
list up to date as the system evolves?

As the project and the community grew, and also as the internal machinery
infrastructure got more modularized, I think ownership at the individual
command level has become almost meaningless concept.

Same reasoning applies to the "Documented by".  I think it's time for
these two sections to go from most (if not all) pages.

On Wed, Mar 09, 2011 at 12:17:53PM -0800, Junio C Hamano wrote:

As the project and the community grew, and also as the internal machinery
infrastructure got more modularized, I think ownership at the individual
command level has become almost meaningless concept.

Same reasoning applies to the "Documented by".  I think it's time for
these two sections to go from most (if not all) pages.

Yeah, I would just as soon drop Author and Documented-by fields in all
manpages. We could replace them with a single "Credits" in git(1). It
can either mention nobody, very few people (like Linus as the originator
and Junio as the long-time maintainer), or the top N (for N < 20 or so)
people in shortlog. And then mention that you can run shortlog yourself.

I would probably do something like this:

diff --git a/Documentation/git.txt b/Documentation/git.txt
index 0c32d45..4323843 100644
--- a/Documentation/git.txt
+++ b/Documentation/git.txt

@@ -745,16 +745,10 @@ unmerged version of a file when a merge is in progress.
 
 Authors
 -------
-* git's founding father is Linus Torvalds <torvalds@osdl.org>.
-* The current git nurse is Junio C Hamano <gitster@pobox.com>.
-* The git potty was written by Andreas Ericsson <ae@op5.se>.
-* General upbringing is handled by the git-list <git@vger.kernel.org>.
-
-Documentation
---------------
-The documentation for git suite was started by David Greaves
-<david@dgreaves.com>, and later enhanced greatly by the
-contributors on the git-list <git@vger.kernel.org>.
+Git was started by Linus Torvalds, and is currently maintained by Junio
+C Hamano. Numerous contributions have come from the git mailing list
+<git@vger.kernel.org>. For a complete list of contributors, see
+linkgit:git-shortlog[1] and linkgit:git-blame[1].
 
 Reporting Bugs
 --------------

And then a follow-on patch to drop the Authors section from all of the
other pages.

-Peff

On 11 March 2011 00:37, Jeff King [off-list ref] wrote:

-The documentation for git suite was started by David Greaves
-[off-list ref], and later enhanced greatly by the
-contributors on the git-list [off-list ref].
+Git was started by Linus Torvalds, and is currently maintained by Junio
+C Hamano. Numerous contributions have come from the git mailing list
+[off-list ref]. For a complete list of contributors, see
+linkgit:git-shortlog[1] and linkgit:git-blame[1].

The last sentence could be a little bit more informative for casual
git-users, something like
  For a complete list of contributors, see http://git-scm.com/about,
or (if you are a true geek) linkgit:git-shortlog[1] and
linkgit:git-blame[1].

Other than that, I totally agree with the idea.

-- 
Best regards,
Alexei Sholik

On Sat, Mar 12, 2011 at 11:52:23AM +0200, Alexei Sholik wrote:

On 11 March 2011 00:37, Jeff King [off-list ref] wrote:

quoted

-The documentation for git suite was started by David Greaves
-[off-list ref], and later enhanced greatly by the
-contributors on the git-list [off-list ref].
+Git was started by Linus Torvalds, and is currently maintained by Junio
+C Hamano. Numerous contributions have come from the git mailing list
+[off-list ref]. For a complete list of contributors, see
+linkgit:git-shortlog[1] and linkgit:git-blame[1].

The last sentence could be a little bit more informative for casual
git-users, something like
  For a complete list of contributors, see http://git-scm.com/about,
or (if you are a true geek) linkgit:git-shortlog[1] and
linkgit:git-blame[1].

Yeah, I was tempted to put in explicit instructions but opted to keep it
simple. I forgot about the credits listing at git-scm.com, though. Maybe
this on top of my other patches?

-- >8 --
Subject: [PATCH] docs: point git.txt author credits to git-scm.com

There is a nice shortlog-ish output of the authors there. We
also point people directly to shortlog, but of course they
might be reading the documentation online or from a binary
package of git.

Signed-off-by: Jeff King <redacted>
---
 Documentation/git.txt |    6 ++++--
 1 files changed, 4 insertions(+), 2 deletions(-)

diff --git a/Documentation/git.txt b/Documentation/git.txt
index 4323843..5e57f69 100644
--- a/Documentation/git.txt
+++ b/Documentation/git.txt

@@ -747,8 +747,10 @@ Authors
 -------
 Git was started by Linus Torvalds, and is currently maintained by Junio
 C Hamano. Numerous contributions have come from the git mailing list
-<git@vger.kernel.org>. For a complete list of contributors, see
-linkgit:git-shortlog[1] and linkgit:git-blame[1].
+<git@vger.kernel.org>. For a more complete list of contributors, see
+http://git-scm.com/about. If you have a clone of git.git itself, the
+output of linkgit:git-shortlog[1] and linkgit:git-blame[1] can show you
+the authors for specific parts of the project.
 
 Reporting Bugs
 --------------

-- 
1.7.2.5.18.g3ffb9