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

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
<https://twitter.com/jer_s/status/1699071450915938609> 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 <pavel(dot)stehule(at)gmail(dot)com>
wrote:

> Hi
>
> čt 21. 12. 2023 v 11:18 odesílatel Peter Eisentraut <peter(at)eisentraut(dot)org>
> 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
>