Re: [PATCH v4 1/4] docs: introduce document to announce breaking changes

From: Patrick Steinhardt <ps@pks.im>
Date: Jun 3, 2024, 09:32 UTC
Message-ID: <Zl2Np9qNcA6Z1q5U@framework>
In-Reply-To: <xmqqr0dhgc1e.fsf@gitster.g>

On Fri, May 31, 2024 at 09:51:25AM -0700, Junio C Hamano wrote:

> Patrick Steinhardt <ps@pks.im> writes:

[snip]

Show 21 quoted lines

> > +Regardless of that, due to the age of the Git project, it is only natural to
> > +accumulate a backlog of backwards-incompatible changes that will eventually be
> > +required to keep the project aligned with a changing world. These changes fall
> > +into several categories:
> > +
> > +  - Changes to long established defaults.
> > +
> > +  - Concepts that have been replaced with a superior design.
> > +
> > +  - Concepts, commands, configuration or options that have been lacking in major
> > +    ways and that cannot be fixed.
> 
> The first two are easy to imagine.  If we change the default, people
> may have to retrain their fingers or rewrite their scripts.  If
> "log" that came later is so good that even those who were using
> "whatchanged" have long switched to it, there will come time when
> nobody even notices a removal of "whatchanged".
> 
> But the third one is puzzling.  If something falls into the "cannot
> be fixed" category, is it still one of "These changes" that "will
> eventually be required to [be made]"?

Well, for a wider definition of "change", yes. In this case the change would be that the broken concept will be ripped out of Git without any replacement.

I'll clarify this a bit further.

Show 10 quoted lines

> > +The Git project will thus irregularly release major versions that deliberately
> > +break backwards compatibility with older versions. This is done to ensure that
> > +Git remains relevant, safe and maintainable going forward. The release cadence
> > +of major versions is typically measured in multiple years.
> 
> Releases vX.Y.Z (0 < Z) are "maintenance releases", and I have been
> calling vX.Y.0 "feature releases" instead of calling them "major
> versions", so the above use of the phrase "major version" can fit
> in, but a more descriptive name, e.g., "breaking versions", might
> convey the intention better, perhaps?

I was trying to stick to the names that semantic versioning uses here, but I'm happy to adapt this accordingly.

> It may be more assuring to cite the last time such a breaking
> version happened.  Was "Git 2.0" a breaking version?  If so, when
> did it happen?  Were there other breaking versions in the past?

I would definitely call Git 2.0 a breaking release as the changes to git-push(1)'s defaults were quite significant.

Other than that I think lines are a bit blurry. We do minor breaking changes sometimes in case certain behaviour is deemed to be buggy, and fixing such buggy behaviour may at times result in user visible changes in behaviour. I wouldn't call that a breaking release though, because we certainly want to retain the ability to fix such bugs without bumping the major version every single time. Going down that path just means that the whole versioning schema becomes meaningless, like it has become for so many other projects nowadays.

I'll also include a sentence along this line.

Show 10 quoted lines

> > +The intent of this document is to track upcoming deprecations for the next
> > +major Git release. Furthermore, this document also tracks what will _not_ be
> > +deprecated. This is done such that the outcome of discussions documente both
> > +when the discussion favors deprecation, but also when it rejects a deprecation.
> 
> We seem to focus on removals and changes; will there be a case where
> an upcoming addition is equally disrupting as removing an established
> thing?  If we wanted to avoid focusing on deprecation/removals too
> narrowly, we could tweak the wording below, with "deprecate a given
> feature" -> "make the described change", etc.

Hard to predict, I guess. Let's just rephrase it to be a bit more generic.

[snip]

Show 15 quoted lines

> > +### Changes
> > +
> > +### Removals
> > +
> > +## Superseded features that will not be deprecated
> > +
> > +Some features have gained newer replacements that aim to improve the design in
> > +certain ways. The fact that there is a replacement does not automatically mean
> > +that the old way of doing things will eventually be removed. This section tracks
> > +those superseded features.
> 
> As the title says "superseded", to help non native speakers like me,
> let's use a different and easier phrase with the same meaning in the
> body text.  "... tracks those features with newer alternatives",
> perhaps?

Sure, makes sense.

Patrick