Re: [PATCH 4/5] doc: use .adoc extension for AsciiDoc files

[Junio C Hamano <gitster@pobox.com>]

"brian m. carlson" <sandals@crustytoothpaste.net> writes:

> On 2025-01-20 at 20:37:10, Jean-Noël Avila wrote:
>> Maybe for users of the end product of the documentations compiled here,
>> but there are other users who use the source files and this change
>> breaks their workflow pretty bad. I am one of those users for the
>> git-scm.com website and the manpage translation projects.
>
> I appreciate that this is a big change, but we do also sometimes make
> those and contributors and downstreams need to change over eventually.

Yup.  FWIW, this change would break my private toolings by renaming
things under Documentation/RelNotes/, which I did not think we even
pass through AsciiDoc, even though by inertia I write something akin
to AsciiDoc in these release note files.

But all who are on the creator side of the ecosystem are expected to
adjust to the upstream changes and that includes me and those who
format git-scm.com.  They are much less protected by the
backward-compatibility promise than the end users as they are
expected to be much much more competent to adjust to changes, and
more importantly, they are more aware of the chance to speak up
before too late to influence the course of the upstream.

In this particular case, I would imagine that the use cases of
myself and Jean-Noël would _eventually_ want to be adjusted to deal
with anything the upstream picks as the file extension that may or
may not be ".txt" (to put it differently, they are written to expect
that these files end with ".txt", but the _ONLY_ reason why they are
is because those files in my tree _happen_ to have such names).  We
certainly do not want to make a change like this unnecessarily and
unannounced.  But with sufficient advance warning and enough time to
prepare transition, it shouldn't too bad.

Perhaps it may be enough keep the topic cooking a lot longer in
'next' than usual one calendar week.  This of course requires that
those on the creator side echosystem are paying attention to 'next',
are capable of writing necessary adjustment (in my case, I would
tweak my tooling so that it uses "$filename.$suffix" instead of
hardcoded "txt" in the rest of the script, checks the presence of
Documention/git.adoc to tweak suffix from default "txt") for their
tooling, and can arrange to test their tooling with 'next'.

>> Maybe a smoother transition could be performed by creating links between
>> txt and adoc files.
>
> I'd prefer if we didn't do that, but we could.  My concern is that will
> actually make the patch even larger, possibly to the point it might not
> fit on the list.

I do not like that, either, for all the reasons you meantioned
below.

Thanks.

> We'll also want to eventually drop the symlinks if we add them now,
> which means that the breaking changes you mentioned above that you
> didn't want to make will need to be made eventually.  Is it that you
> want more of a grace period to do that, or that you're opposed to having
> to make the change at all?