Re: [PATCH 2/2] index-v4: document the entry format

Shawn Pearce [off-list ref] writes:

IMHO, keep this in next to avoid releasing it until we know the
outcome of the GSoC project. The handful of WebKit developers that use
Git that really benefit from index v4 can use it by building and
installing their own next.
...
Its only a few months to wait and see where "v5" goes. If v5 is
successful, v4 will just be a minor footnote in the history of Git,
and other tools won't need to support v4, they can go straight to v5.

You may not have noticed this, but there is no practical difference
between keeping it in 'next' and releasing it to 'master' from the
third-party tool's point of view.

There is _only_ one way to end up with v4 version of index: running "git
update-index --index-version 4".  When creating a new index, or working in
a repository, starting from an index written in the current version, you
will get v2 (or v3) index (this gentle handling of backward compatibility
comes from later parts of the series).  It is either running that command
or running 'next' version *and* running that command---either way, the
user deliberately has to ask for it, and if a third-party tool like jgit
chooses to ignore v4, it is not the end of the world.  The user opted-in
can run "git update-index --index-version 2" to revert it before using
such a tool.

For a third-party tool, lack of support of v4 is similar to not supporting
a config file that does not record the core.repositoryformatversion, which
the user can manually add it with the editor, and much less serious than
not supporting the v3 version of the index, which the user cannot do much
about it.

I would say that the cost of not merging the refactoring in the earlier
parts of the series and the gentler handling of backward compatibility in
the later parts of the series is much higher.