Re: doc: add missing "id" attributes to extension packaging page

From: Corey Huinker <corey(dot)huinker(at)gmail(dot)com>
To: Brar Piening <brar(at)gmx(dot)de>
Cc: Alvaro Herrera <alvherre(at)alvh(dot)no-ip(dot)org>, "Karl O(dot) Pinc" <kop(at)karlpinc(dot)com>, Peter Eisentraut <peter(dot)eisentraut(at)enterprisedb(dot)com>, Tom Lane <tgl(at)sss(dot)pgh(dot)pa(dot)us>, vignesh C <vignesh21(at)gmail(dot)com>, Ian Lawrence Barwick <barwick(at)gmail(dot)com>, pgsql-hackers <pgsql-hackers(at)postgresql(dot)org>
Subject: Re: doc: add missing "id" attributes to extension packaging page
Date: 2023-03-23 19:40:45
Message-ID: CADkLM=d16C_aG2UZLTnZ+_D_od1ysh2Atm-=-uOiY8wfRyZyUA@mail.gmail.com
Views: Raw Message | Whole Thread | Download mbox | Resend email
Thread:
Lists: pgsql-hackers

>
> TBH I'm a bit afraid that people will immediately start complaining
> about the failing docs builds after this got applied since it forces
> them to add ids to all varlistenries in a variablelist if they add one,
> which can be perceived as quite a burden (also committers and reviewers
> will have to get used to always watch out for failing docs builds
> because of this).
>

As a person who had to re-rebase a patch because I discovered that id tags
had been added to one of the files I was working on, I can confidently say
"don't worry". It wasn't that big of a deal, I wasn't even following this
thread at the time and I immediately figured out what had happened and what
was expected of me. So it isn't that much of an inconvenience. If there is
a negative consequence to this change, it would be that it might
incentivize patch writers to omit documentation completely at the early
stages. But I don't think that's a problem because people generally see a
lack of documentation as a clue that maybe the patch isn't ready to be
reviewed, and this change would only reinforce that litmus test.

I had suggested we do something like this a few years back (the ids, that
is. the idea that we could check for compliance was beyond my imagination
at the time), and I'm glad to see both finally happening.

While I can foresee people overlooking the docs build, such oversights
won't go long before being caught, and the fix is simple. Now if we can
just get a threaded version of xlstproc to make the builds faster...

p.s. I'm "Team Paperclip" when it comes to the link hint, but let's get the
feature in first and worry about the right character later.

In response to

Responses

Browse pgsql-hackers by date

  From Date Subject
Next Message Greg Stark 2023-03-23 20:05:23 Re: Code checks for App Devs, using new options for transaction behavior
Previous Message Robert Haas 2023-03-23 19:39:31 Re: Non-superuser subscription owners