[0/4] deprecating core.preferSymlinkRefs

Message

Junio C Hamano Sept. 18, 2024, 11:28 p.m. UTC

Removal of support for core.preferSymlinkRefs at Git 3.0 boundary,
so that we only write textual symrefs for things like HEAD and
refs/remotes/origin/HEAD, and still understand symbolic links used
as symrefs in existing repositories, is a serious proposal this
patch series makes.

But at the same time, this is an RFC.  I wrote it to serve as a
candidate for BCP, a guide to those who want to add an entry to the
breaking changes document.  I think anything that is described in
the breaking changes document has to become a patch series that
spans multi-year effort, and that must be done with care.

 - The proposal phase.  A breaking change is outlined, transition
   plan is given, and the first step of the transition (often,
   starting to give a warning and offering an alternative to the
   feature planned to be removed are involved) is presented.  The
   aim is that after N years, the user base will be aware of the
   upcoming removal and would already be prepared to be able to work
   with Git 3.0 that lacks the removed feature.

   In this series, [Patch 1/4] does this.

 - The Git 3.0 phase.  A breaking change is actually implemented.
   It optionally can offer help to those who procrastinated until
   the last-minute to break them, but the feature itself is gone.

   In this series, [PATCH 2/4] and [Patch 3/4] do this.

 - Clean-up phase.  If the previous phase added an additional
   transition help, after M years, such a help meant for transition
   would be removed.

   In this series, [PATCH 4/4] does this.

What I want people to think about is how to ensure quality of the
Git 3.0 phase.  We can iterate and polish the proposal phase with as
much time as we want to spend, just like any new feature.  But Git
3.0 phase is with a solid deadline, and before that time, we cannot
remove the feature for real.  Would we cook such steps in 'next'
forever until the actual Git 3.0?  To those users who are running
'next' based Git, it would mean that some of the changes the
breaking changes document listed would come a lot earlier to them.
On the other hand, unless we somehow have a way to expose willing
volunteers an early access to these "big changes", there is no way
for them to be as stable and tested.  We should not plan to scramble
and be able to perfect these changes between Git v3.0-rc0 and Git
v3.0 final.

Or perhaps use the "experimental.*" configuration stored in the
user's ~/.gitconfig to let users opt into Git 3.0 features (one of
which may be that textual symrefs are always used regardless of the
core.preferSymlinkRefs setting)?  That way, we can merge these big
changes early without worrying about accidentally affecting the
end-user population.

Junio C Hamano (4):
  refs: deprecate core.preferSymlinkRefs
  refs: mostly remove core.preferSymlinkRefs
  refs: remove NO_SYMLINK_HEAD
  refs: remove the last remnants of core.preferSymlinkRefs

 Documentation/BreakingChanges.txt   | 11 ++++++++
 Documentation/config/core.txt       |  6 -----
 Makefile                            |  6 -----
 config.c                            |  5 ----
 config.mak.uname                    |  3 ---
 configure.ac                        |  3 ---
 contrib/buildsystems/CMakeLists.txt |  2 +-
 environment.c                       |  1 -
 environment.h                       |  1 -
 refs/files-backend.c                | 26 -------------------
 t/t0600-reffiles-backend.sh         | 39 ++++++++++++++++-------------
 11 files changed, 34 insertions(+), 69 deletions(-)

Comments

Derrick Stolee Sept. 18, 2024, 11:38 p.m. UTC | #1

On 9/18/24 7:28 PM, Junio C Hamano wrote:
> Removal of support for core.preferSymlinkRefs at Git 3.0 boundary,
> so that we only write textual symrefs for things like HEAD and
> refs/remotes/origin/HEAD, and still understand symbolic links used
> as symrefs in existing repositories, is a serious proposal this
> patch series makes.

I missed a lot of this discussion about 3.0, but I'm fascinated by
the prospect.

> What I want people to think about is how to ensure quality of the
> Git 3.0 phase.  We can iterate and polish the proposal phase with as
> much time as we want to spend, just like any new feature.  But Git
> 3.0 phase is with a solid deadline, and before that time, we cannot
> remove the feature for real.  Would we cook such steps in 'next'
> forever until the actual Git 3.0?  To those users who are running
> 'next' based Git, it would mean that some of the changes the
> breaking changes document listed would come a lot earlier to them.
> On the other hand, unless we somehow have a way to expose willing
> volunteers an early access to these "big changes", there is no way
> for them to be as stable and tested.  We should not plan to scramble
> and be able to perfect these changes between Git v3.0-rc0 and Git
> v3.0 final.
> 
> Or perhaps use the "experimental.*" configuration stored in the
> user's ~/.gitconfig to let users opt into Git 3.0 features (one of
> which may be that textual symrefs are always used regardless of the
> core.preferSymlinkRefs setting)?  That way, we can merge these big
> changes early without worrying about accidentally affecting the
> end-user population.
I do like the idea of having someone set 'feature.git3=true' in
their global config and having that mean that they are ready to
accept the Git 3.0 breaking changes as they are available in
a Git 2.x release. As much early testing as we can get would be
beneficial.

This would be a way to get your patches 2 & 3 into 'master' and
released, but I'm not sure exactly how to keep patch 4 queued
for a potential future release. The best I could think of is to
have a long-running 'master-v3' branch that takes these cleanup
patches and then merges ongoing 'master' changes into them. It
would be a gross history to manage, but it could potentially
work. It does lead to concerns as to how to communicate that a
change to 'master' has broken the 'master-v3' CI or how an
incoming change could create conflicts with 'master-v3'.

Sorry I don't have full solutions for you. Only more problems.

Thanks,
-Stolee

Junio C Hamano Sept. 19, 2024, 12:26 a.m. UTC | #2

Derrick Stolee <[e-mail]> writes:

> I do like the idea of having someone set 'feature.git3=true' in
> their global config and having that mean that they are ready to
> accept the Git 3.0 breaking changes as they are available in
> a Git 2.x release. As much early testing as we can get would be
> beneficial.
>
> This would be a way to get your patches 2 & 3 into 'master' and
> released, but I'm not sure exactly how to keep patch 4 queued
> for a potential future release.

I actually am not worried about that one, i.e., "Clean-up phase",
even less than I would worry about the "Proposal phase".  Cleaning
up after the dust settles can be done at a leisurely pace after the
big version bump.

I think the feature.git3 opt-in knob would be a nice approach.
Thanks.