Re: Documentation for varbit is missing size parameter

On Fri, Mar 30, 2018 at 6:26 PM, Bruce Momjian <bruce(at)momjian(dot)us> wrote:

> On Fri, Mar 30, 2018 at 05:39:46PM +0200, Magnus Hagander wrote:
> > On Fri, Mar 30, 2018 at 5:18 PM, Bruce Momjian <bruce(at)momjian(dot)us> wrote:
> >
> > On Fri, Mar 16, 2018 at 01:17:04AM -0300, Euler Taveira wrote:
> > > 2018-03-11 1:43 GMT-03:00 PG Doc comments form <
> noreply(at)postgresql(dot)org>:
> > > > The documentation for the varbit data type is missing the size
> > parameter "[
> > > > (n) ]".
> > > >
> > > Good catch! It seems to be an oversight in commit
> > > 768b647ead78d0d63915c1708cad13c2468f9440. The attached patch adds
> it.
> >
> > Wow, that commit is from 2004. Patch applied and backpatched to v10.
> >
> >
> > If it goes all the way back to 2004, why not backpatch further?
>
> Uh, I am always debating how important it is to backpatck vs the churn
> we require of translations of our docs. In this case, it didn't seem
> worthwhile to have all of those translations try to deal with this
> change for all those back branches.
>
>
If it's a clean backpatch I'd say it is -- people who are using PostgreSQL
9.6 will be reading the documentation for 9.6 etc, so they will not know
about the fix then.

If it's not a clean backpatch I can certainly see considering it, but if
it's not a lot of effort then I'd say it's definitely worth it.

I really don't think considerations for translators of the *docs* are an
issue here. If you don't backpatch it, then nobody gets the fix. If you
backpatch it, then English readers do get the fix, and translated docs
readers *might* get the fix, depending on how they are maintained. It's not
like translatable strings where if they change in a backbranch they will
revert to English unless the translation is updated -- for the docs, they
just don't get the fix.

--
Magnus Hagander
Me: https://www.hagander.net/ <http://www.hagander.net/>
Work: https://www.redpill-linpro.com/ <http://www.redpill-linpro.com/>