Re: [PATCH 09/19] documentation: add documentation for the bitmap format

From: Shawn Pearce <spearce@spearce.org>
Date: Oct 30, 2013, 10:23 UTC
Message-ID: <CAJo=hJvOb=oooJ3O0wjxt77caGOMeKwT0VRaV=znMAzm0yNCYw@mail.gmail.com>
In-Reply-To: <20131030075040.GJ11317@sigill.intra.peff.net>

On Wed, Oct 30, 2013 at 7:50 AM, Jeff King <peff@peff.net> wrote:

Show 16 quoted lines

> On Fri, Oct 25, 2013 at 01:47:06PM +0000, Shawn O. Pearce wrote:
>
>> I think Colby and I talked about having additional optional sections
>> in this file, but Colby didn't want to overcomplicate the format early
>> on. So v1 is probably not very extensible and we may have to go to v2
>> to safely create an extension with the name hash cache used in this
>> series.
>>
>> Given that the JGit v1 bitmap format has been shipping since JGit 3.0
>> and in Gerrit Code Review 2.6, its in use in the wild. So we aren't
>> going to go back and redefine v1.
>
> I don't think either course of action affects how JGit in the wild will
> react. If we add a new flag to v1, existing JGit barfs. If we move to
> v2, existing JGit barfs.  In either case, the simplest fix for JGit is
> to ignore the new section.

Fair point. Then we can use v1 with the flag for now, JGit will barf and...

> If we want to define a v2 format and make it clear how to add optional
> sections, that's fine. But what I really want to avoid is a big v2
> bikeshedding discussion where other features get added because it's a
> version bump.

We can defer the v2 bikeshedding until after v1 lands and we get more experience with the format.

Show 8 quoted lines

> If that means dropping the name-hash cache from the series, so be it
> (that's part of why I pulled it out into its own patch at the end). We
> could also make it optional with a documentation warning that existing
> JGit will not like the resulting bitmap files. In practice, I do not
> expect it to be a big deal, as most sites will not mix-and-match serving
> from the two implementations (though you might repack with C git and
> serve with JGit, which means "off" would be the sane default for the
> feature).

The name-hash cache is probably important, but it would be nice to have a variable or flag we can use to disable the name-cache generation and thus permit Git to create JGit style v1 indexes, and also use JGit v1 indexes if the name-cache is not available.