Detailed release notes

On 26 Jul 2024, at 14:30, Marcos Pegoraro <marcos@f10.com.br> wrote:

I'm now using version 14 and planning to update to 17 as soon as it comes available. Then looking carefully to release notes to see exactly what I'll get when updated I see lots of unexplained features. Just because release notes does not explain exactly what that change does. And I don't have a way to get what code or messages generated that feature.

There is a way, but it's not exactly visible from reading the release notes.

• Allow query nodes to be run in parallel in more cases (Tom Lane)
Cool this feature, but when and what kind of query will use this ?

Reading the source of the release notes will show a comment which links to the
commit. The source can be seen here:

https://github.com/postgres/postgres/blob/REL_17_STABLE/doc/src/sgml/release-17.sgml

..and the comment for this item is:

<!--
Author: Tom Lane <tgl@sss.pgh.pa.us>
2023-07-14 [e08d74ca1] Allow plan nodes with initPlans to be considered paralle
-->

<listitem>
<para>
Allow query nodes to be run in parallel in more cases (Tom Lane)
</para>
</listitem>

This comment tells us the relevant commit is e08d74ca1, which can be found here:

https://github.com/postgres/postgres/commit/e08d74ca1

This in turn leads to the mailinglist discussion for this specific feature:

/messages/by-id/1129530.1681317832@sss.pgh.pa.us

--
Daniel Gustafsson

Em sex., 26 de jul. de 2024 às 09:45, Daniel Gustafsson <daniel@yesql.se>
escreveu:

There is a way, but it's not exactly visible from reading the release
notes.

Cool, didn't know that.
But why is that just a hidden comment and not a visible link for us ?

regards
Marcos

On 26 Jul 2024, at 15:00, Marcos Pegoraro <marcos@f10.com.br> wrote:

But why is that just a hidden comment and not a visible link for us ?

That's likely the wrong level of detail for the overwhelming majority of
release notes readers. I have a feeling this was discussed not too long ago
but (if so) I fail to find that discussion now.

--
Daniel Gustafsson

Em sex., 26 de jul. de 2024 às 10:11, Daniel Gustafsson <daniel@yesql.se>
escreveu:

That's likely the wrong level of detail for the overwhelming majority of
release notes readers. I have a feeling this was discussed not too long
ago
but (if so) I fail to find that discussion now.

Wrong level ? Where is the appropriate place on DOCs to see exactly what
I'll get when updated ?
A separate page "Detailed Release Notes" ? I don't think so.
I think release notes are sometimes the only place we read to decide if an
upgrade is doable or not.

Well, that opened my eyes, now I can see detailed info about every feature
when it's committed.
And I'm really convinced that a small link to that commit wouldn't
get dirty release notes.

On Fri, Jul 26, 2024 at 9:26 AM Marcos Pegoraro <marcos@f10.com.br> wrote:

Well, that opened my eyes, now I can see detailed info about every feature when it's committed.
And I'm really convinced that a small link to that commit wouldn't get dirty release notes.

+1. I think those links would be useful to a lot of people.

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

Daniel Gustafsson <daniel@yesql.se> writes:

On 26 Jul 2024, at 15:00, Marcos Pegoraro <marcos@f10.com.br> wrote:
But why is that just a hidden comment and not a visible link for us ?

That's likely the wrong level of detail for the overwhelming majority of
release notes readers. I have a feeling this was discussed not too long ago
but (if so) I fail to find that discussion now.

Yeah, I too recall some discussion of surfacing the commit links
somehow, perhaps as a popup tooltip. Nobody's got round to it yet.
It's not real clear how to handle multiple links per <para>, which
happens from time to time in major release notes and just about
everyplace in minor release notes.

regards, tom lane

On Fri, Jul 26, 2024 at 6:56 AM Robert Haas <robertmhaas@gmail.com> wrote:

On Fri, Jul 26, 2024 at 9:26 AM Marcos Pegoraro <marcos@f10.com.br> wrote:

Well, that opened my eyes, now I can see detailed info about every feature when it's committed.
And I'm really convinced that a small link to that commit wouldn't get dirty release notes.

+1. I think those links would be useful to a lot of people.

+1. I've been asked a lot of times how to find the associated commit
IDs from release note items. These links would help users know the
details of the changes, and I believe many users would like to do
that.

Regards,

--
Masahiko Sawada
Amazon Web Services: https://aws.amazon.com

Em sex., 26 de jul. de 2024 às 13:01, Masahiko Sawada <sawada.mshk@gmail.com>
escreveu:

+1. I've been asked a lot of times how to find the associated commit
IDs from release note items. These links would help users know the
details of the changes, and I believe many users would like to do
that.

Yes, this way release notes would explain itself.

For now my release notes will be this
https://github.com/postgres/postgres/blob/REL_17_STABLE/doc/src/sgml/release-17.sgml
and not this
https://www.postgresql.org/docs/17/release-17.html

regards
Marcos

On Fri, Jul 26, 2024 at 10:11 PM Tom Lane <tgl@sss.pgh.pa.us> wrote:

Daniel Gustafsson <daniel@yesql.se> writes:

On 26 Jul 2024, at 15:00, Marcos Pegoraro <marcos@f10.com.br> wrote:
But why is that just a hidden comment and not a visible link for us ?

That's likely the wrong level of detail for the overwhelming majority of
release notes readers. I have a feeling this was discussed not too long ago
but (if so) I fail to find that discussion now.

Yeah, I too recall some discussion of surfacing the commit links
somehow, perhaps as a popup tooltip. Nobody's got round to it yet.
It's not real clear how to handle multiple links per <para>, which
happens from time to time in major release notes and just about
everyplace in minor release notes.

similar to https://docs.python.org/3/whatsnew/changelog.html

Change functions to use a safe search_path during maintenance
operations (Jeff Davis)

change to

[commitId_link1, commitId_link2]: Change functions to use a safe
search_path during maintenance operations (Jeff Davis)

Does this make sense?
If so, then we can hardcode and some automation can change to that way.

Em seg., 5 de ago. de 2024 às 07:54, jian he <jian.universality@gmail.com>
escreveu:

[commitId_link1, commitId_link2]: Change functions to use a safe
search_path during maintenance operations (Jeff Davis)

I don't like that prefix dirtying each item.
I think having just a link after every item would be better.
Firstly because in English we read left to right and
also because we don't need the commit code. So it would be

- Change functions to use a safe search_path during maintenance
operations (Jeff Davis) [link1, link2]

or just a number to it

- Change functions to use a safe search_path during maintenance
operations (Jeff Davis) [1, 2]

regards
Marcos

On 5 Aug 2024, at 13:16, Marcos Pegoraro <marcos@f10.com.br> wrote:

Em seg., 5 de ago. de 2024 às 07:54, jian he <jian.universality@gmail.com <mailto:jian.universality@gmail.com>> escreveu:

[commitId_link1, commitId_link2]: Change functions to use a safe
search_path during maintenance operations (Jeff Davis)

I don't like that prefix dirtying each item.

I too would prefer links at the end, not least since we might have 2 or 3 (or
more) links for an item.

Python also links to the Github issue and not the commit, in our project the
analog to that would be linking to the thread in the mailinglist archive as
well as the commit. For us linking to the commit is probably preferrable since
it will link to the thread but the thread often wont link to the commit (like a
Github issue will). Maybe icons for code/emailthread can be used to make it
clear what the link is, and cut down to horizontal space required?

--
Daniel Gustafsson

On Mon, Aug 5, 2024, at 10:33 AM, Daniel Gustafsson wrote:

On 5 Aug 2024, at 13:16, Marcos Pegoraro <marcos@f10.com.br> wrote:

Em seg., 5 de ago. de 2024 às 07:54, jian he <jian.universality@gmail.com> escreveu:

[commitId_link1, commitId_link2]: Change functions to use a safe
search_path during maintenance operations (Jeff Davis)

I don't like that prefix dirtying each item.

I too would prefer links at the end, not least since we might have 2 or 3 (or
more) links for an item.

+1.

Python also links to the Github issue and not the commit, in our project the
analog to that would be linking to the thread in the mailinglist archive as
well as the commit. For us linking to the commit is probably preferrable since
it will link to the thread but the thread often wont link to the commit (like a
Github issue will). Maybe icons for code/emailthread can be used to make it
clear what the link is, and cut down to horizontal space required?

PgBouncer adds the PR number at the end [1]https://www.pgbouncer.org/changelog.html too. I generally prefer this style
because you read the message and after that if you want additional detail you
can click on the link at the end.

I don't know if linking to the thread is a good idea. We have long long threads
that cannot provide quick information for the reader. Since we don't have a
concept of every commit has a CF entry, IMO we should use only commits here. The
commit message points to the discussion so it is a good start point if you want
to research about that specific feature.

If one commit is not sufficient for that item, we can always add multiple
commits as we usually do in the release notes comments.

[1]: https://www.pgbouncer.org/changelog.html

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

hi.

please check the attached patch file and apply against
b18b3a8150dbb150124bd345e000d6dc92f3d6dd.

you can also preview the attached screenshot to see the rendered effect.

Em ter., 6 de ago. de 2024 às 04:30, jian he <jian.universality@gmail.com>
escreveu:

you can also preview the attached screenshot to see the rendered effect.

Loved, except that the commit id does not help too much, so I don't think
we need it.
I think a numbered link would be better.

- Change functions to use a safe search_path during maintenance
operations (Jeff Davis) [1, 2]

And your patch has an additional space before comma before second, third
links, [1 , 2] instead of [1, 2]

regards
Marcos

On Tue, Aug 6, 2024 at 9:57 AM Marcos Pegoraro <marcos@f10.com.br> wrote:

Loved, except that the commit id does not help too much, so I don't think we need it.
I think a numbered link would be better.

I think the commit ID is quite useful. If you're using git, you can do
"git show $COMMITID". If you're using the web, you can go to
https://git.postgresql.org/pg/commitdiff/$COMMITID

Big -1 for removing the commit ID.

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

On Tue, Aug 6, 2024, at 11:02 AM, Robert Haas wrote:

On Tue, Aug 6, 2024 at 9:57 AM Marcos Pegoraro <marcos@f10.com.br> wrote:

Loved, except that the commit id does not help too much, so I don't think we need it.
I think a numbered link would be better.

I think the commit ID is quite useful. If you're using git, you can do
"git show $COMMITID". If you're using the web, you can go to
https://git.postgresql.org/pg/commitdiff/$COMMITID

Big -1 for removing the commit ID.

Agree. Numbers mean nothing in this context. You are searching for detailed
information about the referred feature. A visual information (commit hash)
provides a context that you will find the source code modifications for that
feature.

Talking about the patch, do we want to rely on an external resource? I suggest
that we use a postgresql.org subdomain. It can point to

https://git.postgresql.org/gitweb/?p=postgresql.git;a=commit;h=$COMMIT

or even better use a rewrite rule to define a user-friendly URL (and probably a
mechanism to hide the gitweb URL) like

https://www.postgresql.org/commit/da4017a694d

and the short version that we usually use for the mailing list.

https://postgr.es/c/da4017a694d

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

Hi,

On 2024-08-06 12:02:59 -0300, Euler Taveira wrote:

Talking about the patch, do we want to rely on an external resource? I suggest
that we use a postgresql.org subdomain. It can point to

https://git.postgresql.org/gitweb/?p=postgresql.git;a=commit;h=$COMMIT

I wonder if we should make that a configurable base domain? We have a few
other variables in the sgml that can optionally be set.

Greetings,

Andres Freund

On Tue, Aug 6, 2024 at 11:12 PM Andres Freund <andres@anarazel.de> wrote:

Hi,

On 2024-08-06 12:02:59 -0300, Euler Taveira wrote:

Talking about the patch, do we want to rely on an external resource? I suggest
that we use a postgresql.org subdomain. It can point to

https://git.postgresql.org/gitweb/?p=postgresql.git;a=commit;h=$COMMIT

I wonder if we should make that a configurable base domain? We have a few
other variables in the sgml that can optionally be set.

Thanks for the tip.

adding the following line to postgres.sgml saved me.
+<!ENTITY commit_baseurl "https://postgr.es/c/&quot;&gt;

if people think https://postgr.es/c/da4017a694d no good
we have
https://git.postgresql.org/gitweb/?p=postgresql.git;a=commit;h=da4017a694d
and
https://git.postgresql.org/cgit/postgresql.git/commit/?id=da4017a694d

now we don't need to repeat the url prefix in release-17.sgml.
it is not configurable though.