Re: [PATCHv2] Update gitworkflows man page to include release workflow

From: Thomas Rast <trast@student.ethz.ch>
Date: Nov 12, 2009, 08:10 UTC
Message-ID: <200911120910.57091.trast@student.ethz.ch>
In-Reply-To: <4AFB57A3.2020002@fastmail.fm>

Raman Gupta wrote:

Show 15 quoted lines

> Junio C Hamano wrote:
> > Please set the tone straight.  If this is to suggest various possible
> > workflows in general vague terms, "may use" would be good.  If this is to
> > precisely describe what I do, then there won't be "you could do this, or
> > you could do that."  Your "may use" suggests the former, but the commit
> > log message claims the latter.  Which document are you writing?
> 
> Ok. The current document is inconsistent. In places it uses "the
> maintainer" and in other places it uses "you". In any case, it seems
> that the "maintainer" here is not "Junio Hamano" -- rather, it is the
> reader.
> 
> Let me create a separate (and first) cleanup patch to fix the existing
> inconsistencies in this man page. I would prefer to use the pronoun
> "you" consistently as also suggested by Thomas Rast.

Well, I'm not sure if this is also in reply to my comment

} The current gitworkflows is mostly formulated in the imperative, [...] } or by directly describing the tools in the third person, [...]

but note that I do not consider the current form to be inconsistent (though you may of course convince me otherwise). It addresses the presumed user with "you", which is not always the maintainer. For example, when talking about patch submission we have

  If the maintainer tells you that your patch no longer applies to the
  current upstream, you will have to rebase your topic (you cannot use a
  merge because you cannot format-patch merges):

since the presumed user of a patch-submission workflow is a contributor, not the maintainer. Indeed much of the text talks *about* the workflow used by our esteemed maintainer, but is addressed to a contributor who wants to understand how it works so he can participate.

IOW, I'm neither a native speaker nor a professional writer, so you may of course convince me that there is something to fix. I am, however, fairly sure that s/maintainer/you/ and then fixing the grammar is *not* a good thing.

[BTW, it would have been nice to get a Cc to begin with, since the entire manpage blames to me. I noticed the thread anyway, but other times I do not have the time to scan the entire list.]

-- 
Thomas Rast
trast@{inf,student}.ethz.ch