Re: [PATCH v8 11/12] docs: move cruft pack docs to gitformat-pack

From: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
Date: Aug 5, 2022, 08:29 UTC
Message-ID: <220805.86h72rrsuc.gmgdl@evledraar.gmail.com>
In-Reply-To: <xmqq5yj73d6l.fsf@gitster.g>

On Thu, Aug 04 2022, Junio C Hamano wrote:

Show 26 quoted lines

> Ævar Arnfjörð Bjarmason  <avarab@gmail.com> writes:
>
>> Integrate the cruft packs documentation initially added in
>> 3d89a8c1180 (Documentation/technical: add cruft-packs.txt, 2022-05-20)
>> to the newly created "gitformat-pack" documentation.
>>
>> Like the "bitmap-format" added before it in
>> 0d4455a3ab0 (documentation: add documentation for the bitmap format,
>> 2013-11-14) the "cruft-packs" were documented in their own file.
>>
>> As the diff move detection will show there is no change to
>> "Documentation/technical/cruft-packs.txt" here except to move it, and
>> to "indent" the existing sections by adding an extra "=" to them.
>>
>> We could similarly convert the "bitmap-format.txt", but let's leave it
>> for now due to a conflict with the in-flight ac/bitmap-lookup-table
>> series.
>>
>> Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
>> ---
>
> OK, so this round we roll the "cruft packs" into the main "pack file
> format" documentation, because the former is merely a minor deviation
> at file format level (i.e. comes with an extra .mtimes file) and the
> philosophy behind how they are meant to be used is what makes them,
> that is mostly the same as the normal packs, different.

Yes, perhaps we should split all of these out, but it's a smaller logical change to just bundle the ones that were split out into the main documentation.

> That makes sense to me, and I agree that in the longer term we may
> want to treat the pack bitmap format documentation the same way.

I have that patch locally already, and figured I'd send it in shortly after this lands. I just didn't want to burden you with the merge conflict with c7e7f5dd814 (Documentation/technical: describe bitmap lookup table extension, 2022-07-20).

The merge conflict is relatively easy to deal with, I included a resolution in the v3 of this series (but ejected the change out of v4): https://lore.kernel.org/git/cover-v3-0.7-00000000000-20220712T195419Z-avarab@gmail.com/

I can still re-roll with it if you'd like it sooner than later, or ac/bitmap-lookup-table could be re-rolled on top of this topic eventually (it seems it needs an eventual re-roll anyway due to SHA-256 flakyness).

Or we could just go with the status quo here and leave it until the dust eventually settles, which is what I went with so far.