Re: [PATCH 4/5] doc: use .adoc extension for AsciiDoc files
- From
Junio C Hamano <gitster@pobox.com>
- Date
- Jan 20, 2025, 23:43 UTC
- Message-ID
- <xmqqmsfl2gro.fsf@gitster.g>
- In-Reply-To
- <Z47JUbdzMtz1CTMg@tapette.crustytoothpaste.net>
"brian m. carlson" <sandals@crustytoothpaste.net> writes:
Show 8 quoted lines
> 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'.
Show 6 quoted lines
>> 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.
Show 5 quoted lines
> 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?