On Tue, Jul 1, 2025 at 12:25 PM Peter Eisentraut <pe...@eisentraut.org> wrote:
> On 24.05.25 12:34, Florents Tselai wrote: > > > > > >> On 24 May 2025, at 12:24 PM, Álvaro Herrera <alvhe...@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. > In practice people go to the git history to see the files touched by similar commits, and devise a to-do-list for their case. so I think it helps them a lot to see some high-level READMEs waiting for them there. In this particular case, unused_oids isn't included in any commits so you can't be aware of its existence even > Maybe for now just a link like you show would be ok. (But it should > probably be s/current/devel/.) > Done > > > + > > +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 Some basic stuff that was missing in xfunc, I've already added in 86e4efc . For now I think it's good enough.
v2-0001-Add-catalog-README.patch
Description: Binary data
