Обсуждение: Re: mention unused_oids script in pg_proc.dat

On 2025-May-24, Florents Tselai wrote:

> I aggree with having more READMEs around the src tree.
> It’s true that a lot of doc content found in VII. Internals is dev-oriented,
> but imho it should be closer to the src (and more succinct/less verbose too).

Maybe these READMEs can simply contain little more than links to the
built HTML docs, to avoid having multiple sources of info.

> Looking at some of the text in 67.2.2. OID Assignment for example,
> a few things look outdated wrt choosing OIDs.
> 
> One can look through the history of similar commits to see what
> needs to be changed; So it’s not THAT bad.

Sure, outdated docs is something that happens.  Patches welcome.

-- 
Álvaro Herrera        Breisgau, Deutschland  —  https://www.EnterpriseDB.com/
"Cómo ponemos nuestros dedos en la arcilla del otro. Eso es la amistad; jugar
al alfarero y ver qué formas se pueden sacar del otro" (C. Halloway en
La Feria de las Tinieblas, R. Bradbury)

On 24.05.25 12:34, Florents Tselai wrote:
> 
> 
>> On 24 May 2025, at 12:24 PM, Álvaro Herrera <alvherre@kurilemu.de> wrote:
>>
>> On 2025-May-24, Florents Tselai wrote:
>>
>>> I aggree with having more READMEs around the src tree.
>>> It’s true that a lot of doc content found in VII. Internals is dev-oriented,
>>> but imho it should be closer to the src (and more succinct/less verbose too).
>>
>> Maybe these READMEs can simply contain little more than links to the
>> built HTML docs, to avoid having multiple sources of info.
>>
>>> Looking at some of the text in 67.2.2. OID Assignment for example,
>>> a few things look outdated wrt choosing OIDs.
>>>
>>> One can look through the history of similar commits to see what
>>> needs to be changed; So it’s not THAT bad.
>>
>> Sure, outdated docs is something that happens.  Patches welcome.
>>
> 
> Something like this ?

 > diff --git a/src/include/catalog/README b/src/include/catalog/README
 > new file mode 100644
 > index 00000000000..5bd81c6d86c
 > --- /dev/null
 > +++ b/src/include/catalog/README
 > @@ -0,0 +1,11 @@
 > +# Catalog
 > +
 > +For more details see https://www.postgresql.org/docs/current/bki.html

I can see that having a README in src/include/catalog/ would be useful. 
That directory contains some "unusual" files, and some hints about them 
would be good.  Before commit 372728b0d49, we used to have a README in 
src/backend/catalog/README, but then this was moved to the SGML 
documentation.  Maybe you can read up there why this was chosen.  But I 
think src/include/catalog/ would be a better location in any case.

Maybe for now just a link like you show would be ok.  (But it should 
probably be s/current/devel/.)

 > +
 > +Below are some checklists for common scenarios.
 > +
 > +## Adding a New Built-in SQL Command
 > +
 > +1. Implement the function in C and place it in the appropriate 
directory under `src` (typically in `src/utils/adt`)
 > +2. Each function should have a unique integer OID. Run the script 
`src/include/catalog/unused_oids` to find available ranges.
 > +3. Add the entry to `pg_proc.dat` following the surrounding conventions.

Presumably, if you're developing this kind of thing, you are already 
reading some other part of the documentation, maybe xfunc.sgml?  Do we 
need to add more information there, or some links?

On Tue, Jul 08, 2025 at 05:40:39PM +0300, Florents Tselai wrote:
> On Tue, Jul 1, 2025 at 12:25 PM Peter Eisentraut <peter@eisentraut.org> wrote:
>>> +
>>> +Below are some checklists for common scenarios.
>>> +
>>> +## Adding a New Built-in SQL Command
>>> +
>>> +1. Implement the function in C and place it in the appropriate
>> directory under `src` (typically in `src/utils/adt`)
>>> +2. Each function should have a unique integer OID. Run the script
>> `src/include/catalog/unused_oids` to find available ranges.
>>> +3. Add the entry to `pg_proc.dat` following the surrounding
>> conventions.
>>
>> Presumably, if you're developing this kind of thing, you are already
>> reading some other part of the documentation, maybe xfunc.sgml?  Do we
>> need to add more information there, or some links?
>
> I agree. Added a link reference to that xfunc-c

I understand Peter's comment that we need something more general than
what your v2-0001 is proposing, the point being that modifying
pg_proc.dat may apply to some concepts, but it's far from being all of
them.  If you need to add a new in-core type, or something else to a
different catalog, then you need to be aware of a completely different
.dat file.  This set of instructions read as being a bit misleading,
IMO.
--
Michael

On 09.07.25 01:28, Michael Paquier wrote:
> On Tue, Jul 08, 2025 at 05:40:39PM +0300, Florents Tselai wrote:
>> On Tue, Jul 1, 2025 at 12:25 PM Peter Eisentraut <peter@eisentraut.org> wrote:
>>>> +
>>>> +Below are some checklists for common scenarios.
>>>> +
>>>> +## Adding a New Built-in SQL Command
>>>> +
>>>> +1. Implement the function in C and place it in the appropriate
>>> directory under `src` (typically in `src/utils/adt`)
>>>> +2. Each function should have a unique integer OID. Run the script
>>> `src/include/catalog/unused_oids` to find available ranges.
>>>> +3. Add the entry to `pg_proc.dat` following the surrounding
>>> conventions.
>>>
>>> Presumably, if you're developing this kind of thing, you are already
>>> reading some other part of the documentation, maybe xfunc.sgml?  Do we
>>> need to add more information there, or some links?
>>
>> I agree. Added a link reference to that xfunc-c
> 
> I understand Peter's comment that we need something more general than
> what your v2-0001 is proposing, the point being that modifying
> pg_proc.dat may apply to some concepts, but it's far from being all of
> them.  If you need to add a new in-core type, or something else to a
> different catalog, then you need to be aware of a completely different
> .dat file.  This set of instructions read as being a bit misleading,
> IMO.

I have committed the part that adds a link to the bki documentation.

I think the other parts, like how to add a new built-in function, didn't 
have consensus.  Maybe a wiki page or a blog post could be good forums 
for that.