Re: [RFC/PATCH] Formatting variables in the documentation

From: Junio C Hamano <gitster@pobox.com>
Date: May 26, 2016, 16:18 UTC
Message-ID: <xmqqmvncyera.fsf@gitster.mtv.corp.google.com>
In-Reply-To: <20160526043607.GB6756@sigill.intra.peff.net>

Jeff King <peff@peff.net> writes:

Show 22 quoted lines

> On Mon, May 23, 2016 at 07:57:43PM +0200, Matthieu Moy wrote:
>
>> Samuel GROOT <samuel.groot@ensimag.grenoble-inp.fr> writes:
>> 
>> > Since 2.8.3 was out recently, we could flip MAN_BOLD_LITERAL on by
>> > default for this cycle to shake out problems as Jeff King suggested
>> > [2].
>> 
>> 2.8.3 was a bufix release, and flipping a controversial flag should
>> clearly not be done on a bugfix release. So, in this context, "beginning
>> of a cycle" means after a x.y.0 release.
>> 
>> Anyway, a patch enabling MAN_BOLD_LITERAL by default would need to cook
>> in pu and next as any other patches, so the time when the patch is sent
>> does not really matter.
>
> Yeah, I think a reasonable plan is:
>
>   1. Somebody produces a patch flipping the default. The patch is
>      trivial, but the commit message should tell why, and try to dig up
>      any possible problems we might see (e.g., why wasn't this the
>      default? Particular versions of tools? Some platforms?)

"git log -SBOLD_LITERAL Documentation/" tells me that it's not like we had this on by default sometime in the past and then we flipped the default back in response to some problems (which I forgot about).

I just re-read the two iterations that introduced BOLD_LITERAL:

 * http://news.gmane.org/find-root.php?message_id=<1237881866-5497-1-git-send-email-chris_johnsen@pobox.com>

 * http://news.gmane.org/find-root.php?message_id=<1238136245-22853-1-git-send-email-chris_johnsen@pobox.com>

There was no particular "caveat" raised there to recommend against using this on particular versions of tools or platforms. It was inertia that has kept the new optional feature "optional".

>   2. Assuming no problems, Junio merges the patch to "next". We get
>      any reports of issues from people using "next" day-to-day.

So I can do these steps myself up to this point. After waiting for a few days to see if somebody else with better memory tells me what I forgot, perhaps.

Show 13 quoted lines

>   3. Assuming no problems, Junio merges to "master". We hit more people
>      (who build from master). And also it would be part of the
>      pre-generated pages that Junio ships, so we might get reports
>      there.
>
>   4. Eventually it's released. We hope to get no problem reports there,
>      though it _does_ hit a wider audience at that point.
>
> Steps 1 and 2 can happen now. As we are in the -rc cycle right now,
> probably step 3 would happen post-v2.9. But there's no reason not to
> start the clock ticking now.
>
> -Peff