Horton

Thread

Commits

  1. Align some terms in arch-dev.sgml to glossary

  2. doc: Copy-edit the "Overview of PostgreSQL Internals" chapter

  3. Merge postmaster and postgres command into just postgres. postmaster

  1. Additional Chapter for Tutorial

    Jürgen Purtz <juergen@purtz.de> — 2020-04-17T17:56:08Z

    Our documentation explains many details about commands, tools, 
parameters in detail and with high accuracy. Nevertheless my impression 
is that we neglect the 'big picture': why certain processes exist and 
what their relation to each other is, summary of strategies, 
visualization of key situations, ... . People with mature knowledge 
don't miss this information because they know all about it. But for 
beginners such explanations would be a great help. In the time before 
GSoD 2019 we had similar discussions.

I plan to extend over time the part 'Tutorial' by an additional chapter 
with an overview about key design decisions and basic features. The 
typical audience should consist of persons with limited pre-knowledge in 
database systems and some interest in PostgreSQL. In the attachment you 
find a patch for the first sub-chapter. Subsequent sub-chapters should 
be: MVCC, transactions, VACUUM, backup, replication, ... - mostly with 
the focus on the PostgreSQL implementation and not on generic topics 
like b-trees.

There is a predecessor of this patch: 
https://www.postgresql.org/message-id/974e09b8-edf5-f38f-2fb5-a5875782ffc9%40purtz.de 
. In the meanwhile its glossary-part is separated and commited. The new 
patch contains two elements: textual descriptions and 4 figures. My 
opinion concerning figures is set out in detail in the previous patch.

Kind regards, Jürgen Purtz

  2. Re: Additional Chapter for Tutorial

    Corey Huinker <corey.huinker@gmail.com> — 2020-04-17T18:18:17Z

    >
> I plan to extend over time the part 'Tutorial' by an additional chapter
> with an overview about key design decisions and basic features. The
> typical audience should consist of persons with limited pre-knowledge in
> database systems and some interest in PostgreSQL. In the attachment you
> find a patch for the first sub-chapter. Subsequent sub-chapters should
> be: MVCC, transactions, VACUUM, backup, replication, ... - mostly with
> the focus on the PostgreSQL implementation and not on generic topics
> like b-trees.
>

+1

  3. Re: Additional Chapter for Tutorial

    Erik Rijkers <er@xs4all.nl> — 2020-04-17T18:40:32Z

    On 2020-04-17 19:56, Jürgen Purtz wrote:
> Our documentation explains many details about commands, tools,
> parameters in detail and with high accuracy. Nevertheless my
> impression is that we neglect the 'big picture': why certain processes

> [0001-architecture.patch]

Very good stuff, and useful. I think.

I mean that but nevertheless here is a lot of comment :)

(I didn't fully compile as docs, just read the 'text' from the patch 
file)


Collabortion
Collaboration

drop 'resulting'


He acts in close cooperation with the
It acts in close cooperation with the

He loads the configuration files, allocates the
It loads the configuration files, allocates the

process</firstterm>. He checks the authorization, starts a
process</firstterm>. it checks the authorization, starts a

and instructs the client application to connect to him. All further
and instructs the client application to connect to it. All further

by him.
by it.

In an first attempt
In a first attempt

much huger than memory, it's likely that
much larger than memory, it's likely that

RAM is performed in units of complete pages while retaining
RAM is performed in units of complete pages, retaining

Sooner or later it is necessary to overwrite old RAM
Sooner or later it becomes necessary to overwrite old RAM

transfered
transferred
   (multiple times)

who runs
which runs

He writes
it writes

This is the primarily duty of the
This is primarily the duty of the
   or possibly:
This is the primary duty of the

he starts periodically
it starts periodically

speeds up a possibly occurring recovery.
can speed up recovery.

writen
written

collects counter about accesses
collects counters about accesses

and others. He stores the obtained information in system
and more. It stores the obtained information in system

sudirectories consists
subdirectories consist  <-- plural, no -s

there are information
there is information

and contains the ID of the
and contains the ID (pid) of the

( IMHO, it is conventional (and therefore easier to read) to have 'e.g.' 
followed by a comma, and not by a semi-colon, although obviously that's 
not really wrong either. )


Thanks,

Erik Rijkers

  4. Re: Additional Chapter for Tutorial

    Jürgen Purtz <juergen@purtz.de> — 2020-04-20T08:30:20Z

    On 17.04.20 20:40, Erik Rijkers wrote:
> Very good stuff, and useful. I think.
>
> I mean that but nevertheless here is a lot of comment :)
>
> (I didn't fully compile as docs, just read the 'text' from the patch 
> file)

Thanks. Added nearly all of the suggestions.


--

Jürgen Purtz

  5. Re: Additional Chapter for Tutorial

    Jürgen Purtz <juergen@purtz.de> — 2020-04-29T14:13:46Z

    On 20.04.20 10:30, Jürgen Purtz wrote:
> On 17.04.20 20:40, Erik Rijkers wrote:
>> Very good stuff, and useful. I think.
>>
>> I mean that but nevertheless here is a lot of comment :)
>>
>> (I didn't fully compile as docs, just read the 'text' from the patch 
>> file)
>
> Thanks. Added nearly all of the suggestions.
>
>
What is new? Added two sub-chapters 'mvcc' and 'vacuum' plus graphics. 
Made some modifications in previous sub-chapters and in existing titles. 
Added some glossary entries.

--

Jürgen Purtz

  6. Re: Additional Chapter for Tutorial - (review first half of 0003)

    Erik Rijkers <er@xs4all.nl> — 2020-04-29T15:35:22Z

    On 2020-04-29 16:13, Jürgen Purtz wrote:
> On 20.04.20 10:30, Jürgen Purtz wrote:
>> On 17.04.20 20:40, Erik Rijkers wrote:
>>> Very good stuff, and useful. I think.
>>> 
>>> I mean that but nevertheless here is a lot of comment :)
>>> 
>>> (I didn't fully compile as docs, just read the 'text' from the patch 
>>> file)
>> 
>> Thanks. Added nearly all of the suggestions.
>> 
>> 
> What is new? Added two sub-chapters 'mvcc' and 'vacuum' plus graphics.
> Made some modifications in previous sub-chapters and in existing
> titles. Added some glossary entries.

> [0003-architecture.patch]

Hi Jürgen,


Here are again some suggested changes, up to line 600 (of the patch - 
that is around start of the new NVCC paragraph)

I may have repeated some thing you have already rejected (it was too 
much work to go back and check).  I am not a native speaker of english.

One general remark: in my humble opinion, you write too many capitalized 
words.  It's not really a problem but overall it's becomes bit too much. 
  But I have not marked these. perhaps some future iteration.

I'll probably read through the latter part of the patch later (probably 
tomorrow).

Thanks,

Erik Rijkers



they merely send requests to the server side and receives
they merely send requests to the server side and receive

is a group of tightly coupled other server side processes plus a
is a group of tightly coupled other server-side processes plus a

Client requests (SELECT, UPDATE, ...) usually leads to the
Client requests (SELECT, UPDATE, ...) usually lead to the

Because files are much larger than memory, it's likely that
Because files are often larger than memory, it's likely that

RAM is performed in units of complete pages, retaining their size and 
layout.
RAM is performed in units of complete pages.

Reading file pages is notedly slower than reading
Reading file pages is slower than reading

of the <firstterm>Backend processes</firstterm> has done the job those 
pages are available for all other
of the <firstterm>Backend processes</firstterm> has read pages into 
memory those pages are available for all other

they must be transferred back to disk. This is a two-step process.
they must be written back to disk. This is a two-step process.

Because of the sequential nature of this writing, it is much
Because of this writing is sequential, it is much

in an independent process. Nevertheless all
in an independent process. Nevertheless, all

huge I/O activities can block other processes significantly,
I/O activities can block other processes,

it starts periodically and acts only for a short period.
it starts periodically and is active only for a short period.

duty. As its name suggests, he has to create
duty. As its name suggests, it has to create

In consequence, after a <firstterm>Checkpoint</firstterm>
After a <firstterm>Checkpoint</firstterm>,

In correlation with data changes,
As a result of data changes,

text lines about serious and non-serious events which can happen
text lines about serious and less serious events which can happen

database contains many <glossterm 
linkend="glossary-schema">schema</glossterm>,
database contains many <glossterm 
linkend="glossary-schema">schemas</glossterm>,

belongs to a certain <firstterm>schema</firstterm>, they cannot
belongs to a single <firstterm>schema</firstterm>, they cannot

A <firstterm>Cluster</firstterm> is the outer frame for a
A <firstterm>Cluster</firstterm> is the outer container for a

<literal>postgres</literal> as a copy of
<literal>postgres</literal> is generated as a copy of

role of <literal>template0</literal> as the origin
role of <literal>template0</literal> as the pristine origin

are different objects and absolutely independent from each
are different objects and independent from each

complete <firstterm>cluster</firstterm>, independent from
<firstterm>cluster</firstterm>, independent from

anywhere in the file system. In many cases, the environment
somewhere in the file system. In many cases, the environment

some files, all of which are necessary to store long lasting
some files, all of which are necessary to store long-lasting

<firstterm>tablespaces</firstterm> itself.
<firstterm>tablespaces</firstterm> themselves.

<firstterm>Postgres</firstterm> (respectively 
<firstterm>Postmaster</firstterm>) process.
<firstterm>Postgres</firstterm> process (also known as 
<firstterm>Postmaster</firstterm>).

<title>MVCC</title>
<title>MVCC - Multiversion Concurrency Control</title>

The dabase must take a sensible decision to prevent the application
The database must take a sensible decision to prevent the application

# this sentence I just don't understand - can you please elucidate?
The database must take a sensible decision to prevent the application
from promising delivery of the single article to both clients.

  7. Re: Additional Chapter for Tutorial

    Peter Eisentraut <peter.eisentraut@2ndquadrant.com> — 2020-04-29T19:12:25Z

    On 2020-04-29 16:13, Jürgen Purtz wrote:
> On 20.04.20 10:30, Jürgen Purtz wrote:
>> On 17.04.20 20:40, Erik Rijkers wrote:
>>> Very good stuff, and useful. I think.
>>>
>>> I mean that but nevertheless here is a lot of comment :)
>>>
>>> (I didn't fully compile as docs, just read the 'text' from the patch
>>> file)
>>
>> Thanks. Added nearly all of the suggestions.
>>
>>
> What is new? Added two sub-chapters 'mvcc' and 'vacuum' plus graphics.
> Made some modifications in previous sub-chapters and in existing titles.
> Added some glossary entries.

I don't see this really as belonging into the tutorial.  The tutorial 
should be hands-on, how do you get started, how do you get some results.

Your material is more of an overview of the whole system.  What's a new 
user supposed to do with that?

-- 
Peter Eisentraut              http://www.2ndQuadrant.com/
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services

  8. Re: Additional Chapter for Tutorial

    Jürgen Purtz <juergen@purtz.de> — 2020-04-30T12:31:10Z

    On 29.04.20 21:12, Peter Eisentraut wrote:
>
> I don't see this really as belonging into the tutorial.  The tutorial 
> should be hands-on, how do you get started, how do you get some results.
>
Yes, the tutorial should be a short overview and give instructions how 
to start. IMO the first 4 sub-chapters fulfill this expectation. Indeed, 
the fifth (VACUUM) is extensive and offers many details.

During the inspection of the existing documentation I recognized that 
there are many details about VACUUM, AUTOVACUUM, all of their parameters 
as well as their behavior. But the information is spread across many 
pages: Automatic Vacuuming, Client Connection Defaults, Routine 
Vacuuming, Resource Consumption, VACUUM. Even for a person with some 
pre-knowledge it is hard to get an overview how this fits together and 
why things are solved in exactly this way. In the end we have very good 
descriptions of all details but I miss the 'big picture'. Therefore I 
summarized central aspects and tried to give an answer to the question 
'why is it done in this way?'. I do not dispute that the current version 
of the page is not adequate for beginners. But at some place we should 
have such a summary about vacuuming and freezing.

How to proceed?

- Remove the page and add a short paragraph to the MVCC page instead.

- Cut down the page to a tiny portion.

- Divide it into two parts: a) a short introduction and b) the rest 
after a statement like 'The following offers more details and parameters 
that are more interesting for an experienced user than for a beginner. 
You can easily skip it.'


> Your material is more of an overview of the whole system.  What's a 
> new user supposed to do with that?

When I dive into a new subject, I'm more interested in its architecture 
than in its details. We shall offer an overview about the major PG 
components and strategies to beginners.


--

Jürgen Purtz

  9. Re: Additional Chapter for Tutorial

    Jürgen Purtz <juergen@purtz.de> — 2020-06-02T15:01:31Z

    On 30.04.20 14:31, Jürgen Purtz wrote:
> On 29.04.20 21:12, Peter Eisentraut wrote:
>>
>> I don't see this really as belonging into the tutorial.  The tutorial 
>> should be hands-on, how do you get started, how do you get some results.
>>
> Yes, the tutorial should be a short overview and give instructions how 
> to start. IMO the first 4 sub-chapters fulfill this expectation. 
> Indeed, the fifth (VACUUM) is extensive and offers many details.
>
> During the inspection of the existing documentation I recognized that 
> there are many details about VACUUM, AUTOVACUUM, all of their 
> parameters as well as their behavior. But the information is spread 
> across many pages: Automatic Vacuuming, Client Connection Defaults, 
> Routine Vacuuming, Resource Consumption, VACUUM. Even for a person 
> with some pre-knowledge it is hard to get an overview how this fits 
> together and why things are solved in exactly this way. In the end we 
> have very good descriptions of all details but I miss the 'big 
> picture'. Therefore I summarized central aspects and tried to give an 
> answer to the question 'why is it done in this way?'. I do not dispute 
> that the current version of the page is not adequate for beginners. 
> But at some place we should have such a summary about vacuuming and 
> freezing.
>
> How to proceed?
>
> - Remove the page and add a short paragraph to the MVCC page instead.
>
> - Cut down the page to a tiny portion.
>
> - Divide it into two parts: a) a short introduction and b) the rest 
> after a statement like 'The following offers more details and 
> parameters that are more interesting for an experienced user than for 
> a beginner. You can easily skip it.'
>
>
>> Your material is more of an overview of the whole system.  What's a 
>> new user supposed to do with that?
>
> When I dive into a new subject, I'm more interested in its 
> architecture than in its details. We shall offer an overview about the 
> major PG components and strategies to beginners.
>
>
In comparison with to previous patch this one contains:

- Position and title changed to reflect its intention and importance.

- A <note> delimits VACUUM basics from details. This is done because I 
cannot find another suitable place for such a summarizing description.

- Three additional sub-chapters.

--

Jürgen Purtz

  10. Re: Additional Chapter for Tutorial

    Daniel Gustafsson <daniel@yesql.se> — 2020-07-12T20:45:28Z

    > On 2 Jun 2020, at 17:01, Jürgen Purtz <juergen@purtz.de> wrote:

> In comparison with to previous patch this one contains:
> 
> - Position and title changed to reflect its intention and importance.
> 
> - A <note> delimits VACUUM basics from details. This is done because I cannot find another suitable place for such a summarizing description.
> 
> - Three additional sub-chapters.

This patch no longer applies, due to conflicts in start.sgml, can you please
submit a rebased version?

cheers ./daniel

  11. Re: Additional Chapter for Tutorial

    Jürgen Purtz <juergen@purtz.de> — 2020-07-13T06:15:20Z

    On 12.07.20 22:45, Daniel Gustafsson wrote:
> This patch no longer applies, due to conflicts in start.sgml, can you please
> submit a rebased version?

ok. but I need some days.  juergen

  12. Re: Additional Chapter for Tutorial

    Naresh gandi <naresh5310@gmail.com> — 2020-07-13T12:20:51Z

    Which version is this application for?

I tried for v12 and v13 Beta, both failed.

Regards,
Naresh G

On Mon, Jul 13, 2020 at 11:45 AM Jürgen Purtz <juergen@purtz.de> wrote:

>
> On 12.07.20 22:45, Daniel Gustafsson wrote:
> > This patch no longer applies, due to conflicts in start.sgml, can you
> please
> > submit a rebased version?
>
> ok. but I need some days.  juergen
>
>
>
>
>

  13. Re: Additional Chapter for Tutorial

    Daniel Gustafsson <daniel@yesql.se> — 2020-07-13T12:24:43Z

    > On 13 Jul 2020, at 14:20, Naresh gandi <naresh5310@gmail.com> wrote:

(please avoid top-posting)

> Which version is this application for?
> 
> I tried for v12 and v13 Beta, both failed.

Unless being a bugfix, all patches are only considered against the main
development branch in Git. As this is new material, it would be for v14.

cheers ./daniel

  14. Re: Additional Chapter for Tutorial

    Jürgen Purtz <juergen@purtz.de> — 2020-07-17T09:32:50Z

    On 12.07.20 22:45, Daniel Gustafsson wrote:
>
> This patch no longer applies, due to conflicts in start.sgml, can you please
> submit a rebased version?
>
> cheers ./daniel
>
New version attached.

--

Jürgen Purtz

  15. Re: Additional Chapter for Tutorial

    Erik Rijkers <er@xs4all.nl> — 2020-07-18T17:17:50Z

    On 2020-07-17 11:32, Jürgen Purtz wrote:
> On 12.07.20 22:45, Daniel Gustafsson wrote:
>> 
>> This patch no longer applies, due to conflicts in start.sgml, can you 
>> please
>> submit a rebased version?
>> 
>> cheers ./daniel
>> 
> New version attached.
> 
> [0005-architecture.patch]

Hi,

I went through the architecture.sgml file once, and accumulated the 
attached edits.

There are still far too many Unneeded Capitals On Words for my taste but 
I have not changed many of those. We could use some more opinions on 
that, I suppose. (if it becomes too silent maybe include the 
pgsql-hackers again?)

Thanks,


Erik Rijkers







> --
> 
> Jürgen Purtz

  16. Re: Additional Chapter for Tutorial

    Jürgen Purtz <juergen@purtz.de> — 2020-07-21T11:51:07Z

    On 18.07.20 19:17, Erik Rijkers wrote:
>
> Hi,
>
> I went through the architecture.sgml file once, and accumulated the 
> attached edits.
>
> There are still far too many Unneeded Capitals On Words for my taste 
> but I have not changed many of those. We could use some more opinions 
> on that, I suppose. (if it becomes too silent maybe include the 
> pgsql-hackers again?)
>
> Thanks,
>
>
> Erik Rijkers

The attached patch contains:

- integration of Erik's suggestions

- coordination of terms in text, graphic and glossary

- some changes in upper-case usage

- fewer usage of <firstterm> with two exceptions: The first chapter 4.1 
emphasize all important terms to help beginners in their learning 
process; chapter 4.5. emphasize the term 'autovacuum' to straighten the 
fact that - despite its similarities - the tool autovacuum is something 
else than the SQL command vacuum.


--

Jürgen Purtz

  17. RE: Additional Chapter for Tutorial

    Pascal CROZET <pascal.crozet@qualis-consulting.com> — 2020-07-21T23:49:08Z

    Hi all,


I want to import XML file into PG database table.

I've find functions to get the XML content of a cell after imported an XML file with the pg_get_file function.

But, I want to explode the XML content to colums. How can I do this ?


PG 10 under Ubuntu 18

_________________________________

Cordialement, Pascal CROZET

DBA - Qualis Consulting

• 300 Route Nationale 6 – 69760 LIMONEST

_________________________________

  18. Re: Additional Chapter for Tutorial

    Peter Eisentraut <peter.eisentraut@2ndquadrant.com> — 2020-09-01T21:30:11Z

    Again, I don't see how this belongs into the tutorial.  It is mostly 
advanced low-level information that is irrelevant for someone starting 
up, it is not hands-on, so quite unlike the rest of the tutorial, and 
for the most part the information just duplicates what is already 
explained elsewhere.

-- 
Peter Eisentraut              http://www.2ndQuadrant.com/
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services

  19. Re: Additional Chapter for Tutorial

    Jürgen Purtz <juergen@purtz.de> — 2020-09-02T07:04:38Z

    On 01.09.20 23:30, Peter Eisentraut wrote:
> It is mostly advanced low-level information that is irrelevant for 
> someone starting up,

That applies only to the VACUUM chapter. VACUUM and AUTOVACUUM are 
controlled by a lot of parameters. Therefor the current documentation 
concerning the two mechanism spreads the description across different 
pages (20.4, 25.1, VACUUM command). Because of the structure of our 
documentation that's ok. But we should have a summary page somewhere - 
not necessarily in the tutorial.

> the most part the information just duplicates what is already 
> explained elsewhere.

That is the nature of a tutorial respectively a summary.

--

J. Purtz

  20. Re: Additional Chapter for Tutorial

    Peter Eisentraut <peter.eisentraut@2ndquadrant.com> — 2020-09-10T16:26:59Z

    On 2020-09-02 09:04, Jürgen Purtz wrote:
> On 01.09.20 23:30, Peter Eisentraut wrote:
>> It is mostly advanced low-level information that is irrelevant for
>> someone starting up,
> That applies only to the VACUUM chapter. VACUUM and AUTOVACUUM are
> controlled by a lot of parameters. Therefor the current documentation
> concerning the two mechanism spreads the description across different
> pages (20.4, 25.1, VACUUM command). Because of the structure of our
> documentation that's ok. But we should have a summary page somewhere -
> not necessarily in the tutorial.

There is probably room for improvement, but the section numbers you 
mention are not about VACUUM, AFAICT, so I can't really comment on what 
you have in mind.

-- 
Peter Eisentraut              http://www.2ndQuadrant.com/
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services

  21. Re: Additional Chapter for Tutorial

    Jürgen Purtz <juergen@purtz.de> — 2020-09-11T07:49:23Z

    On 10.09.20 18:26, Peter Eisentraut wrote:
> On 2020-09-02 09:04, Jürgen Purtz wrote:
>> On 01.09.20 23:30, Peter Eisentraut wrote:
>>> It is mostly advanced low-level information that is irrelevant for
>>> someone starting up,
>> That applies only to the VACUUM chapter. VACUUM and AUTOVACUUM are
>> controlled by a lot of parameters. Therefor the current documentation
>> concerning the two mechanism spreads the description across different
>> pages (20.4, 25.1, VACUUM command). Because of the structure of our
>> documentation that's ok. But we should have a summary page somewhere -
>> not necessarily in the tutorial.
>
> There is probably room for improvement, but the section numbers you 
> mention are not about VACUUM, AFAICT, so I can't really comment on 
> what you have in mind.
>
Because of the additional chapter for the 'tutorial' on my local 
computer, the numbers increased for me. The regular chapter numbers are 
19.4 and 24.1. Sorry for the confusion. In detail:

19.4: parameters to configure the server, especially five parameters 
'vacuum_cost_xxx'.

19.10: parameters to configure autovacuum.

19.11: parameters to configure client connections, especially five 
parameters 'vacuum_xxx' concerning their freeze-behavior.

24.1: explains the general necessity of (auto)vacuum and their strategies.

The page about the SQL command VACUUM explains the different options 
(FULL, FREEZE, ..) and their meaning.

--

Jürgen Purtz

  22. Re: Additional Chapter for Tutorial

    David G. Johnston <david.g.johnston@gmail.com> — 2020-10-21T20:33:54Z

    On Wed, Sep 2, 2020 at 12:04 AM Jürgen Purtz <juergen@purtz.de> wrote:

> On 01.09.20 23:30, Peter Eisentraut wrote:
> > It is mostly advanced low-level information that is irrelevant for
> > someone starting up,
>
> That applies only to the VACUUM chapter. VACUUM and AUTOVACUUM are
> controlled by a lot of parameters. Therefor the current documentation
> concerning the two mechanism spreads the description across different
> pages (20.4, 25.1, VACUUM command). Because of the structure of our
> documentation that's ok. But we should have a summary page somewhere -
> not necessarily in the tutorial.
>
> > the most part the information just duplicates what is already
> > explained elsewhere.
>
> That is the nature of a tutorial respectively a summary.
>
>
I've begun looking at this and have included quite a few html comments
within the patch.  However, the two main items that I have found so far are:

One, I agree with Peter that this seems misplaced in Tutorial.  I would
create a new Internals Chapter and place this material there, or maybe
consider a sub-chapter under "Overview of PostgreSQL Internals".  If this
is deemed to be of a more primary importance than the content in the
Internals section I would recommend placing it in Reference.  I feel it
does fit there and given the general importance of that section readers
will be inclined to click into it and skim over its content.

Two, I find the amount of detail being provided here to be on the too-much
side.  A bit more judicious use of links into the appropriate detail
chapters seems warranted.

I took a pretty heavy hand to the original section though aside from the
scope comment it can probably be considered a bit weighted toward style
preferences.  Though I did note/rewrite a couple of things that seemed
factually incorrect - and seemingly not done intentionally in the interest
of simplification.  Specifically the client connection process and, I
think, the relationship between the checkpointer and background writer.

I do like the idea and the general flow of the material so far - though I
haven't really looked at the overall structure yet, just started reading
and editing from the top of the new file.

I've attached the original 0007 patch and my diff against it applied to
HEAD.

Took a quick peek at the image (at the end) and while I will need a second
pass over this section regardless I figured I'd provide this subset of
feedback now in order to move things along a bit.

David J.

  23. Re: Additional Chapter for Tutorial

    Jürgen Purtz <juergen@purtz.de> — 2020-10-23T13:58:46Z

    On 21.10.20 22:33, David G. Johnston wrote:
> I've begun looking at this and have included quite a few html comments 
> within the patch.  However, the two main items that I have found so 
> far are:
>
> One, I agree with Peter that this seems misplaced in Tutorial.  I 
> would create a new Internals Chapter and place this material there, or 
> maybe consider a sub-chapter under "Overview of PostgreSQL 
> Internals".  If this is deemed to be of a more primary importance than 
> the content in the Internals section I would recommend placing it in 
> Reference.  I feel it does fit there and given the general importance 
> of that section readers will be inclined to click into it and skim 
> over its content.

I like the idea of dividing the material into two different chapters. 
The existing part "I. Tutorial" contains the first concrete steps: 
installation, creating database and database objects, using SQL basic 
and advanced features. Its typical audience consists of persons doing 
their first steps with PG. The new material is aimed at persons 
interested in implementation aspects of PG. Therefore, the part "VII. 
Internals" seems to be the natural place to integrate it, something like 
"Architecture and Implementation Aspects" or "Architecture and 
Implementation Cornerstones".

Creating such a chapter in "VII. Internals" will increase the existing 
chapter numbers 50 - 71, which may lead to some confusion. On the other 
hand the content can possibly be applied to all supported PG versions at 
the same time, which will lead to a consistent behavior. Extending one 
of the existing chapters won't work because all of them handle their own 
topic, eg.: "50. Overview of PostgreSQL Internals" (misleading title?) 
focuses on the handling of SQL statements from parsing to execution.

What are your thoughts?

--

J. Purtz

  24. Re: Additional Chapter for Tutorial

    David G. Johnston <david.g.johnston@gmail.com> — 2020-10-23T16:15:14Z

    On Fri, Oct 23, 2020 at 6:58 AM Jürgen Purtz <juergen@purtz.de> wrote:

> Creating such a chapter in "VII. Internals" will increase the existing
> chapter numbers 50 - 71, which may lead to some confusion. On the other
> hand the content can possibly be applied to all supported PG versions at
> the same time, which will lead to a consistent behavior. Extending one of
> the existing chapters won't work because all of them handle their own
> topic, eg.: "50. Overview of PostgreSQL Internals" (misleading title?)
> focuses on the handling of SQL statements from parsing to execution.
>
> What are your thoughts?
>
v14 has already added a new chapter, installation from binaries.  It was
not back-patched.  To my knowledge no one brought up these points - numbers
changing or back-patching the new material.  I don't see that this
enhancement needs to be treated any differently.

David J.

  25. Re: Additional Chapter for Tutorial

    Jürgen Purtz <juergen@purtz.de> — 2020-10-26T13:33:35Z

    On 21.10.20 22:33, David G. Johnston wrote:
> I've begun looking at this and have included quite a few html comments 
> within the patch.  However, the two main items that I have found so 
> far are:
>
> One, I agree with Peter that this seems misplaced in Tutorial.  I 
> would create a new Internals Chapter and place this material there, or 
> maybe consider a sub-chapter under "Overview of PostgreSQL 
> Internals".  If this is deemed to be of a more primary importance than 
> the content in the Internals section I would recommend placing it in 
> Reference.  I feel it does fit there and given the general importance 
> of that section readers will be inclined to click into it and skim 
> over its content.
>
> Two, I find the amount of detail being provided here to be on the 
> too-much side.  A bit more judicious use of links into the appropriate 
> detail chapters seems warranted.
>
> I took a pretty heavy hand to the original section though aside from 
> the scope comment it can probably be considered a bit weighted toward 
> style preferences.  Though I did note/rewrite a couple of things that 
> seemed factually incorrect - and seemingly not done intentionally in 
> the interest of simplification.  Specifically the client connection 
> process and, I think, the relationship between the checkpointer and 
> background writer.
>
> I do like the idea and the general flow of the material so far - 
> though I haven't really looked at the overall structure yet, just 
> started reading and editing from the top of the new file.
>
> I've attached the original 0007 patch and my diff against it applied 
> to HEAD.
>
> Took a quick peek at the image (at the end) and while I will need a 
> second pass over this section regardless I figured I'd provide this 
> subset of feedback now in order to move things along a bit.
>
> David J.

The attached patch is an intermediate, mostly formal step. It includes:

- Moving the chapter to "Part VII. Internals".

- Changing the title of the current chapter "Chapter 50. Overview of 
PostgreSQL Internals" to "Overview of Query Handling" because the old 
title is too generic. This chapter is focused on the handling of queries.

- Integration of David's smaller suggestions. For the more important 
suggestions I need some days.

The patch is intended to give every interested person an overall 
impression of the chapter within its new position. Because it has moved 
from part 'Tutorial' to 'Internals' the text should be very accurate 
concerning technical issues - like all the other chapters in this part. 
A tutorial chapter has a more superficial nature.

--

J. Purtz

  26. Re: Additional Chapter for Tutorial

    David G. Johnston <david.g.johnston@gmail.com> — 2020-10-26T14:53:43Z

    Removing -docs as moderation won’t let me cross-post.

On Monday, October 26, 2020, David G. Johnston <david.g.johnston@gmail.com>
wrote:

> On Monday, October 26, 2020, Jürgen Purtz <juergen@purtz.de> wrote:
>
>> On 21.10.20 22:33, David G. Johnston wrote:
>>
>>
>> Two, I find the amount of detail being provided here to be on the
>> too-much side.  A bit more judicious use of links into the appropriate
>> detail chapters seems warranted.
>>
>> The patch is intended to give every interested person an overall
>> impression of the chapter within its new position. Because it has moved
>> from part 'Tutorial' to 'Internals' the text should be very accurate
>> concerning technical issues - like all the other chapters in this part. A
>> tutorial chapter has a more superficial nature.
>>
> Haven’t reviewed the patches yet but...
>
> I still think that my comment applies even with the move to internals.
> The value here is putting together a coherent narrative and making deeper
> implementation details accessible.  If those details are already covered
> elsewhere in the documentation (not source code) links should be given
> serious consideration.
>
> David J.
>
>

  27. Re: Additional Chapter for Tutorial

    Jürgen Purtz <juergen@purtz.de> — 2020-10-30T10:57:04Z

    On 26.10.20 15:53, David G. Johnston wrote:
> Removing -docs as moderation won’t let me cross-post.
>
> On Monday, October 26, 2020, David G. Johnston 
> <david.g.johnston@gmail.com <mailto:david.g.johnston@gmail.com>> wrote:
>
>     On Monday, October 26, 2020, Jürgen Purtz <juergen@purtz.de
>     <mailto:juergen@purtz.de>> wrote:
>
>         On 21.10.20 22:33, David G. Johnston wrote:
>>
>>         Two, I find the amount of detail being provided here to be on
>>         the too-much side.  A bit more judicious use of links into
>>         the appropriate detail chapters seems warranted.
>>
>         The patch is intended to give every interested person an
>         overall impression of the chapter within its new position.
>         Because it has moved from part 'Tutorial' to 'Internals' the
>         text should be very accurate concerning technical issues -
>         like all the other chapters in this part. A tutorial chapter
>         has a more superficial nature.
>
>     Haven’t reviewed the patches yet but...
>
>     I still think that my comment applies even with the move to
>     internals.  The value here is putting together a coherent
>     narrative and making deeper implementation details accessible.  If
>     those details are already covered elsewhere in the documentation
>     (not source code) links should be given serious consideration.
>
>     David J.
>
Please find the new patch in the attachment after integrating David's 
suggestions: a) versus the last patch and b) versus master.

Notably it contains

  * nearly all of his suggestions (see sgml file for comments 'DGJ')
  * reduction of <firstterm>. This was a hangover from the
    pre-glossary-times. I tried to emphasis standard terms. This is no
    longer necessary because nowadays they are clearly defined in the
    glossary.

--

J. Purtz

  28. Re: Additional Chapter for Tutorial

    Erik Rijkers <er@xs4all.nl> — 2020-10-30T16:45:00Z

    On 2020-10-30 11:57, Jürgen Purtz wrote:
> On 26.10.20 15:53, David G. Johnston wrote:
>> Removing -docs as moderation won’t let me cross-post.
>> 

Hi,

I applied 0009-architecture-vs-master.patch to head
and went through architecture.sgml (only that file),
then produced the attached .diff


And I wrote down some separate items:

1.
'Two Phase Locking' and 'TPL' should be, I think,
'Two-Phase Commit'. Please someone confirm.
(no changes made)

2.
To compare xid to sequence because they similarly 'count up' seems a bad 
idea.
(I don't think it's always true in the case of sequences)
(no changes made)

3.
'accesses' seems a somewhat strange word most of the time just 'access' 
may be better.  Not sure - native speaker wanted. (no changes made)

4.
'heap', in postgres, means often (always?) files. But more generally, 
the meaning is more associated with memory.  Therefore it would be good 
I think to explicitly use 'heap file' at least in the beginning once to 
make clear that heap implies 'safely written away to disk'.  Again, I'm 
not quite sure if my understanding is correct - I have made no changes 
in this regard.



Erik Rijkers

  29. Re: Additional Chapter for Tutorial

    Justin Pryzby <pryzby@telsasoft.com> — 2020-10-31T21:34:44Z

    On Fri, Oct 30, 2020 at 05:45:00PM +0100, Erik Rijkers wrote:
> On 2020-10-30 11:57, Jürgen Purtz wrote:
> > On 26.10.20 15:53, David G. Johnston wrote:
> > > Removing -docs as moderation won’t let me cross-post.
> > > 
> 
> Hi,
> 
> I applied 0009-architecture-vs-master.patch to head
> and went through architecture.sgml (only that file),
> then produced the attached .diff

Now I applied 0009 as well as Erik's changes and made some more of my own :)

I'm including all patches so CFBOT is happy.

> 3.
> 'accesses' seems a somewhat strange word most of the time just 'access' may
> be better.  Not sure - native speaker wanted. (no changes made)

You're right, and I included that part.

-- 
Justin

  30. Re: Additional Chapter for Tutorial

    Jürgen Purtz <juergen@purtz.de> — 2020-11-01T15:38:43Z

    On 30.10.20 17:45, Erik Rijkers wrote:
> Hi,
>
> I applied 0009-architecture-vs-master.patch to head
> and went through architecture.sgml (only that file),
> then produced the attached .diff
>
>
> And I wrote down some separate items:
>
> 1.
> 'Two Phase Locking' and 'TPL' should be, I think,
> 'Two-Phase Commit'. Please someone confirm.
> (no changes made)
>
> 2.
> To compare xid to sequence because they similarly 'count up' seems a 
> bad idea.
> (I don't think it's always true in the case of sequences)
> (no changes made)
>
> 3.
> 'accesses' seems a somewhat strange word most of the time just 
> 'access' may be better.  Not sure - native speaker wanted. (no changes 
> made)
>
> 4.
> 'heap', in postgres, means often (always?) files. But more generally, 
> the meaning is more associated with memory.  Therefore it would be 
> good I think to explicitly use 'heap file' at least in the beginning 
> once to make clear that heap implies 'safely written away to disk'.  
> Again, I'm not quite sure if my understanding is correct - I have made 
> no changes in this regard.
>
>
>
> Erik Rijkers

All suggestions so far are summarized in the attached patch with the 
following exceptions:

- 'Two Phase Locking' is the intended term.

- Not adopted:

      Second, the transfer of dirty buffers from Shared Memory to
      files must take place. This is the primary task of the
-    Background Writer process. Because I/O activities can block
+    Checkpointer process. Because I/O activities can block
      other processes, it starts periodically and

Partly adopted:

-    the data in the old version of the row does not change! ...

-    before. Nothing is thrown away so far! Only <literal>xmax</literal> ...

--

J. Purtz

  31. Re: Additional Chapter for Tutorial

    Erik Rijkers <er@xs4all.nl> — 2020-11-02T06:15:28Z

    On 2020-11-01 16:38, Jürgen Purtz wrote:
> On 30.10.20 17:45, Erik Rijkers wrote:
>> 
>> And I wrote down some separate items:
>> 
>> 1.
>> 'Two Phase Locking' and 'TPL' should be, I think,
>> 'Two-Phase Commit'. Please someone confirm.
>> (no changes made)
>> 
>> Erik Rijkers
> 
> All suggestions so far are summarized in the attached patch with the
> following exceptions:
> 
> - 'Two Phase Locking' is the intended term.

OK, so what is 'Two Phase Locking'?  The term is not explained, and not 
used anywhere else in the manual.  You propose to introduce it here, in 
the tutorial.  I don't know what it means, and I am not really a 
beginner.

'Two Phase Locking' should be explained somewhere, and how it relates 
(or not) to Two-Phase Commit (2PC), don't you agree?


Erik Rijkers

  32. Re: Additional Chapter for Tutorial

    Jürgen Purtz <juergen@purtz.de> — 2020-11-02T08:26:27Z

    On 02.11.20 07:15, Erik Rijkers wrote:
> On 2020-11-01 16:38, Jürgen Purtz wrote:
>> On 30.10.20 17:45, Erik Rijkers wrote:
>>>
>>> And I wrote down some separate items:
>>>
>>> 1.
>>> 'Two Phase Locking' and 'TPL' should be, I think,
>>> 'Two-Phase Commit'. Please someone confirm.
>>> (no changes made)
>>>
>>> Erik Rijkers
>>
>> All suggestions so far are summarized in the attached patch with the
>> following exceptions:
>>
>> - 'Two Phase Locking' is the intended term.
>
> OK, so what is 'Two Phase Locking'?  The term is not explained, and 
> not used anywhere else in the manual.  You propose to introduce it 
> here, in the tutorial.  I don't know what it means, and I am not 
> really a beginner.
>
> 'Two Phase Locking' should be explained somewhere, and how it relates 
> (or not) to Two-Phase Commit (2PC), don't you agree?
>
>
> Erik Rijkers
>
>
It may be possible to explain OCC and 2PL in two or three sentences 
within the glossary. But I think, we shall not try to explain such 
general strategies. They are not specific to PG and even not 
implemented. Instead, if the paragraph is too detailed, we can use a 
more general formulation without explicitly naming locking strategies.

OLD:

     A first approach to implement protections against concurrent
     access to the same data may be the locking of critical
     rows. Two such techniques are:
     <emphasis>Optimistic Concurrency Control</emphasis> (OCC)
     and <emphasis>Two Phase Locking</emphasis> (2PL).
     <productname>PostgreSQL</productname> implements a third, more
     sophisticated technique: <firstterm>Multiversion Concurrency
     Control</firstterm> (MVCC). The crucial advantage of MVCC ...

Proposal:

     A first approach to implement protections against concurrent
     access to the same data may be the locking of critical
     rows.
     <productname>PostgreSQL</productname> implements a more
     sophisticated technique which avoids any locking: 
<firstterm>Multiversion Concurrency
     Control</firstterm> (MVCC). The crucial advantage of MVCC ...

Any thoughts or other suggestions?

--

J. Purtz

  33. Re: Additional Chapter for Tutorial

    Erik Rijkers <er@xs4all.nl> — 2020-11-02T08:44:54Z

    On 2020-11-02 09:26, Jürgen Purtz wrote:

> OLD:
> 
>     A first approach to implement protections against concurrent
>     access to the same data may be the locking of critical
>     rows. Two such techniques are:
>     <emphasis>Optimistic Concurrency Control</emphasis> (OCC)
>     and <emphasis>Two Phase Locking</emphasis> (2PL).
>     <productname>PostgreSQL</productname> implements a third, more
>     sophisticated technique: <firstterm>Multiversion Concurrency
>     Control</firstterm> (MVCC). The crucial advantage of MVCC ...
> 
> Proposal:
> 
>     A first approach to implement protections against concurrent
>     access to the same data may be the locking of critical
>     rows.
>     <productname>PostgreSQL</productname> implements a more
>     sophisticated technique which avoids any locking:
> <firstterm>Multiversion Concurrency
>     Control</firstterm> (MVCC). The crucial advantage of MVCC ...
> 
> Any thoughts or other suggestions?
> 

Yes, just leave it out. Much better, as far as I'm concerned.

Erik

  34. Re: Additional Chapter for Tutorial

    Jürgen Purtz <juergen@purtz.de> — 2020-11-07T12:24:53Z

    On 02.11.20 09:44, Erik Rijkers wrote:
> On 2020-11-02 09:26, Jürgen Purtz wrote:
>
>> OLD:
>>
>>     A first approach to implement protections against concurrent
>>     access to the same data may be the locking of critical
>>     rows. Two such techniques are:
>>     <emphasis>Optimistic Concurrency Control</emphasis> (OCC)
>>     and <emphasis>Two Phase Locking</emphasis> (2PL).
>>     <productname>PostgreSQL</productname> implements a third, more
>>     sophisticated technique: <firstterm>Multiversion Concurrency
>>     Control</firstterm> (MVCC). The crucial advantage of MVCC ...
>>
>> Proposal:
>>
>>     A first approach to implement protections against concurrent
>>     access to the same data may be the locking of critical
>>     rows.
>>     <productname>PostgreSQL</productname> implements a more
>>     sophisticated technique which avoids any locking:
>> <firstterm>Multiversion Concurrency
>>     Control</firstterm> (MVCC). The crucial advantage of MVCC ...
>>
>> Any thoughts or other suggestions?
>>
>
> Yes, just leave it out. Much better, as far as I'm concerned.
>
> Erik
>
>
Because there have been no more comments in the last days I created a 
consolidated patch. It contains Erik's suggestion and some tweaks for 
the text size within graphics.

--

J. Purtz

  35. Re: Additional Chapter for Tutorial

    Erik Rijkers <er@xs4all.nl> — 2020-11-07T19:15:07Z

    On 2020-11-07 13:24, Jürgen Purtz wrote:
>> 
> Because there have been no more comments in the last days I created a
> consolidated patch. It contains Erik's suggestion and some tweaks for
> the text size within graphics.
> 
> [0011-architecture.patch]

Hi,

I went through architecture.sgml once more; some proposed changes 
attached.

And in some .svg files I noticed 'jungest' which should be 'youngest', I 
suppose.
I did not change them but below is filelist of  grep -l 'jung'.

./doc/src/sgml/images/freeze-ink.svg
./doc/src/sgml/images/freeze-ink-svgo.svg
./doc/src/sgml/images/freeze-raw.svg
./doc/src/sgml/images/wraparound-ink.svg
./doc/src/sgml/images/wraparound-ink-svgo.svg
./doc/src/sgml/images/wraparound-raw.svg


Thanks,

Erik

  36. Re: Additional Chapter for Tutorial

    Jürgen Purtz <juergen@purtz.de> — 2020-11-08T15:55:56Z

    On 07.11.20 20:15, Erik Rijkers wrote:
> On 2020-11-07 13:24, Jürgen Purtz wrote:
>>>
>> Because there have been no more comments in the last days I created a
>> consolidated patch. It contains Erik's suggestion and some tweaks for
>> the text size within graphics.
>>
>> [0011-architecture.patch]
>
> Hi,
>
> I went through architecture.sgml once more; some proposed changes 
> attached.
>
> And in some .svg files I noticed 'jungest' which should be 'youngest', 
> I suppose.
> I did not change them but below is filelist of  grep -l 'jung'.
>
> ./doc/src/sgml/images/freeze-ink.svg
> ./doc/src/sgml/images/freeze-ink-svgo.svg
> ./doc/src/sgml/images/freeze-raw.svg
> ./doc/src/sgml/images/wraparound-ink.svg
> ./doc/src/sgml/images/wraparound-ink-svgo.svg
> ./doc/src/sgml/images/wraparound-raw.svg
>
>
> Thanks,
>
> Erik
>
>
Good catches. Everything applied.

--

J. Purtz

  37. Re: Additional Chapter for Tutorial

    David G. Johnston <david.g.johnston@gmail.com> — 2020-11-09T23:14:57Z

    On Sun, Nov 8, 2020 at 8:56 AM Jürgen Purtz <juergen@purtz.de> wrote:

>
> Good catches. Everything applied.
>

Reviewed the first three sections.

template0 - I would remove the schema portions of this and simply note this
as being a pristine recovery database in the diagram.

I would drop the word "more" and just say "system schemas".  I would drop
pg_toast from the list of system schema and focus on the three user-facing
ones.

Instead of "my_schema" (optional) I would do "my_schema" (example)

Server Graphic
#3 Global SQL Objects: Objects which are shared among all databases within
a cluster.
#6 Client applications are prohibited from connecting to template0
#1 If by you we mean "the client" saying that you work "in the cluster
data" doesn't really help.  I would emphasize the point that the client
sees an endpoint the Postmaster publishes as a port or socket file and that
plus the database name defines the endpoint the client connects to (meld
with #5)

In lieu of some of the existing detail provided about structure I would add
information about configuration and search_path at this level.

I like the object type enumeration - I would suggest grouping them by type
in a manner consistent with the documentation and making each one a link to
its "primary" section - the SQL Command reference if all else fails.

The "i" in internal in 51.3 (the image) needs capitalization).

You correctly add both Extension and Collation as database-level objects
but they are not mentioned anywhere else.  They do belong here and need to
be tied in properly in the text.

The whole thing needs a good pass focused on capitalization.  Both for
typos and to decide when various primary concepts like Instance should be
capitalized and when not.

51.4 - When you look at the diagram seeing /pg/data/base looks really cool,
but when reading the prose where both the "pg" and the "base" are omitted
and all you get are repeated references to "data", the directory name
choice becomes an issue IMO.  I suggest (and changed the attached) to name
the actual root directory "pgdata".  You should change the /pg/ directory
name to something like ".../tutorial_project/".

Since you aren't following alphabetical order anyway I would place
pg_tblspc after globals since tablespaces are globals and thus proximity
links them here - and pointing out that pg_tblspc holds the data makes
stating that global doesn't contain tablespace data unnecessary.

Maybe point out somewhere the the "base/databaseOID" directory represents
the default tablespace for each database, which isn't "global", only the
non-default tablespaces are considered globals (or just get rid of the
mentioned on "non-default tablespace" for now).

David J.

  38. Re: Additional Chapter for Tutorial

    David G. Johnston <david.g.johnston@gmail.com> — 2020-11-10T21:58:26Z

    On Sun, Nov 8, 2020 at 8:56 AM Jürgen Purtz <juergen@purtz.de> wrote:

> Good catches. Everything applied.
>

MVCC Section

The first paragraph and example in the MVCC section is a good example but
seems misplaced - its relationship to MVCC generally is tenuous, rather I
would expect a discussion of the serializable isolation mode to follow.

I'm not sure how much detail this section wants to get into given the
coverage of concurrency elsewhere in the documentation.  "Not much" would
be my baseline.

I would suggest spelling out what "OLTP" stands for and ideally pointing
the user to the glossary for the term.

Tending more toward a style gripe but the amount of leader phrases and
redundancy are at a level that I am noticing them when I read this but do
not have the same impression having read large portions of documentation.
In particular:

"When we speak about transaction IDs, you need to know that xids are like
sequences."

"But keep in mind that xids are independent of any time measurement — in
milliseconds or otherwise. If you dive deeper into PostgreSQL, you will
recognize parameters with names such as 'xxx_age'. Despite their names,
these '_age' parameters do not specify a period of time but represent a
certain number of transactions, e.g., 100 million."

Could just be:  xids are sequences and age computations involving them
measure a transaction count as opposed to a time interval.

Then I would consider adding a bit more detail/context here.

xids are 32bit sequences, with a reserved value to handle wrap-around.
There are 4 billion values in the sequence but wrap-around handling must
occur every 2 billion transactions. Age computations involving xids measure
a transaction count as opposed to a time interval.

I would move the mentioning of "vacuum" to the main paragraph about delete
and not solely as a "keep in mind" note.

The part before the diagram seems like it should be much shorter, concise,
and provide links to the excellent documentation.  The part after the
image, and the image itself, are good material, though possibly should be
in a main administration chapter instead of an internals chapter.

The first bullet of "keep in mind" is both wordy and wrong - in particular
"as xids grow old row versions get out of scope over time" doesn't make
sense (or rather it only does in the context of wrap-around, not normal
visibility).  Having the only mention of bloat be here is also not ideal,
it too should be weaved into the main narrative.  The "keep in mind"
section here should be a recap of already covered material in a succinct
form, nothing should be new to someone who just read the entire section.

I don't think that usage of exclamation marks (!) is warranted here, though
emphasis on the key phrase wouldn't hurt.

Vacuum Section

avoid -> prevent (continued growth)

Autovacuum is enabled by default.  The whole note needs commas.

I'd try to get rid of "at arbitrary point in time"

"Instance." we've already described where instances are previously ("on the
server")

The other sections - these seem misplaced for the tutorial, update the main
documentation if this information is wholly missing or lacking.  The MVCC
chapter can incorporate overview information as it is a strict consequence
of that implementation.

Statistics belong elsewhere - the tutorial should not use poor command
implementation choices as a guide for user education.

In short, this whole section should not exist and its content moved to more
appropriate areas (mainly MVCC).  Vacuum is a tool that one must use but
the narrative should be about the system generally.

David J.

  39. Re: Additional Chapter for Tutorial

    Jürgen Purtz <juergen@purtz.de> — 2020-11-15T18:45:35Z

    On 10.11.20 00:14, David G. Johnston wrote:
> Reviewed the first three sections.
>
> template0 - I would remove the schema portions of this and simply note 
> this as being a pristine recovery database in the diagram.
ok
>
> I would drop the word "more" and just say "system schemas".  I would 
> drop pg_toast from the list of system schema and focus on the three 
> user-facing ones.
ok
>
> Instead of "my_schema" (optional) I would do "my_schema" (example)
The terms 'optional' and 'default' are used at various places with their 
literal meaning. We shall not change them.
>
> Server Graphic
> #3 Global SQL Objects: Objects which are shared among all databases 
> within a cluster.
> #6 Client applications are prohibited from connecting to template0
ok
> #1 If by you we mean "the client" saying that you work "in the cluster 
> data" doesn't really help.  I would emphasize the point that the 
> client sees an endpoint the Postmaster publishes as a port or socket 
> file and that plus the database name defines the endpoint the client 
> connects to (meld with #5)
ok, with some changes.
>
> In lieu of some of the existing detail provided about structure I 
> would add information about configuration and search_path at this level.
Search path appended. But IMO configuration questions are out of scope 
of this sub-chapter.
>
> I like the object type enumeration - I would suggest grouping them by 
> type in a manner consistent with the documentation and making each one 
> a link to its "primary" section - the SQL Command reference if all 
> else fails.
ok. But don't how to group them in a better way.
>
> The "i" in internal in 51.3 (the image) needs capitalization).
ok
>
> You correctly add both Extension and Collation as database-level 
> objects but they are not mentioned anywhere else.  They do belong here 
> and need to be tied in properly in the text.
Have some courage to the gap, it's an introductory chapter.
>
> The whole thing needs a good pass focused on capitalization.  Both for 
> typos and to decide when various primary concepts like Instance should 
> be capitalized and when not.
'Instance' and 'Cluster' are now uppercase because of their importance, 
everything else lowercase for better reading.
>
> 51.4 - When you look at the diagram seeing /pg/data/base looks really 
> cool, but when reading the prose where both the "pg" and the "base" 
> are omitted and all you get are repeated references to "data", the 
> directory name choice becomes an issue IMO.  I suggest (and changed 
> the attached) to name the actual root directory "pgdata".  You should 
> change the /pg/ directory name to something like ".../tutorial_project/".

The graphic shall reflect the default behavior of PG. Without the 
parameter -D, initdb creates the new cluster in the directory where 
PGDATA points to. This is in many cases |/var/lib/pgsql/data|. Therefore 
'data' and its subdirectory 'base' are not my invention but reflects the 
default situation.

(Diving a little deeper into this issue I noticed that there is a 
parameter 'cluster_name' in the config file. But it does not change the 
name of the cluster's root directory, it only changes the names of the 
running processes. Choosing 'instance_name' instead of 'cluster_name' as 
the parameter's name would be a better choice imo - but that is not what 
we are speaking about in the context of the new chapter).

I changed the very first directory in the graphic to visualize the 
standard behavior; I reverted your recommendation to use 'pgdata' 
instead of 'data' in the text part.

> Since you aren't following alphabetical order anyway I would place 
> pg_tblspc after globals since tablespaces are globals and thus 
> proximity links them here - and pointing out that pg_tblspc holds the 
> data makes stating that global doesn't contain tablespace data 
> unnecessary.
ok
>
> Maybe point out somewhere the the "base/databaseOID" directory 
> represents the default tablespace for each database, which isn't 
> "global", only the non-default tablespaces are considered globals (or 
> just get rid of the mentioned on "non-default tablespace" for now).

ok

more:

1) some changes concerning the nature of connections (52.2: logical 
perspective). IMO accessing multiple databases within one connection is 
not a question of configuring, you have to take more actions. But I'm 
not sure we should mention this at all.

2) you propose to cancel or trim down the paragraphs behind figure 51.2. 
(cluster, database, schema). I believe that a textual description of 
this hierarchy is essential for the understanding of the system. Because 
it isn't described explicitly at a different place, it should remain.

--- snipp -------- from other e-mail ----

> MVCC Section
>
> The first paragraph and example in the MVCC section is a good example 
> but seems misplaced - its relationship to MVCC generally is tenuous, 
> rather I would expect a discussion of the serializable isolation mode 
> to follow.
>
> I'm not sure how much detail this section wants to get into given the 
> coverage of concurrency elsewhere in the documentation.  "Not much" 
> would be my baseline.
The paragraph focus on the fact that new row versions are generated 
instead of locking something. Explaining serialization isolation modes 
is imo very complicate and out of the scope of this subchapter. If we 
want to give an overview - in addition to the exiting documentation - it 
should be a separate subchapter.
>
> I would suggest spelling out what "OLTP" stands for and ideally 
> pointing the user to the glossary for the term.
ok, but not added to glossary. The given explanation "... with a massive 
number of concurrent write actions" should be sufficient.
>
> Tending more toward a style gripe but the amount of leader phrases and 
> redundancy are at a level that I am noticing them when I read this but 
> do not have the same impression having read large portions of 
> documentation. In particular:
Because I'm not a native English speaker, orthographic and style hits 
are always welcome.
>
> "When we speak about transaction IDs, you need to know that xids are 
> like sequences."
>
> "But keep in mind that xids are independent of any time measurement — 
> in milliseconds or otherwise. If you dive deeper into PostgreSQL, you 
> will recognize parameters with names such as 'xxx_age'. Despite their 
> names, these '_age' parameters do not specify a period of time but 
> represent a certain number of transactions, e.g., 100 million."
>
> Could just be:  xids are sequences and age computations involving them 
> measure a transaction count as opposed to a time interval.
ok
>
> Then I would consider adding a bit more detail/context here.
>
> xids are 32bit sequences, with a reserved value to handle 
> wrap-around.  There are 4 billion values in the sequence but 
> wrap-around handling must occur every 2 billion transactions. Age 
> computations involving xids measure a transaction count as opposed to 
> a time interval.
>
> I would move the mentioning of "vacuum" to the main paragraph about 
> delete and not solely as a "keep in mind" note.
The mentioning here at the food of the page is a crossover to the next 
subchapter.
>
> The part before the diagram seems like it should be much shorter, 
> concise, and provide links to the excellent documentation.  The part 
> after the image, and the image itself, are good material, though 
> possibly should be in a main administration chapter instead of an 
> internals chapter.

vacuum: The problem - and one reason for the existence of this 
subchapter - is that vacuum's documentation is scattered across may pages:

19.4: parameters to configure the server, especially five parameters 
'vacuum_cost_xxx'.

19.10: parameters to configure autovacuum.

19.11: parameters to configure client connections, especially five 
parameters 'vacuum_xxx' concerning their freeze-behavior.

24.1: explains the general necessity of (auto)vacuum and their strategies.

The page about the SQL command VACUUM explains the different options 
(FULL, FREEZE, ..) and their meaning.

Because of the structure of our documentation as well as the complexity 
of the issue that's ok. The existing documentation describes every 
parameter very well, but I'm missing a page where the 'big picture' of 
vacuum is explained (not necessarily here). It shall show the 
relationship between the huge number of parameters and an explanation 
*why* they exists. As far as we don't have such a page within the vacuum 
documentation the proposed subchapter fills the gap. (The provided 
graphics can be included multiple times without generating redundancies 
- here and at arbitrary other places.)

>
> The first bullet of "keep in mind" is both wordy and wrong - in 
> particular "as xids grow old row versions get out of scope over time" 
> doesn't make sense (or rather it only does in the context of 
> wrap-around, not normal visibility).  Having the only mention of bloat 
> be here is also not ideal, it too should be weaved into the main 
> narrative.  The "keep in mind" section here should be a recap of 
> already covered material in a succinct form, nothing should be new to 
> someone who just read the entire section.
ok.
>
> I don't think that usage of exclamation marks (!) is warranted here, 
> though emphasis on the key phrase wouldn't hurt.
ok
>
> Vacuum Section
>
> avoid -> prevent (continued growth)
ok
>
> Autovacuum is enabled by default.  The whole note needs commas.
ok
>
> I'd try to get rid of "at arbitrary point in time"
ok
>
> "Instance." we've already described where instances are previously 
> ("on the server")
ok
>
> The other sections - these seem misplaced for the tutorial, update the 
> main documentation if this information is wholly missing or lacking.  
> The MVCC chapter can incorporate overview information as it is a 
> strict consequence of that implementation.
>
> Statistics belong elsewhere - the tutorial should not use poor command 
> implementation choices as a guide for user education.
>
> In short, this whole section should not exist and its content moved to 
> more appropriate areas (mainly MVCC).  Vacuum is a tool that one must 
> use but the narrative should be about the system generally.
>
>
concerning vacuum section: see my comments above

concerning 'the other sections' (transactions, reliability, backup 
(plus: someone should add 'replication', I'm not familiar with this 
issue)): The intention of the chapter is to give a *summary* about PG's 
essential architecture and about central implementation aspects. This 
implies that the chapters does not present any new information. They 
shall only show (or repeat) essential things in their context and 
explain *why* they are used. In this sense the three chapters may be 
reasonable. Concerning this, I like to hear some comments from other people.


Attachments:

0013-architecture.patch: complete patch vs. master

0013-architecture.sgml.diff: changes in file architecture.sgml since 0012

0013-images.diff: changes in files *-raw.svg since 0012

-- 

J. Purtz

  40. Re: Additional Chapter for Tutorial - arch-dev.sgml

    Erik Rijkers <er@xs4all.nl> — 2020-11-20T21:52:32Z

    On 2020-11-15 19:45, Jürgen Purtz wrote:
>> 

(smallish) Changes to arch-dev.sgml

Erik

  41. Re: Additional Chapter for Tutorial - arch-dev.sgml

    Heikki Linnakangas <hlinnaka@iki.fi> — 2021-01-18T14:13:22Z

    On 20/11/2020 23:52, Erik Rijkers wrote:
> (smallish) Changes to arch-dev.sgml

This looks good to me. One little complaint:

> @@ -125,7 +122,7 @@
>      use a <firstterm>supervisor process</firstterm> (also
>      <firstterm>master process</firstterm>) that spawns a new
>      server process every time a connection is requested. This supervisor
> -    process is called <literal>postgres</literal> and listens at a
> +    process is called <literal>postgres</literal> (formerly 'postmaster') and listens at a
>      specified TCP/IP port for incoming connections. Whenever a request
>      for a connection is detected the <literal>postgres</literal>
>      process spawns a new server process. The server tasks

I believe we still call it the postmaster process. We renamed the binary 
a long time ago (commit 5266f221a2), and the above text was changed as 
part of that commit. I think that was a mistake, and this should say simply:

... This supervisor process is called <literal>postmaster</literal> and ...

like it did before we renamed the binary.

Barring objections, I'll commit this with that change (as attached).

- Heikki

  42. Re: Additional Chapter for Tutorial - arch-dev.sgml

    Jürgen Purtz <juergen@purtz.de> — 2021-01-19T06:37:25Z

    On 18.01.21 15:13, Heikki Linnakangas wrote:
> On 20/11/2020 23:52, Erik Rijkers wrote:
>> (smallish) Changes to arch-dev.sgml
>
> This looks good to me. One little complaint:
>
>> @@ -125,7 +122,7 @@
>>      use a <firstterm>supervisor process</firstterm> (also
>>      <firstterm>master process</firstterm>) that spawns a new
>>      server process every time a connection is requested. This 
>> supervisor
>> -    process is called <literal>postgres</literal> and listens at a
>> +    process is called <literal>postgres</literal> (formerly 
>> 'postmaster') and listens at a
>>      specified TCP/IP port for incoming connections. Whenever a request
>>      for a connection is detected the <literal>postgres</literal>
>>      process spawns a new server process. The server tasks
>
> I believe we still call it the postmaster process. We renamed the 
> binary a long time ago (commit 5266f221a2), and the above text was 
> changed as part of that commit. I think that was a mistake, and this 
> should say simply:
>
> ... This supervisor process is called <literal>postmaster</literal> 
> and ...
>
> like it did before we renamed the binary.
>
> Barring objections, I'll commit this with that change (as attached).
>
> - Heikki

I fear that the patch 'Additional chapter for Tutorial' grows beyond 
manageable limits. It runs since nearly one year, the size of 228 KB is 
very huge, many people havemade significant contributions. But a commit 
seems to be in far distance. Having said that, I'm pleased with Heikki's 
proposal to split changes in the existing file 'arch-dev.sgml' from the 
rest of the patch and commit them separately.

But I have some concerns with the chapter '51.2. How Connections Are 
Established'. It uses central terms like 'client process', 'server 
process','supervisor process', 'master process', 'server tasks', 
'backend (server)', 'frontend (client)', 'server', 'client'. Some month 
ago, we have cleared his terminology in the new chapter 'glossary'. As 
long as it leads to readable text, we shall use the glossary-terms 
instead of the current ones. And we shall include some links to the 
glossary.

I propose to start a new thread which contains only changes to 
'arch-dev.sgml'. In pgsql-hackers or in pgsql-docs list? Initialized by 
Heikki or by me?

--

Jürgen Purtz

  43. Re: Additional Chapter for Tutorial - arch-dev.sgml

    Jürgen Purtz <juergen@purtz.de> — 2021-01-21T12:38:26Z

    On 18.01.21 15:13, Heikki Linnakangas wrote:
> On 20/11/2020 23:52, Erik Rijkers wrote:
>> (smallish) Changes to arch-dev.sgml
>
> This looks good to me. One little complaint:
>
>> @@ -125,7 +122,7 @@
>>      use a <firstterm>supervisor process</firstterm> (also
>>      <firstterm>master process</firstterm>) that spawns a new
>>      server process every time a connection is requested. This 
>> supervisor
>> -    process is called <literal>postgres</literal> and listens at a
>> +    process is called <literal>postgres</literal> (formerly 
>> 'postmaster') and listens at a
>>      specified TCP/IP port for incoming connections. Whenever a request
>>      for a connection is detected the <literal>postgres</literal>
>>      process spawns a new server process. The server tasks
>
> I believe we still call it the postmaster process. We renamed the 
> binary a long time ago (commit 5266f221a2), and the above text was 
> changed as part of that commit. I think that was a mistake, and this 
> should say simply:
>
> ... This supervisor process is called <literal>postmaster</literal> 
> and ...
>
> like it did before we renamed the binary.
>
> Barring objections, I'll commit this with that change (as attached).
>
> - Heikki

Some additional changes in 51.2:

  - smaller number of different terms

  - aligning with Glossary

  - active voice instead of passive voice

  - commas

---

J. Purtz

  44. Re: Additional Chapter for Tutorial - arch-dev.sgml

    Heikki Linnakangas <hlinnaka@iki.fi> — 2021-01-22T09:15:40Z

    On 21/01/2021 14:38, Jürgen Purtz wrote:
> This supervisor process is called <glossterm
> linkend="glossary-postmaster">postmaster</glossterm> and listens at
> a specified TCP/IP port for incoming connections. Whenever he
> detects a request for a connection, he spawns a new backend process.

It sounds weird to refer to a process with "he". I left out this hunk, 
and the other with similar changes.

Committed the rest, thanks!.

- Heikki

  45. Re: Additional Chapter for Tutorial - arch-dev.sgml

    David Steele <david@pgmasters.net> — 2021-03-25T13:00:11Z

    On 1/22/21 4:15 AM, Heikki Linnakangas wrote:
> On 21/01/2021 14:38, Jürgen Purtz wrote:
>> This supervisor process is called <glossterm
>> linkend="glossary-postmaster">postmaster</glossterm> and listens at
>> a specified TCP/IP port for incoming connections. Whenever he
>> detects a request for a connection, he spawns a new backend process.
> 
> It sounds weird to refer to a process with "he". I left out this hunk, 
> and the other with similar changes.
> 
> Committed the rest, thanks!.

So it looks like this was committed. Is there anything left to do?

If not, we should close the CF entry.

Regards,
-- 
-David
david@pgmasters.net

  46. Re: Additional Chapter for Tutorial - arch-dev.sgml

    Alvaro Herrera <alvherre@alvh.no-ip.org> — 2021-04-03T13:39:55Z

    On 2021-Mar-25, David Steele wrote:

> On 1/22/21 4:15 AM, Heikki Linnakangas wrote:
> > On 21/01/2021 14:38, Jürgen Purtz wrote:
> > > This supervisor process is called <glossterm
> > > linkend="glossary-postmaster">postmaster</glossterm> and listens at
> > > a specified TCP/IP port for incoming connections. Whenever he
> > > detects a request for a connection, he spawns a new backend process.
> > 
> > It sounds weird to refer to a process with "he". I left out this hunk,
> > and the other with similar changes.
> > 
> > Committed the rest, thanks!.
> 
> So it looks like this was committed. Is there anything left to do?

Yes, there is.  AFAICS Heikki committed a small wordsmithing patch --
not the large patch with the additional chapter.

-- 
Álvaro Herrera                            39°49'30"S 73°17'W
"Ed is the standard text editor."
      http://groups.google.com/group/alt.religion.emacs/msg/8d94ddab6a9b0ad3

  47. Re: Additional Chapter for Tutorial - arch-dev.sgml

    Jürgen Purtz <juergen@purtz.de> — 2021-04-03T17:43:48Z

    On 03.04.21 15:39, Alvaro Herrera wrote:
> Yes, there is.  AFAICS Heikki committed a small wordsmithing patch --
> not the large patch with the additional chapter.

What can i do to move the matter forward?

--

J. Purtz

  48. Re: Additional Chapter for Tutorial - arch-dev.sgml

    Alvaro Herrera <alvherre@alvh.no-ip.org> — 2021-04-03T19:01:10Z

    On 2021-Apr-03, Jürgen Purtz wrote:

> On 03.04.21 15:39, Alvaro Herrera wrote:
> > Yes, there is.  AFAICS Heikki committed a small wordsmithing patch --
> > not the large patch with the additional chapter.
> 
> What can i do to move the matter forward?

Please post a version that applies to the current sources.  If the
latest version posted does, please state so.

-- 
Álvaro Herrera                            39°49'30"S 73°17'W

  49. Re: Additional Chapter for Tutorial - arch-dev.sgml

    Jürgen Purtz <juergen@purtz.de> — 2021-04-04T09:07:55Z

    On 03.04.21 21:01, Alvaro Herrera wrote:
> On 2021-Apr-03, Jürgen Purtz wrote:
>
>> On 03.04.21 15:39, Alvaro Herrera wrote:
>>> Yes, there is.  AFAICS Heikki committed a small wordsmithing patch --
>>> not the large patch with the additional chapter.
>> What can i do to move the matter forward?
> Please post a version that applies to the current sources.  If the
> latest version posted does, please state so.
>
The small patch 'arch-dev.sgml.20210121.diff' contains only some 
clearing up concerning the used terminology and its alignments with the 
glossary. The patch was rejected by Heikki.

The latest version of the huge patch '0013-architecture.patch' is valid 
and doesn't contain merge conflicts.

--
Jürgen Purtz

  50. Re: Additional Chapter for Tutorial - arch-dev.sgml

    Alvaro Herrera <alvherre@alvh.no-ip.org> — 2021-04-04T17:02:48Z

    On 2021-Apr-04, Jürgen Purtz wrote:

> The small patch 'arch-dev.sgml.20210121.diff' contains only some clearing up
> concerning the used terminology and its alignments with the glossary. The
> patch was rejected by Heikki.

This comment is not helpful, because it's not obvious where would I find
that patch.  Also, you say "the patch was rejected by Heikki" but
upthread he said he committed it.  His comment was that he left out some
paragraphs because of a style issue.  Did you re-post that patch after
fixing the style issues?  If you did, I couldn't find it.


> The latest version of the huge patch '0013-architecture.patch' is valid and
> doesn't contain merge conflicts.

Yeah, OK, but I have to dive deep in the thread to find it.  Please post
it again.  When you have a patch series, please post it as a whole every
time -- that makes it easier for a committer to review it.

You seem to be making your life hard by not using git to assist you.  Do
you know you can have several commits in a branch of your own, rebase it
to latest master, merge master to it, rebase on top of master, commit
fixups, "rebase -i" and change commit ordering to remove unnecessary
fixup commits, and so on?  Such techniques are extremely helpful when
dealing with a patch series.  When you want to post a new version to the
list, you can just do "git format-patch -v14 origin/master" to produce a
set of patch files.  You don't need to manually give names to your patch
files, or come up with a versioning scheme.  Just increment the argument
to -v by +1 each time you (or somebody else) posts a new version of the
patch series.

-- 
Álvaro Herrera       Valdivia, Chile

  51. Re: Additional Chapter for Tutorial - arch-dev.sgml

    Jürgen Purtz <juergen@purtz.de> — 2021-04-05T13:18:44Z

    On 04.04.21 19:02, Alvaro Herrera wrote:
> On 2021-Apr-04, Jürgen Purtz wrote:
>
>> The small patch 'arch-dev.sgml.20210121.diff' contains only some clearing up
>> concerning the used terminology and its alignments with the glossary. The
>> patch was rejected by Heikki.
> This comment is not helpful, because it's not obvious where would I find
> that patch.  Also, you say "the patch was rejected by Heikki" but
> upthread he said he committed it.  His comment was that he left out some
> paragraphs because of a style issue.  Did you re-post that patch after
> fixing the style issues?  If you did, I couldn't find it.
>
>
>> The latest version of the huge patch '0013-architecture.patch' is valid and
>> doesn't contain merge conflicts.
> Yeah, OK, but I have to dive deep in the thread to find it.  Please post
> it again.  When you have a patch series, please post it as a whole every
> time -- that makes it easier for a committer to review it.
>
> You seem to be making your life hard by not using git to assist you.  Do
> you know you can have several commits in a branch of your own, rebase it
> to latest master, merge master to it, rebase on top of master, commit
> fixups, "rebase -i" and change commit ordering to remove unnecessary
> fixup commits, and so on?  Such techniques are extremely helpful when
> dealing with a patch series.  When you want to post a new version to the
> list, you can just do "git format-patch -v14 origin/master" to produce a
> set of patch files.  You don't need to manually give names to your patch
> files, or come up with a versioning scheme.  Just increment the argument
> to -v by +1 each time you (or somebody else) posts a new version of the
> patch series.
>
The thread contains a sequence of files '0001_architecture.patch' to 
'0013_architecture.patch' (with gaps in the numbering) created by me and 
other authors over the last 12 month. This is what I call the 'huge 
patch'. Indeed, the files are created more or less manually without the 
format-patch option. I welcome the reference to rebase and format-patch 
and I'm considering to use it in the future.

In addition to this chain Erik introduced in November within the same 
thread some changes to the chapter "Overview of Query Handling", which 
subsequently was expanded by Heikki and me with the sequence of 
'arch-dev.sgml.xxxxx.diff' files. This is what I call the 'small patch'. 
It's independent from the 'huge patch'. That 'small patch' is partly 
committed by Heikki. In case that a committer gives the uncommitted part 
a second chance, I append a patch. Because I'm not a native English 
speaker, every improvement in the linguistic is highly welcome.

--

Jürgen Purtz

  52. Re: Additional Chapter for Tutorial - arch-dev.sgml

    Alvaro Herrera <alvherre@alvh.no-ip.org> — 2021-04-05T15:48:14Z

    On 2021-Apr-05, Jürgen Purtz wrote:

> In addition to this chain Erik introduced in November within the same thread
> some changes to the chapter "Overview of Query Handling", which subsequently
> was expanded by Heikki and me with the sequence of
> 'arch-dev.sgml.xxxxx.diff' files. This is what I call the 'small patch'.
> It's independent from the 'huge patch'. That 'small patch' is partly
> committed by Heikki. In case that a committer gives the uncommitted part a
> second chance, I append a patch. Because I'm not a native English speaker,
> every improvement in the linguistic is highly welcome.

Pushed this one with cosmetic adjustments.

-- 
Álvaro Herrera       Valdivia, Chile
"Cuando mañana llegue pelearemos segun lo que mañana exija" (Mowgli)

  53. Re: Additional Chapter for Tutorial

    Erik Rijkers <er@xs4all.nl> — 2021-05-20T21:02:30Z

    Hi Jürgen,

What's going to happen with this work?

If you intend to have it eventually committed, I think it will be 
necessary to make the patches smaller, and bring them into the 
commitfest app, so that others can follow progress.

I for one, cannot see/remember/understand what has been done, or even 
whether you intend to continue with it.

Thanks,

Erik

  54. Re: Additional Chapter for Tutorial

    Jürgen Purtz <juergen@purtz.de> — 2021-05-21T06:47:15Z

    > Hi Jürgen,
>
> What's going to happen with this work?
>
> If you intend to have it eventually committed, I think it will be 
> necessary to make the patches smaller, and bring them into the 
> commitfest app, so that others can follow progress.
>
> I for one, cannot see/remember/understand what has been done, or even 
> whether you intend to continue with it.
>
> Thanks,
>
> Erik
>
>
Peter changed the status to 'Returned with feedback' at the end of the 
last commit fest. I'm not absolutely sure, but my understanding is that 
the patch is rejected.

--

Jürgen Purtz

  55. Re: Additional Chapter for Tutorial

    Laurenz Albe <laurenz.albe@cybertec.at> — 2021-05-21T08:52:42Z

    On Fri, 2021-05-21 at 08:47 +0200, Jürgen Purtz wrote:
> Peter changed the status to 'Returned with feedback' at the end of the 
> last commit fest. I'm not absolutely sure, but my understanding is that 
> the patch is rejected.

There is a different status for that.

"Returned with feedback" means: there was review, and further work by
the author is needed, or we need more discussion if we want that or not
or how it should be, but there hasn't been a lot of feedback from the author
lately, so it seems that just moving it on to the next commitfest is not
the right thing to do.

You are welcome to re-submit the patch if you address the feedback.

Yours,
Laurenz Albe