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

[Patrick Steinhardt <ps@pks.im>]

[-- Attachment #1: Type: text/plain, Size: 4479 bytes --]

On Fri, May 31, 2024 at 09:51:25AM -0700, Junio C Hamano wrote:
> Patrick Steinhardt <ps@pks.im> writes:
[snip]
> > +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.

> > +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.

> > +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]
> > +### 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

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]