Re: [RFC/PATCH 0/2] Documentation: kicking the "reset --hard" habit

From: J. Bruce Fields <bfields@fieldses.org>
Date: Nov 1, 2010, 20:03 UTC
Message-ID: <20101101200333.GG2340@fieldses.org>
In-Reply-To: <AANLkTiknyZBeWY8Z14EF+uq_2feJxJniVBwpwjUHgdEF@mail.gmail.com>

On Sun, Oct 31, 2010 at 05:25:20PM +0000, Ævar Arnfjörð Bjarmason wrote:

Show 18 quoted lines

> On Sat, Oct 30, 2010 at 01:55, Matthieu Moy
> <Matthieu.Moy@grenoble-inp.fr> wrote:
> 
> >> Sadly, at least the user manual change suggested below is probably
> >> not suitable, since reset --keep and --merge have not been around
> >> since git 1.5.3 days.  Ideas for working around that and other
> >> comments would be welcome.
> >
> > Do we really want to keep the user manual compatible with 1.5.3
> > forever? It's nice to keep the user manual usable by slightly outdated
> > Gits, but 1.5.3 starts being really old, and older docs are still
> > available on the web (like
> > http://www.kernel.org/pub/software/scm/git/docs/v1.5.3.8/git.html ).
> 
> I didn't know we even did this with our user manual. When I read
> manuals for version X (e.g. PostgreSQL, Emacs or libc versions) I
> fully expect the features described to only work on the documented
> version unless otherwise noted.

Yeah, previous versions of the user manual are still around if people need them. For a book or an independent website a wider range of versions would make more sense, but for documentation destributed with the git source I think we can afford to be more aggressive.

If we think information about old versions is really important maybe someone could find a way to incorporate it in a way that doesn't intrude into the main text too much (e.g. footnotes or an appendix.)

--b.