Re: [PATCH v3 1/6] Documentation/technical: describe bitmap lookup table extension

[Abhradeep Chakraborty <chakrabortyabhradeep79@gmail.com>]

Hello Philip,

Philip Oakley <philipoakley@iee.email> wrote:

> Not sure if this is new in this extension, but should there be a link or
> two to the basics of XOR compression and some of the bitmap look up
> techniques?
>
> It's not always obvious if these techniques are 'heuristic' and only
> have partial commit data, or they have all the commits listed, Nor
> how/why they work. My point is more about giving new readers a hand-up
> in their understanding, rather than simple implementation details for
> those who already know what is going on. For example, are there any
> external articles that you found helpful in getting started that could
> be referenced somewhere in the docs?

As this series is only about adding a lookup-table extension (and not
about bitmap itself), I am not sure whether it's good to include those
things in this series. But I agree with your point that it should be
able build a logical understanding among the new readers.

There are some external articles[1] which talk about bitmap internals.
But I think it would be better if we can make a new doc file (may be
`Documentation/technical/reachability-bitmaps.txt` or similar) rather
than putting those details in the `bitmap-format.txt` (As the name 
suggests, this file should only contain format details of bitmaps).
That file would provide the answers of "Why bitmaps", "how they are
stored",  "How they are fetched", "how they work with pack-objects,
git-fetch, midx etc.", "Detailed explanation of each bitmap extension"
, and lastly "what are the future works" (if any).

What do you think?

> Separately I'm preparing a short series on adding 'reachability bitmap'
> and 'commit graph' (among other stuff) to the glossary as part of giving
> folks [0] stepping stones to cross the chasm of understanding

Great!

Thanks :)

[1] https://github.blog/2015-09-22-counting-objects/, https://github.blog/2021-04-29-scaling-monorepo-maintenance/