Re: [DOC] Introducing Quick Start Guide to PL/pgSQL and PL/Python Documentation

[Robert Haas]

On Fri, Dec 22, 2023 at 12:04 PM Pavel Stehule  wrote:
> I have not a strong opinion about it. My personal experience is so 99% PL 
> code is PLpgSQL, so it can be there, and other PL can be referenced there. I 
> am not sure if there is some common part for all PL.

After reading over this thread, it seems clear to me that there is no
consensus to proceed with this patch in its current form, and the
discussion seems to have stalled. Accordingly, I've marked this
"Returned with Feedback" in the CommitFest.

Ishaan, if you plan to rework this into a form which might be
acceptable given the review comments made up until now, please feel
free to change this back to "Waiting on Author", and/or move it to a
future CommitFest.

-- 
Robert Haas
EDB: http://www.enterprisedb.com

Re: [DOC] Introducing Quick Start Guide to PL/pgSQL and PL/Python Documentation

[Pavel Stehule]

pá 22. 12. 2023 v 15:50 odesílatel Japin Li  napsal:

>
> On Thu, 21 Dec 2023 at 21:03, Pavel Stehule 
> wrote:
> > Hi
> >
> > čt 21. 12. 2023 v 13:37 odesílatel Ishaan Adarsh 
> > napsal:
> >
> >> The recent documentation patches are part of my GSoC 2023 project
> >> <
> https://wiki.postgresql.org/wiki/GSoC_2023#Postgres_extension_tutorial_.2F_quick_start
> >
> >> to develop a comprehensive PostgreSQL extension development tutorial, it
> >> assumes only a basic knowledge of Postgres and the target programming
> >> language.
> >>
> >> The entire project is available on GitHub: Postgres-extension-tutorial
> >> <
> https://github.com/IshaanAdarsh/Postgres-extension-tutorial/blob/main/SGML/intro_and_toc.md
> >.
> >> It covers many topics, including prerequisites, writing extensions,
> >> creating Makefiles, using procedural languages, incorporating external
> >> languages, writing regression tests, and managing extension releases.
> *The patch submitted
> >> for procedural languages, specifically PL/pgSQL and PL/Python, is part
> of
> >> the procedural language section within the broader tutorial. *
> >>
> >> Based on the feedback I think there is a real need
> >>  for this as this
> >> is a very important and growing part of the Postgres ecosystem.
> Currently,
> >> all the extension material is scattered and very limited. There are
> >> various third-party blog posts focusing on different areas, and
> sometimes
> >> contradictory. The main motivation behind making this is to make the
> barrier
> >> for entry less prohibitive for new contributors.
> >>
> >> I would greatly appreciate your input on how to add it to the existing
> >> documentation (this is where I have major doubts) and any suggestions on
> >> how to proceed. If there are areas where the existing documentation is
> >> already sufficient or if there are ways to improve the overall
> structure, I
> >> am open to making adjustments.
> >>
> >
> > https://www.postgresql.org/docs/current/plpgsql-development-tips.html
> and
> > new section - deployment or packaging to extensions
> >
> > I agree so https://www.postgresql.org/docs/current/plpgsql-overview.html
> is
> > under dimensioned, but packaging should not be there
> >
>
> It seems redundant if we add this for each PL, maybe a separate section to
> describe how to package PL into extensions is better.
>

I have not a strong opinion about it. My personal experience is so 99% PL
code is PLpgSQL, so it can be there, and other PL can be referenced there.
I am not sure if there is some common part for all PL.

Regards

Pavel

>
> --
> Regrads,
> Japin Li
> ChengDu WenWu Information Technology Co., Ltd.
>

Re: [DOC] Introducing Quick Start Guide to PL/pgSQL and PL/Python Documentation

[Japin Li]

On Thu, 21 Dec 2023 at 21:03, Pavel Stehule  wrote:
> Hi
>
> čt 21. 12. 2023 v 13:37 odesílatel Ishaan Adarsh 
> napsal:
>
>> The recent documentation patches are part of my GSoC 2023 project
>> 
>> to develop a comprehensive PostgreSQL extension development tutorial, it
>> assumes only a basic knowledge of Postgres and the target programming
>> language.
>>
>> The entire project is available on GitHub: Postgres-extension-tutorial
>> .
>> It covers many topics, including prerequisites, writing extensions,
>> creating Makefiles, using procedural languages, incorporating external
>> languages, writing regression tests, and managing extension releases. *The 
>> patch submitted
>> for procedural languages, specifically PL/pgSQL and PL/Python, is part of
>> the procedural language section within the broader tutorial. *
>>
>> Based on the feedback I think there is a real need
>>  for this as this
>> is a very important and growing part of the Postgres ecosystem. Currently,
>> all the extension material is scattered and very limited. There are
>> various third-party blog posts focusing on different areas, and sometimes
>> contradictory. The main motivation behind making this is to make the barrier
>> for entry less prohibitive for new contributors.
>>
>> I would greatly appreciate your input on how to add it to the existing
>> documentation (this is where I have major doubts) and any suggestions on
>> how to proceed. If there are areas where the existing documentation is
>> already sufficient or if there are ways to improve the overall structure, I
>> am open to making adjustments.
>>
>
> https://www.postgresql.org/docs/current/plpgsql-development-tips.html and
> new section - deployment or packaging to extensions
>
> I agree so https://www.postgresql.org/docs/current/plpgsql-overview.html is
> under dimensioned, but packaging should not be there
>

It seems redundant if we add this for each PL, maybe a separate section to
describe how to package PL into extensions is better.

--
Regrads,
Japin Li
ChengDu WenWu Information Technology Co., Ltd.

Re: [DOC] Introducing Quick Start Guide to PL/pgSQL and PL/Python Documentation

[Pavel Stehule]

Hi

čt 21. 12. 2023 v 13:37 odesílatel Ishaan Adarsh 
napsal:

> The recent documentation patches are part of my GSoC 2023 project
> 
> to develop a comprehensive PostgreSQL extension development tutorial, it
> assumes only a basic knowledge of Postgres and the target programming
> language.
>
> The entire project is available on GitHub: Postgres-extension-tutorial
> .
> It covers many topics, including prerequisites, writing extensions,
> creating Makefiles, using procedural languages, incorporating external
> languages, writing regression tests, and managing extension releases. *The 
> patch submitted
> for procedural languages, specifically PL/pgSQL and PL/Python, is part of
> the procedural language section within the broader tutorial. *
>
> Based on the feedback I think there is a real need
>  for this as this
> is a very important and growing part of the Postgres ecosystem. Currently,
> all the extension material is scattered and very limited. There are
> various third-party blog posts focusing on different areas, and sometimes
> contradictory. The main motivation behind making this is to make the barrier
> for entry less prohibitive for new contributors.
>
> I would greatly appreciate your input on how to add it to the existing
> documentation (this is where I have major doubts) and any suggestions on
> how to proceed. If there are areas where the existing documentation is
> already sufficient or if there are ways to improve the overall structure, I
> am open to making adjustments.
>

https://www.postgresql.org/docs/current/plpgsql-development-tips.html and
new section - deployment or packaging to extensions

I agree so https://www.postgresql.org/docs/current/plpgsql-overview.html is
under dimensioned, but packaging should not be there

Regards

Pavel


>
> Best,
> Ishaan Adarsh
>
>
> On Thu, Dec 21, 2023 at 4:17 PM Pavel Stehule 
> wrote:
>
>> Hi
>>
>> čt 21. 12. 2023 v 11:18 odesílatel Peter Eisentraut 
>> napsal:
>>
>>> On 19.12.23 17:26, Ishaan Adarsh wrote:
>>> > Subject: Clarification on the Purpose of the Patch
>>> >
>>> > Hi Peter,
>>> >
>>> > The intention was to address the challenge faced by newcomers in
>>> > understanding how to write an extension for PostgreSQL. The existing
>>> > documentation, while comprehensive, lacks a consolidated and
>>> > easy-to-follow tutorial that serves as a quick start guide. The goal
>>> was
>>> > to create a beginner-friendly resource that assumes only knowledge of
>>> > Postgres and the target language, making it accessible for new
>>> > contributors because the barrier for entry is prohibitive for new
>>> > contributors. There are various third-party blog posts focusing on
>>> > different areas, and sometimes contradictory.
>>>
>>> Have you seen this:
>>>
>>> https://www.postgresql.org/docs/devel/extend-extensions.html#EXTEND-EXTENSIONS-EXAMPLE
>>>
>>> Maybe that could be extended/modified/simplified?
>>>
>>> > Specifically:
>>> > 1. The new section titled "Quick Start Guide" aims to provide
>>> > step-by-step instructions for users to get started with writing
>>> > extensions in PL/pgSQL and PL/Python.
>>>
>>> What's confusing here is writing an extension in a PL language is not a
>>> normal use case I'd say.  The normal use case involves some C code.
>>>
>>
>>  Extensions were designed for C, but they are working with PL well too.
>> Some of my customers use extensions for PLpgSQL and they are almost happy.
>> 1) there is nothing else, 2) it is really works
>>
>> I agree with Peter - this topic is not what I imagine under "Quick start
>> guide"
>>
>> Regards
>>
>> Pavel
>>
>

Re: [DOC] Introducing Quick Start Guide to PL/pgSQL and PL/Python Documentation

[Ishaan Adarsh]

The recent documentation patches are part of my GSoC 2023 project

to develop a comprehensive PostgreSQL extension development tutorial, it
assumes only a basic knowledge of Postgres and the target programming
language.

The entire project is available on GitHub: Postgres-extension-tutorial
.
It covers many topics, including prerequisites, writing extensions,
creating Makefiles, using procedural languages, incorporating external
languages, writing regression tests, and managing extension releases.
*The patch submitted
for procedural languages, specifically PL/pgSQL and PL/Python, is part of
the procedural language section within the broader tutorial. *

Based on the feedback I think there is a real need
 for this as this is
a very important and growing part of the Postgres ecosystem. Currently, all
the extension material is scattered and very limited. There are various
third-party blog posts focusing on different areas, and sometimes
contradictory. The main motivation behind making this is to make the barrier
for entry less prohibitive for new contributors.

I would greatly appreciate your input on how to add it to the existing
documentation (this is where I have major doubts) and any suggestions on
how to proceed. If there are areas where the existing documentation is
already sufficient or if there are ways to improve the overall structure, I
am open to making adjustments.

Best,
Ishaan Adarsh


On Thu, Dec 21, 2023 at 4:17 PM Pavel Stehule 
wrote:

> Hi
>
> čt 21. 12. 2023 v 11:18 odesílatel Peter Eisentraut 
> napsal:
>
>> On 19.12.23 17:26, Ishaan Adarsh wrote:
>> > Subject: Clarification on the Purpose of the Patch
>> >
>> > Hi Peter,
>> >
>> > The intention was to address the challenge faced by newcomers in
>> > understanding how to write an extension for PostgreSQL. The existing
>> > documentation, while comprehensive, lacks a consolidated and
>> > easy-to-follow tutorial that serves as a quick start guide. The goal
>> was
>> > to create a beginner-friendly resource that assumes only knowledge of
>> > Postgres and the target language, making it accessible for new
>> > contributors because the barrier for entry is prohibitive for new
>> > contributors. There are various third-party blog posts focusing on
>> > different areas, and sometimes contradictory.
>>
>> Have you seen this:
>>
>> https://www.postgresql.org/docs/devel/extend-extensions.html#EXTEND-EXTENSIONS-EXAMPLE
>>
>> Maybe that could be extended/modified/simplified?
>>
>> > Specifically:
>> > 1. The new section titled "Quick Start Guide" aims to provide
>> > step-by-step instructions for users to get started with writing
>> > extensions in PL/pgSQL and PL/Python.
>>
>> What's confusing here is writing an extension in a PL language is not a
>> normal use case I'd say.  The normal use case involves some C code.
>>
>
>  Extensions were designed for C, but they are working with PL well too.
> Some of my customers use extensions for PLpgSQL and they are almost happy.
> 1) there is nothing else, 2) it is really works
>
> I agree with Peter - this topic is not what I imagine under "Quick start
> guide"
>
> Regards
>
> Pavel
>

Re: [DOC] Introducing Quick Start Guide to PL/pgSQL and PL/Python Documentation

[Pavel Stehule]

Hi

čt 21. 12. 2023 v 11:18 odesílatel Peter Eisentraut 
napsal:

> On 19.12.23 17:26, Ishaan Adarsh wrote:
> > Subject: Clarification on the Purpose of the Patch
> >
> > Hi Peter,
> >
> > The intention was to address the challenge faced by newcomers in
> > understanding how to write an extension for PostgreSQL. The existing
> > documentation, while comprehensive, lacks a consolidated and
> > easy-to-follow tutorial that serves as a quick start guide. The goal was
> > to create a beginner-friendly resource that assumes only knowledge of
> > Postgres and the target language, making it accessible for new
> > contributors because the barrier for entry is prohibitive for new
> > contributors. There are various third-party blog posts focusing on
> > different areas, and sometimes contradictory.
>
> Have you seen this:
>
> https://www.postgresql.org/docs/devel/extend-extensions.html#EXTEND-EXTENSIONS-EXAMPLE
>
> Maybe that could be extended/modified/simplified?
>
> > Specifically:
> > 1. The new section titled "Quick Start Guide" aims to provide
> > step-by-step instructions for users to get started with writing
> > extensions in PL/pgSQL and PL/Python.
>
> What's confusing here is writing an extension in a PL language is not a
> normal use case I'd say.  The normal use case involves some C code.
>

 Extensions were designed for C, but they are working with PL well too.
Some of my customers use extensions for PLpgSQL and they are almost happy.
1) there is nothing else, 2) it is really works

I agree with Peter - this topic is not what I imagine under "Quick start
guide"

Regards

Pavel

Re: [DOC] Introducing Quick Start Guide to PL/pgSQL and PL/Python Documentation

[Peter Eisentraut]

On 19.12.23 17:26, Ishaan Adarsh wrote:

Subject: Clarification on the Purpose of the Patch

Hi Peter,

The intention was to address the challenge faced by newcomers in 
understanding how to write an extension for PostgreSQL. The existing 
documentation, while comprehensive, lacks a consolidated and 
easy-to-follow tutorial that serves as a quick start guide. The goal was 
to create a beginner-friendly resource that assumes only knowledge of 
Postgres and the target language, making it accessible for new 
contributors because the barrier for entry is prohibitive for new 
contributors. There are various third-party blog posts focusing on 
different areas, and sometimes contradictory.


Have you seen this: 
https://www.postgresql.org/docs/devel/extend-extensions.html#EXTEND-EXTENSIONS-EXAMPLE


Maybe that could be extended/modified/simplified?


Specifically:
1. The new section titled "Quick Start Guide" aims to provide 
step-by-step instructions for users to get started with writing 
extensions in PL/pgSQL and PL/Python.


What's confusing here is writing an extension in a PL language is not a 
normal use case I'd say.  The normal use case involves some C code.

Re: [DOC] Introducing Quick Start Guide to PL/pgSQL and PL/Python Documentation

[Ishaan Adarsh]

Subject: Clarification on the Purpose of the Patch

Hi Peter,

The intention was to address the challenge faced by newcomers in
understanding how to write an extension for PostgreSQL. The existing
documentation, while comprehensive, lacks a consolidated and easy-to-follow
tutorial that serves as a quick start guide. The goal was to create a
beginner-friendly resource that assumes only knowledge of Postgres and the
target language, making it accessible for new contributors because the
barrier for entry is prohibitive for new contributors. There are various
third-party blog posts focusing on different areas, and sometimes
contradictory.

Specifically:
1. The new section titled "Quick Start Guide" aims to provide step-by-step
instructions for users to get started with writing extensions in PL/pgSQL
and PL/Python.
2. Explanations, code snippets, and examples were included to illustrate
key concepts, making it easier for users to follow along.

I understand your point about the basics of setting up an extension file
structure being repeated. The intention was to provide a self-contained
guide within each language's documentation, ensuring that users who
directly access a specific language's documentation get a complete guide
without having to navigate between sections.

If there are areas where the existing documentation is already sufficient
or if there are ways to improve the approach, I am open to suggestions. The
primary aim is to enhance the accessibility of extension development
information for newcomers.

--
Best regards,
Ishaan Adarsh


On Tue, Dec 19, 2023 at 9:18 PM Peter Eisentraut 
wrote:

> On 16.12.23 11:49, Ishaan Adarsh wrote:
> > 1. Added a new section titled "Quick Start Guide" to both PL/pgSQL and
> > PL/Python documentation.
> > 2. Included step-by-step instructions for users to get started with
> > these procedural languages.
> > 3. Provided explanations, code snippets, and examples to illustrate key
> > concepts.
>
> The way I read it, that's not really what your patch does.  Your patch
> explains how to write an extension in PL/pgSQL and PL/Python,
> respectively.  Which is okay, I guess, but a bit unusual.  But I
> wouldn't call that an unqualified "quick start" in the respective
> languages.  Also, it seems to repeat the very basics of setting up an
> extension file structure etc. repeatedly in each chapter.
>
> The existing documentation has "explanations, code snippets, and
> examples".  Are they not good?  Do you have more?  Better ones?  Why are
> yours separate from the existing ones?
>
> I think it would be useful to take a step back here and define the
> purpose of a bit clearer.
>

Re: [DOC] Introducing Quick Start Guide to PL/pgSQL and PL/Python Documentation

[Peter Eisentraut]

On 16.12.23 11:49, Ishaan Adarsh wrote:
1. Added a new section titled "Quick Start Guide" to both PL/pgSQL and 
PL/Python documentation.
2. Included step-by-step instructions for users to get started with 
these procedural languages.
3. Provided explanations, code snippets, and examples to illustrate key 
concepts.


The way I read it, that's not really what your patch does.  Your patch 
explains how to write an extension in PL/pgSQL and PL/Python, 
respectively.  Which is okay, I guess, but a bit unusual.  But I 
wouldn't call that an unqualified "quick start" in the respective 
languages.  Also, it seems to repeat the very basics of setting up an 
extension file structure etc. repeatedly in each chapter.


The existing documentation has "explanations, code snippets, and 
examples".  Are they not good?  Do you have more?  Better ones?  Why are 
yours separate from the existing ones?


I think it would be useful to take a step back here and define the 
purpose of a bit clearer.

Re: [DOC] Introducing Quick Start Guide to PL/pgSQL and PL/Python Documentation

[Japin Li]

On Tue, 19 Dec 2023 at 17:57, Ishaan Adarsh  wrote:
> I've addressed the points you raised:
>
> 1. *Missing `` Tag:*
> I reviewed the "Create the Makefile" section, and it seems that 
> tags are appropriately used for filenames. If there's a specific instance
> where you observed a missing tag, please provide more details, and I'll
> ensure it's addressed.
>

Thanks.

> 2. *Use `CREATE EXTENSION` in "extension--version.sql":*
>  Considering that there's already a CREATE EXTENSION step in the quick
> start guide, I can include a note in the general documentation to explain
> the rationale without repeating it in the individual script. What do you
> think?

Agreed.

--
Regrads,
Japin Li
ChengDu WenWu Information Technology Co., Ltd.

Re: [DOC] Introducing Quick Start Guide to PL/pgSQL and PL/Python Documentation

[Ishaan Adarsh]

I've addressed the points you raised:

1. *Missing `` Tag:*
I reviewed the "Create the Makefile" section, and it seems that 
tags are appropriately used for filenames. If there's a specific instance
where you observed a missing tag, please provide more details, and I'll
ensure it's addressed.

2. *Use `CREATE EXTENSION` in "extension--version.sql":*
 Considering that there's already a CREATE EXTENSION step in the quick
start guide, I can include a note in the general documentation to explain
the rationale without repeating it in the individual script. What do you
think?

--
Best regards,
Ishaan Adarsh

On Tue, Dec 19, 2023 at 12:28 PM Japin Li  wrote:

>
> 1.
> It seems you miss  tag in plpgsql "Create the Makefile":
>
> +  
> +Create the Makefile
> +
> +
> +  Create a Makefile in the pg_plpgsql_ext
> directory with the following content:
> +
>
> 2.
> We expected use CREATE EXTENSION to load the extension, should we add the
> following in extension--version.sql?
>
> -- complain if script is sourced in psql, rather than via CREATE EXTENSION
> \echo Use "CREATE EXTENSION pair" to load this file. \quit
>
> --
> Regrads,
> Japin Li
> ChengDu WenWu Information Technology Co., Ltd.
>

Re: [DOC] Introducing Quick Start Guide to PL/pgSQL and PL/Python Documentation

[Japin Li]

On Sat, 16 Dec 2023 at 18:49, Ishaan Adarsh  wrote:
> Hi
>
> I have made some documentation enhancements for PL/pgSQL and PL/Python
> sections. The changes include the addition of a Quick Start Guide to
> facilitate a smoother onboarding experience for users.
>
> Patch File Name:
> 0001-plpyhton-plpgsql-docu-changes.patch
>
> Patch Description:
> This patch introduces a Quick Start Guide to the documentation for PL/pgSQL
> and PL/Python. The Quick Start Guide provides users with a step-by-step
> walkthrough of setting up and using these procedural languages. The goal is
> to improve user accessibility and streamline the learning process.
>
> Changes Made:
> 1. Added a new section titled "Quick Start Guide" to both PL/pgSQL and
> PL/Python documentation.
> 2. Included step-by-step instructions for users to get started with these
> procedural languages.
> 3. Provided explanations, code snippets, and examples to illustrate key
> concepts.
>
> Discussion Points:
> I am seeking your feedback on the following aspects:
> - Clarity and completeness of the Quick Start Guide
> - Any additional information or examples that could enhance the guide
> - Suggestions for improving the overall documentation structure
>
> Your insights and suggestions are highly valuable, and I appreciate your
> time in reviewing this documentation enhancement.

1.
It seems you miss  tag in plpgsql "Create the Makefile":

+  
+Create the Makefile
+
+
+  Create a Makefile in the pg_plpgsql_ext directory 
with the following content:
+

2.
We expected use CREATE EXTENSION to load the extension, should we add the
following in extension--version.sql?

-- complain if script is sourced in psql, rather than via CREATE EXTENSION
\echo Use "CREATE EXTENSION pair" to load this file. \quit

--
Regrads,
Japin Li
ChengDu WenWu Information Technology Co., Ltd.

Re: [DOC] Introducing Quick Start Guide to PL/pgSQL and PL/Python Documentation

[Euler Taveira]

On Sat, Dec 16, 2023, at 7:49 AM, Ishaan Adarsh wrote:
> I have made some documentation enhancements for PL/pgSQL and PL/Python 
> sections. The changes include the addition of a Quick Start Guide to 
> facilitate a smoother onboarding experience for users.

Great! Add your patch to the next CF [1] so we don't miss it.

[1] https://commitfest.postgresql.org/46/


--
Euler Taveira
EDB   https://www.enterprisedb.com/

[DOC] Introducing Quick Start Guide to PL/pgSQL and PL/Python Documentation

[Ishaan Adarsh]

Hi

I have made some documentation enhancements for PL/pgSQL and PL/Python
sections. The changes include the addition of a Quick Start Guide to
facilitate a smoother onboarding experience for users.

Patch File Name:
0001-plpyhton-plpgsql-docu-changes.patch

Patch Description:
This patch introduces a Quick Start Guide to the documentation for PL/pgSQL
and PL/Python. The Quick Start Guide provides users with a step-by-step
walkthrough of setting up and using these procedural languages. The goal is
to improve user accessibility and streamline the learning process.

Changes Made:
1. Added a new section titled "Quick Start Guide" to both PL/pgSQL and
PL/Python documentation.
2. Included step-by-step instructions for users to get started with these
procedural languages.
3. Provided explanations, code snippets, and examples to illustrate key
concepts.

Discussion Points:
I am seeking your feedback on the following aspects:
- Clarity and completeness of the Quick Start Guide
- Any additional information or examples that could enhance the guide
- Suggestions for improving the overall documentation structure

Your insights and suggestions are highly valuable, and I appreciate your
time in reviewing this documentation enhancement.

--
Best regards,
Ishaan Adarsh


0001-plpyhton-plpgsql-docu-changes.patch
Description: Binary data