On Mon, Sep 10, 2007 at 02:18:27PM -0700, Steven Grimm wrote:
> Joel Becker wrote:
>> The suggestions are pretty simple. First, when behavior is
>> changed invisibly (as the remote branch stuff was), can we note it in
>> the documentation? I don't mean the ChangeLog, I mean the manpage.
>
> Please, no. I understand where you're coming from with this request, but
> think of it from the point of view of non-long-time users (or users who
> have been keeping up with the changelog) who want to look up some piece of
> information. The last thing they want to have to do is read through a bunch
> of irrelevant information related to the behavior of obsolete versions of
> git they've never even used.
I do git clone. It doesn't do what it has always done. I think
it has failed. I check git-clone(7). I see nothing relevant. That's a
problem. You can't just claim "only people new to the system matter"
any more than "only people who follow git@xxxxxxxxxxxxxxx matter". In
fact, when you are silently changing existing behavior, it's the people
in between that will get bitten. The new user never knew the old way,
and the git@vger reader already knows.
> I guess I would be fine with the idea of the manpages saying something
> like, "Note: This is new as of version 1.X.Y; see git-changelog(7)." But
> that's as much intrusion from old versions of the software as I'd want in
> the reference manual, which is what the manpages really are.
It doesn't have to be a big discussion. It can be a short
section. It can call out to a different document. But let people know
that behavior has changed in a fashion that will break existing
expectations.
Joel
--
"The only way to get rid of a temptation is to yield to it."
- Oscar Wilde
Joel Becker
Principal Software Developer
Oracle
E-mail: joel.becker@xxxxxxxxxx
Phone: (650) 506-8127
-
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html
