From: Patrick Steinhardt <ps@pks.im>
To: Junio C Hamano <gitster@pobox.com>
Cc: git@vger.kernel.org
Subject: Re: [RFC PATCH] docs: document upcoming breaking changes
Date: Wed, 8 May 2024 15:54:56 +0200 [thread overview]
Message-ID: <ZjuEMNsw-KARJjwx@tanuki> (raw)
In-Reply-To: <xmqqle4lnuvy.fsf@gitster.g>
[-- Attachment #1: Type: text/plain, Size: 2635 bytes --]
On Tue, May 07, 2024 at 03:02:09PM -0700, Junio C Hamano wrote:
> Patrick Steinhardt <ps@pks.im> writes:
>
> > Over time, Git has grown quite a lot. With this evolution, many ideas
> > that were sensible at the time they were introduced are not anymore and
> > are thus considered to be deprecated. And while some deprecations may be
> > noted in manpages, most of them are actually deprecated in the "hive
> > mind" of the Git community, only.
>
> There may be a new way that we hope is more suitable for folks who
> are learning Git today that achieves the same goal as an old way.
> It rarely means that the old way goes away, even when the new way is
> more capable than the old way and the use case the new way covers is
> a strict superset of the old way.
>
> Such an introduction of a new way is *not* a breaking change.
> Everything the first paragraph talks about is a "deprecation" that
> does not break anything. Documenting them is worthwhile, but it is
> worth pointing out that it not what the title of the topic "upcoming
> breaking changes" covers.
>
> I think you should explicitly say that we deprecate but rarely
> remove and old ways are kept for backward compatibility in that
> introductory paragraph. Then propose "But we may want to remove old
> ways and deliberately break at a large version bump every 5 years".
> That will lead your readers more smoothly to the next paragraph.
Agreed, I'll something along these lines.
> > Introduce a new document that lists upcoming breaking changes to address
> > this issue. This document serves multiple purposes:
> >
> > - It is a way to facilitate discussion around proposed deprecations.
> >
> > - It allows users to learn about deprecations and speak up in case
> > they have good reasons why a certain feature should not be
> > deprecated.
> >
> > - It states intent and documents where the Git project wants to go.
>
> Another thing we may want to describe in such a document is what we
> do not want to drop and why, even when a new way that is a superset
> is available, which would give newbies with a natural "why don't we
> force everybody including the old timers to adopt new ways" question
> a reasonable answer.
Okay, I see how that may make sense for some parts. I guess one of the
motivations here is things like git-checkout(1) and git-switch(1) /
git-restore(1)?
Do we want to give this class a separate name? Deprecated may feel a bit
too strong in that context as it does imply eventual removal for many
folks (including me, I guess). Is "superseded" better?
Patrick
[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]
next prev parent reply other threads:[~2024-05-08 13:55 UTC|newest]
Thread overview: 97+ messages / expand[flat|nested] mbox.gz Atom feed top
2024-05-07 8:27 [RFC PATCH] docs: document upcoming breaking changes Patrick Steinhardt
2024-05-07 10:38 ` Johannes Schindelin
2024-05-08 13:55 ` Patrick Steinhardt
2024-05-07 22:02 ` Junio C Hamano
2024-05-08 13:54 ` Patrick Steinhardt [this message]
2024-05-08 14:58 ` Junio C Hamano
2024-05-08 15:59 ` Dragan Simic
2024-05-10 11:36 ` Patrick Steinhardt
2024-05-10 12:43 ` Dragan Simic
2024-05-08 13:15 ` Phillip Wood
2024-05-08 13:55 ` Patrick Steinhardt
2024-05-10 2:15 ` Justin Tobler
2024-05-10 4:47 ` Junio C Hamano
2024-05-14 6:50 ` Patrick Steinhardt
2024-05-14 6:16 ` [RFC PATCH v2] " Patrick Steinhardt
2024-05-14 10:48 ` Karthik Nayak
2024-05-14 11:22 ` Patrick Steinhardt
2024-05-14 15:45 ` Junio C Hamano
2024-05-14 12:32 ` Dragan Simic
2024-05-24 12:54 ` [PATCH v3] " Patrick Steinhardt
2024-05-24 17:27 ` Junio C Hamano
2024-05-30 12:04 ` Patrick Steinhardt
2024-05-30 3:23 ` Commands using -h as an option don't work consistently Junio C Hamano
2024-06-03 18:33 ` Junio C Hamano
2024-06-03 20:05 ` [PATCH 0/3] Branches are branches and not heads Junio C Hamano
2024-06-03 20:05 ` [PATCH 1/3] refs: call branches branches Junio C Hamano
2024-06-03 21:32 ` Eric Sunshine
2024-06-03 20:05 ` [PATCH 2/3] ls-remote: introduce --branches and deprecate --heads Junio C Hamano
2024-06-03 21:30 ` Rubén Justo
2024-06-03 21:42 ` Eric Sunshine
2024-06-03 21:48 ` Junio C Hamano
2024-06-03 20:05 ` [PATCH 3/3] show-ref: " Junio C Hamano
2024-06-03 21:32 ` [PATCH 0/3] Branches are branches and not heads Rubén Justo
2024-06-04 7:56 ` Patrick Steinhardt
2024-06-04 22:01 ` [PATCH v2 " Junio C Hamano
2024-06-04 22:01 ` [PATCH v2 1/3] refs: call branches branches Junio C Hamano
2024-06-04 22:01 ` [PATCH v2 2/3] ls-remote: introduce --branches and deprecate --heads Junio C Hamano
2024-06-06 9:39 ` Patrick Steinhardt
2024-06-06 15:18 ` Junio C Hamano
2024-06-04 22:01 ` [PATCH v2 3/3] show-ref: " Junio C Hamano
2024-06-14 19:32 ` Elijah Newren
2024-06-14 21:21 ` Junio C Hamano
2024-06-14 21:34 ` Elijah Newren
2024-06-14 21:42 ` Elijah Newren
2024-06-14 22:46 ` Junio C Hamano
2024-06-06 9:39 ` [PATCH v2 0/3] Branches are branches and not heads Patrick Steinhardt
2024-05-31 7:56 ` [PATCH v4 0/4] docs: document upcoming breaking changes Patrick Steinhardt
2024-05-31 7:56 ` [PATCH v4 1/4] docs: introduce document to announce " Patrick Steinhardt
2024-05-31 16:51 ` Junio C Hamano
2024-06-03 9:32 ` Patrick Steinhardt
2024-06-03 16:17 ` Junio C Hamano
2024-06-04 7:42 ` Patrick Steinhardt
2024-05-31 7:56 ` [PATCH v4 2/4] BreakingChanges: document upcoming change from "sha1" to "sha256" Patrick Steinhardt
2024-05-31 17:00 ` Junio C Hamano
2024-05-31 7:56 ` [PATCH v4 3/4] BreakingChanges: document removal of grafting Patrick Steinhardt
2024-05-31 7:56 ` [PATCH v4 4/4] BreakingChanges: document that we do not plan to deprecate git-checkout Patrick Steinhardt
2024-05-31 17:05 ` Junio C Hamano
2024-05-31 23:35 ` Todd Zullinger
2024-05-31 8:43 ` [PATCH v4 0/4] docs: document upcoming breaking changes Junio C Hamano
2024-05-31 11:15 ` Patrick Steinhardt
2024-06-03 9:28 ` [PATCH v5 " Patrick Steinhardt
2024-06-03 9:28 ` [PATCH v5 1/4] docs: introduce document to announce " Patrick Steinhardt
2024-06-03 14:08 ` Phillip Wood
2024-06-03 16:24 ` Junio C Hamano
2024-06-04 6:59 ` Patrick Steinhardt
2024-06-03 9:28 ` [PATCH v5 2/4] BreakingChanges: document upcoming change from "sha1" to "sha256" Patrick Steinhardt
2024-06-03 16:36 ` Junio C Hamano
2024-06-04 7:06 ` Patrick Steinhardt
2024-06-04 17:16 ` Junio C Hamano
2024-06-03 9:28 ` [PATCH v5 3/4] BreakingChanges: document removal of grafting Patrick Steinhardt
2024-06-03 16:42 ` Junio C Hamano
2024-06-03 9:28 ` [PATCH v5 4/4] BreakingChanges: document that we do not plan to deprecate git-checkout Patrick Steinhardt
2024-06-03 16:52 ` Junio C Hamano
2024-06-04 7:11 ` Patrick Steinhardt
2024-06-04 12:32 ` [PATCH v6 0/4] docs: document upcoming breaking changes Patrick Steinhardt
2024-06-04 12:32 ` [PATCH v6 1/4] docs: introduce document to announce " Patrick Steinhardt
2024-06-04 17:59 ` Junio C Hamano
2024-06-05 5:31 ` Patrick Steinhardt
2024-06-05 16:03 ` Junio C Hamano
2024-06-05 17:52 ` Junio C Hamano
2024-06-06 4:35 ` Patrick Steinhardt
2024-06-04 12:32 ` [PATCH v6 2/4] BreakingChanges: document upcoming change from "sha1" to "sha256" Patrick Steinhardt
2024-06-04 12:32 ` [PATCH v6 3/4] BreakingChanges: document removal of grafting Patrick Steinhardt
2024-06-04 18:00 ` Junio C Hamano
2024-06-04 12:32 ` [PATCH v6 4/4] BreakingChanges: document that we do not plan to deprecate git-checkout Patrick Steinhardt
2024-06-04 14:23 ` [PATCH v6 0/4] docs: document upcoming breaking changes Phillip Wood
2024-06-04 18:01 ` Junio C Hamano
2024-06-05 5:32 ` Patrick Steinhardt
2024-06-14 6:42 ` [PATCH v7 " Patrick Steinhardt
2024-06-14 6:42 ` [PATCH v7 1/4] docs: introduce document to announce " Patrick Steinhardt
2024-06-14 16:08 ` Junio C Hamano
2024-06-14 6:42 ` [PATCH v7 2/4] BreakingChanges: document upcoming change from "sha1" to "sha256" Patrick Steinhardt
2024-06-14 6:42 ` [PATCH v7 3/4] BreakingChanges: document removal of grafting Patrick Steinhardt
2024-06-14 6:42 ` [PATCH v7 4/4] BreakingChanges: document that we do not plan to deprecate git-checkout Patrick Steinhardt
-- strict thread matches above, loose matches on Subject: below --
2024-05-29 22:03 Commands using -h as an option don't work consistently Kevin Day
2024-05-29 22:22 ` Junio C Hamano
2024-05-29 22:40 ` Kevin Day
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=ZjuEMNsw-KARJjwx@tanuki \
--to=ps@pks.im \
--cc=git@vger.kernel.org \
--cc=gitster@pobox.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).