Thread: 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
releasenotes to see exactly what I'll get when updated I see lots of unexplained features. Just because release notes
doesnot 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:

    https://www.postgresql.org/message-id/1129530.1681317832@sss.pgh.pa.us

--
Daniel Gustafsson

> 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

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

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.

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.

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?

hi.

please check the attached patch file and apply against
b18b3a8150dbb150124bd345e000d6dc92f3d6dd.

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

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 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.

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/">


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.

On Thu, Aug 8, 2024 at 8:51 PM Marcos Pegoraro <marcos@f10.com.br> wrote:
>
> Em qui., 8 de ago. de 2024 às 00:11, jian he <jian.universality@gmail.com> escreveu:
>>
>>
>> adding the following line to postgres.sgml saved me.
>> +<!ENTITY commit_baseurl "https://postgr.es/c/">
>
>
> Comma at end of line of these should be removed
> <ulink url="&commit_baseurl;165d581f1"> [165d581f1] </ulink>,
> <ulink url="&commit_baseurl;6dbb49026"> [6dbb49026] </ulink>,
>
> Maybe those items which have lots of commits would be strange
> A space before commas on next links I think should be removed because an item like this
> <ulink url="&commit_baseurl;c951e9042"> [c951e9042] </ulink>,

please check attached.

On Fri, Aug 9, 2024 at 8:43 PM Marcos Pegoraro <marcos@f10.com.br> wrote:
>
> I still think this way would be better

> +       Sawada, John Naylor). [
> +       <ulink url="&commit_baseurl;ee1b30f12">ee1b30f12</ulink>,
> +       <ulink url="&commit_baseurl;30e144287">30e144287</ulink>,
> +       <ulink url="&commit_baseurl;667e65aac">667e65aac</ulink>,
> +       <ulink url="&commit_baseurl;6dbb49026">6dbb49026</ulink>]
> instead of this
> +       Sawada, John Naylor).
> +       <ulink url="&commit_baseurl;ee1b30f12"> [ee1b30f12]</ulink>,
> +       <ulink url="&commit_baseurl;30e144287"> [30e144287]</ulink>,
> +       <ulink url="&commit_baseurl;667e65aac"> [667e65aac]</ulink>,
> +       <ulink url="&commit_baseurl;6dbb49026"> [6dbb49026]</ulink>
>

as your wish.

On Fri, Jul 26, 2024 at 10:11:22AM -0400, Tom Lane 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.

Yes, some kind of popup is what I remember.  Looking at the HTML output
for the docs, the SGML comments don't appear the HTML, so I think we
need to write a Perl or shell script to match all the SGML <listitem>
comment text with the HTML <li> text, and insert tooltip text with links
for every one of them.  Should I work on this?

-- 
  Bruce Momjian  <bruce@momjian.us>        https://momjian.us
  EDB                                      https://enterprisedb.com

  Only you can decide what is important to you.

Marcos Pegoraro <marcos@f10.com.br> writes:
> Well, a process which does this automatically would be cool, but a
> modified version of release notes for version 17 was done manually and
> seems fine.
> So, why not commit this version and later for version 18 then create this
> process ?

I'd prefer to see this implemented in the website based on our
existing markup practices.  That way it would work for quite a
few years' worth of existing release notes, not only future ones.

            regards, tom lane

On Fri, Aug 23, 2024 at 11:26:30AM +0800, jian he wrote:
> do you mean this thread [1]? but the output is the attached image.png,
> which looks more invasive.
> also that does not link to git commit url.
> 
> or do you mean automate the process, like add
> <a href="commit_url">commit</a>
> automatically? using perl script, and the output is the same as [2]
> 
> 
> or a popup like this kind of
> https://stackoverflow.com/a/47821773/15603477
> but this thread, people seem to want to display the git commit as is,
> no need for extra action?

Sure, we can display it however people want.

-- 
  Bruce Momjian  <bruce@momjian.us>        https://momjian.us
  EDB                                      https://enterprisedb.com

  Only you can decide what is important to you.

On 22.08.24 19:27, Tom Lane wrote:
> Marcos Pegoraro <marcos@f10.com.br> writes:
>> Well, a process which does this automatically would be cool, but a
>> modified version of release notes for version 17 was done manually and
>> seems fine.
>> So, why not commit this version and later for version 18 then create this
>> process ?
> 
> I'd prefer to see this implemented in the website based on our
> existing markup practices.  That way it would work for quite a
> few years' worth of existing release notes, not only future ones.

Seems difficult, because the annotations right now are in XML comments. 
You'd need to put them in some kind of markup around it, like from

<!--
Author: Bruce Momjian <bruce@momjian.us>
2023-09-26 [15d5d7405] pgrowlocks: change lock mode output labels for 
consiste
-->

     <listitem>
      <para>
      Change <application><xref linkend="pgrowlocks"/></application>
      lock mode output labels (Bruce Momjian)
      </para>
     </listitem>

to

     <listitem>
      <para>
      Change <application><xref linkend="pgrowlocks"/></application>
      lock mode output labels (Bruce Momjian)
      </para>
<literallayout role="something">
Author: Bruce Momjian <bruce@momjian.us>
2023-09-26 [15d5d7405] pgrowlocks: change lock mode output labels for 
consiste
</literallayout>
     </listitem>

The fact that the comment is before the main item might also be a bit 
tricky to sort out.

On Wed, Aug 28, 2024 at 10:47:32AM +0200, Peter Eisentraut wrote:
> <!--
> Author: Bruce Momjian <bruce@momjian.us>
> 2023-09-26 [15d5d7405] pgrowlocks: change lock mode output labels for
> consiste
> -->
> 
>     <listitem>
>      <para>
>      Change <application><xref linkend="pgrowlocks"/></application>
>      lock mode output labels (Bruce Momjian)
>      </para>
>     </listitem>
> 
> to
> 
>     <listitem>
>      <para>
>      Change <application><xref linkend="pgrowlocks"/></application>
>      lock mode output labels (Bruce Momjian)
>      </para>
> <literallayout role="something">
> Author: Bruce Momjian <bruce@momjian.us>
> 2023-09-26 [15d5d7405] pgrowlocks: change lock mode output labels for
> consiste
> </literallayout>
>     </listitem>
> 
> The fact that the comment is before the main item might also be a bit tricky
> to sort out.

I think we can just assume any XML comment in that file that has Author:
on line line and an ISO date on the next is a commit comment.

-- 
  Bruce Momjian  <bruce@momjian.us>        https://momjian.us
  EDB                                      https://enterprisedb.com

  Only you can decide what is important to you.

On Thu, 22 Aug 2024 at 21:34, Marcos Pegoraro <marcos@f10.com.br> wrote:
> I understand your point, and agree with that for previous releases, but since we have a month only for version 17,
willthis process work properly until that date ?
 
> I think a release notes is more read as soon as it is available than other months, isn't it ?
> And this feature is just a HTML page, so if it's done manually or automatically, from the reader point of view it'll
beexactly the same.
 

Big +1 to this. It would definitely be great if we would have these
commit links for previous release notes. But the PG17 GA release is
probably happening in 19 days on September 26th. I feel like we should
focus on getting the manual improvements from Jian He merged,
otherwise we'll end up with release notes for PG17 on release day that
are significantly less useful than they could have been. Let's not
make perfect the enemy of good here.

On Sat, Sep  7, 2024 at 10:12:00AM +0800, jian he wrote:
> On Sat, Sep 7, 2024 at 6:30 AM Jelte Fennema-Nio <postgres@jeltef.nl> wrote:
> >
> > On Thu, 22 Aug 2024 at 21:34, Marcos Pegoraro <marcos@f10.com.br> wrote:
> > > I understand your point, and agree with that for previous releases, but since we have a month only for version
17,will this process work properly until that date ?
 
> > > I think a release notes is more read as soon as it is available than other months, isn't it ?
> > > And this feature is just a HTML page, so if it's done manually or automatically, from the reader point of view
it'llbe exactly the same.
 
> >
> > Big +1 to this. It would definitely be great if we would have these
> > commit links for previous release notes. But the PG17 GA release is
> > probably happening in 19 days on September 26th. I feel like we should
> > focus on getting the manual improvements from Jian He merged,
> > otherwise we'll end up with release notes for PG17 on release day that
> > are significantly less useful than they could have been. Let's not
> > make perfect the enemy of good here.
> >
> 
> hi. Thanks for your interest.
> patch updated.
> 
> 
> I have proof-read release-17.sgml again,
> making sure the commit url's commit is the same as
> release-17.sgml comment's git commit.

I will write a script to do this, but I am not sure I will have it done
by the time we release Postgres 17.

-- 
  Bruce Momjian  <bruce@momjian.us>        https://momjian.us
  EDB                                      https://enterprisedb.com

  When a patient asks the doctor, "Am I going to die?", he means 
  "Am I going to die soon?"

On Wed, Sep 11, 2024 at 10:16:04AM -0400, Bruce Momjian wrote:
> On Sat, Sep  7, 2024 at 10:12:00AM +0800, jian he wrote:
> > On Sat, Sep 7, 2024 at 6:30 AM Jelte Fennema-Nio <postgres@jeltef.nl> wrote:
> > >
> > > On Thu, 22 Aug 2024 at 21:34, Marcos Pegoraro <marcos@f10.com.br> wrote:
> > > > I understand your point, and agree with that for previous releases, but since we have a month only for version
17,will this process work properly until that date ?
 
> > > > I think a release notes is more read as soon as it is available than other months, isn't it ?
> > > > And this feature is just a HTML page, so if it's done manually or automatically, from the reader point of view
it'llbe exactly the same.
 
> > >
> > > Big +1 to this. It would definitely be great if we would have these
> > > commit links for previous release notes. But the PG17 GA release is
> > > probably happening in 19 days on September 26th. I feel like we should
> > > focus on getting the manual improvements from Jian He merged,
> > > otherwise we'll end up with release notes for PG17 on release day that
> > > are significantly less useful than they could have been. Let's not
> > > make perfect the enemy of good here.
> > >
> > 
> > hi. Thanks for your interest.
> > patch updated.
> > 
> > 
> > I have proof-read release-17.sgml again,
> > making sure the commit url's commit is the same as
> > release-17.sgml comment's git commit.
> 
> I will write a script to do this, but I am not sure I will have it done
> by the time we release Postgres 17.

I now see you have done the entire PG 17 release notes, so I can just
use your patch and work on a script later.  I will apply your patch
soon.

-- 
  Bruce Momjian  <bruce@momjian.us>        https://momjian.us
  EDB                                      https://enterprisedb.com

  When a patient asks the doctor, "Am I going to die?", he means 
  "Am I going to die soon?"

On Sat, Sep  7, 2024 at 10:12:00AM +0800, jian he wrote:
> On Sat, Sep 7, 2024 at 6:30 AM Jelte Fennema-Nio <postgres@jeltef.nl> wrote:
> >
> > On Thu, 22 Aug 2024 at 21:34, Marcos Pegoraro <marcos@f10.com.br> wrote:
> > > I understand your point, and agree with that for previous releases, but since we have a month only for version
17,will this process work properly until that date ?
 
> > > I think a release notes is more read as soon as it is available than other months, isn't it ?
> > > And this feature is just a HTML page, so if it's done manually or automatically, from the reader point of view
it'llbe exactly the same.
 
> >
> > Big +1 to this. It would definitely be great if we would have these
> > commit links for previous release notes. But the PG17 GA release is
> > probably happening in 19 days on September 26th. I feel like we should
> > focus on getting the manual improvements from Jian He merged,
> > otherwise we'll end up with release notes for PG17 on release day that
> > are significantly less useful than they could have been. Let's not
> > make perfect the enemy of good here.
> >
> 
> hi. Thanks for your interest.
> patch updated.

I applied this patch to PG 17.  You can see the results at:

    https://momjian.us/pgsql_docs/release-17.html

The community doc build only shows the master branch, which is PG 18,
and the PG 17 docs are only built before the release.

I changed the patch to use the section symbol "§" instead of showing
the hashes.  The hashes seemed too detailed.  Does anyone see a better
symbol to use from here?

    http://www.zipcon.net/~swhite/docs/computers/browsers/entities_page.html

I think we are limited to the HTML entities listed on that page. I also
removed the brackets and the period you added at the end of the text. 

> there are at least several typos in sgml comment.
> like
> 
> <!--
> Author: Tom Lane <tgl@sss.pgh.pa.us>
> 2023-11-17 [f7816aec2] Extract column statistics from CTE references, if possib
> Author: Tom Lane <tgl@sss.pgh.pa.us>
> 2024-03-26 [a65724dfa] Propagate pathkeys from CTEs up to the outer query.
> -->
> 
> here should be "possible".

Yes, the git output is cut off at a certain length --- I don't think we
should change it.

-- 
  Bruce Momjian  <bruce@momjian.us>        https://momjian.us
  EDB                                      https://enterprisedb.com

  When a patient asks the doctor, "Am I going to die?", he means 
  "Am I going to die soon?"

On Fri, Sep 13, 2024 at 06:41:30PM -0300, Marcos Pegoraro wrote:
> Em sex., 13 de set. de 2024 às 13:39, Bruce Momjian <bruce@momjian.us>
> escreveu:
> 
>     I changed the patch to use the section symbol "§" instead of showing
>     the hashes.  The hashes seemed too detailed.  Does anyone see a better
>     symbol to use from here?
> 
> 
> Robert and others liked commit hashes because you can do "git show $COMMITID"

We have to consider the small percentage of people who will want to do
that vs the number of people reading the release notes.  I think it is
reasonable to require someone to click on the link to see the hash.

> On my first email I used numbered links, because when you have several links
> you know which one was clicked lastly

True, and the section symbol makes it even less clear.

> And brackets were useful to separate description, authors and commit links of
> that item. 

Right, but without hashes, the section mark is clear.

> Anyway, one way or another, I'm ok because it's committed.

We can easily change it if we decide we want something else.

-- 
  Bruce Momjian  <bruce@momjian.us>        https://momjian.us
  EDB                                      https://enterprisedb.com

  When a patient asks the doctor, "Am I going to die?", he means 
  "Am I going to die soon?"

On Fri, Sep 13, 2024 at 05:54:31PM -0400, Bruce Momjian wrote:
> On Fri, Sep 13, 2024 at 06:41:30PM -0300, Marcos Pegoraro wrote:
> > Em sex., 13 de set. de 2024 às 13:39, Bruce Momjian <bruce@momjian.us>
> > escreveu:
> > 
> >     I changed the patch to use the section symbol "§" instead of showing
> >     the hashes.  The hashes seemed too detailed.  Does anyone see a better
> >     symbol to use from here?
> > 
> > 
> > Robert and others liked commit hashes because you can do "git show $COMMITID"
> 
> We have to consider the small percentage of people who will want to do
> that vs the number of people reading the release notes.  I think it is
> reasonable to require someone to click on the link to see the hash.

Thinking some more, I think that displaying the hashes would give the
average reader the impression that the release notes are too complex for
them to understand.

-- 
  Bruce Momjian  <bruce@momjian.us>        https://momjian.us
  EDB                                      https://enterprisedb.com

  When a patient asks the doctor, "Am I going to die?", he means 
  "Am I going to die soon?"

On Sat, Sep 14, 2024 at 08:37:31PM -0400, Bruce Momjian wrote:
> On Fri, Sep 13, 2024 at 12:39:28PM -0400, Bruce Momjian wrote:
> > I applied this patch to PG 17.  You can see the results at:
> > 
> >     https://momjian.us/pgsql_docs/release-17.html
> > 
> > The community doc build only shows the master branch, which is PG 18,
> > and the PG 17 docs are only built before the release.
> > 
> > I changed the patch to use the section symbol "§" instead of showing
> > the hashes.  The hashes seemed too detailed.  Does anyone see a better
> > symbol to use from here?
> > 
> >     http://www.zipcon.net/~swhite/docs/computers/browsers/entities_page.html
> > 
> > I think we are limited to the HTML entities listed on that page. I also
> > removed the brackets and the period you added at the end of the text. 
> 
> I wrote the attached Perl script that automatically adds commit links. 
> I tested it against PG 12-17 and the results were good. I plan to add
> this script to all branches and run it on all branch release notes in a
> few days.

I have added the Perl script, added instructions on when to run the
script, and ran the script on all release notes back to PG 12.  I think
we can call this item closed.

-- 
  Bruce Momjian  <bruce@momjian.us>        https://momjian.us
  EDB                                      https://enterprisedb.com

  When a patient asks the doctor, "Am I going to die?", he means 
  "Am I going to die soon?"

On Mon, Sep 16, 2024 at 03:42:22PM -0300, Marcos Pegoraro wrote:
> Em seg., 16 de set. de 2024 às 15:15, Bruce Momjian <bruce@momjian.us>
> escreveu:
> 
>     > > I changed the patch to use the section symbol "§" instead of showing
>     > > the hashes.  The hashes seemed too detailed.  Does anyone see a better
>     > > symbol to use from here
> 
> 
> Well, I think section symbol is not a good choice for all commit links
> 
> Add backend support for injection points (Michael Paquier) § § § §
> Add backend support for injection points (Michael Paquier) 1 2 3 4
> Add backend support for injection points (Michael Paquier) Commit 1 2 3 4
> 
> I don't know which one is better, but I don't think the section symbol is the
> best. 

We could try:

   Add backend support for injection points (Michael Paquier) §1 §2 §3 §4

and maybe only add numbers if there is more than one commit.

-- 
  Bruce Momjian  <bruce@momjian.us>        https://momjian.us
  EDB                                      https://enterprisedb.com

  When a patient asks the doctor, "Am I going to die?", he means 
  "Am I going to die soon?"

On 2024-Sep-16, Bruce Momjian wrote:

> We could try:
> 
>    Add backend support for injection points (Michael Paquier) §1 §2 §3 §4
> 
> and maybe only add numbers if there is more than one commit.

Well, this reads like references to sections 1, 2, 3 and 4, but they
aren't that, and probably such sections don't even exist.  I think the
use of the section symbol is misleading and typographically wrong.
https://www.monotype.com/resources/punctuation-series-section-sign


Maybe it would work to use numbers in square brackets instead:

    Add backend support for injection points (Michael Paquier) [1] [2] [3] [4]

Maybe use the word "commit" for the first one, which would make it
clearer what the links are about:

    Add backend support for injection points (Michael Paquier) [commit 1] [2] [3] [4]

and if there's only one, say just "[commit]".

-- 
Álvaro Herrera         PostgreSQL Developer  —  https://www.EnterpriseDB.com/

On Tue, 17 Sept 2024 at 10:12, Alvaro Herrera <alvherre@alvh.no-ip.org> wrote:
> Maybe it would work to use numbers in square brackets instead:
>
>     Add backend support for injection points (Michael Paquier) [1] [2] [3] [4]

Another option would be to add them in superscript using the <sup>
html tag (or even using some unicode stuff):

    Add backend support for injection points (Michael Paquier)<sup>1,
2, 3, 4</sup>

So similar to footnotes in a sense, i.e. if you want details click on
the small numbers

Bruce Momjian <bruce@momjian.us> writes:
> On Tue, Sep 17, 2024 at 03:29:54PM -0300, Marcos Pegoraro wrote:
>> Em ter., 17 de set. de 2024 às 05:12, Alvaro Herrera <alvherre@alvh.no-ip.org>
>>> Add backend support for injection points (Michael Paquier) [commit 1] [2]

> I think trying to add text to each item is both redundant and confusing,

Also very clutter-y.  I'm not convinced that any of this is a good
idea that will stand the test of time: I estimate that approximately
0.01% of people who read the release notes will want these links.
But if we keep it I think the annotations have to be very unobtrusive.

(Has anyone looked at the PDF rendering of this?  It seems rather
unfortunate to me.)

            regards, tom lane

On Tue, Sep 17, 2024 at 08:22:41PM -0400, Tom Lane wrote:
> Bruce Momjian <bruce@momjian.us> writes:
> > On Tue, Sep 17, 2024 at 03:29:54PM -0300, Marcos Pegoraro wrote:
> >> Em ter., 17 de set. de 2024 às 05:12, Alvaro Herrera <alvherre@alvh.no-ip.org>
> >>> Add backend support for injection points (Michael Paquier) [commit 1] [2]
> 
> > I think trying to add text to each item is both redundant and confusing,
> 
> Also very clutter-y.  I'm not convinced that any of this is a good
> idea that will stand the test of time: I estimate that approximately
> 0.01% of people who read the release notes will want these links.

Yes, I think 0.01% is accurate.

> But if we keep it I think the annotations have to be very unobtrusive.

I very much agree.

> (Has anyone looked at the PDF rendering of this?  It seems rather
> unfortunate to me.)

Oh, not good.  See my build:

    https://momjian.us/expire/postgres-US.pdf#page=2890

Those numbers are there because all external links get numbers that
start a 1 at the top of the section and increment for every link --- I
have no idea why.  You can see that acronyms that have external links
have the same numbering:

    https://momjian.us/expire/postgres-US.pdf#page=3150

I wonder if we should remove the numbers in both cases.

-- 
  Bruce Momjian  <bruce@momjian.us>        https://momjian.us
  EDB                                      https://enterprisedb.com

  When a patient asks the doctor, "Am I going to die?", he means 
  "Am I going to die soon?"

On 18.09.24 02:54, Bruce Momjian wrote:
> On Tue, Sep 17, 2024 at 08:22:41PM -0400, Tom Lane wrote:
>> Bruce Momjian <bruce@momjian.us> writes:
>>> On Tue, Sep 17, 2024 at 03:29:54PM -0300, Marcos Pegoraro wrote:
>>>> Em ter., 17 de set. de 2024 às 05:12, Alvaro Herrera <alvherre@alvh.no-ip.org>
>>>>> Add backend support for injection points (Michael Paquier) [commit 1] [2]
>>
>>> I think trying to add text to each item is both redundant and confusing,
>>
>> Also very clutter-y.  I'm not convinced that any of this is a good
>> idea that will stand the test of time: I estimate that approximately
>> 0.01% of people who read the release notes will want these links.
> 
> Yes, I think 0.01% is accurate.
> 
>> But if we keep it I think the annotations have to be very unobtrusive.
> 
> I very much agree.
> 
>> (Has anyone looked at the PDF rendering of this?  It seems rather
>> unfortunate to me.)
> 
> Oh, not good.  See my build:
> 
>     https://momjian.us/expire/postgres-US.pdf#page=2890
> 
> Those numbers are there because all external links get numbers that
> start a 1 at the top of the section and increment for every link --- I
> have no idea why.  You can see that acronyms that have external links
> have the same numbering:
> 
>     https://momjian.us/expire/postgres-US.pdf#page=3150
> 
> I wonder if we should remove the numbers in both cases.

Maybe this shouldn't be done between RC1 and GA.  This is clearly a more 
complex topic that should go through a proper review and testing cycle.

On 2024-Sep-17, Bruce Momjian wrote:

> I think trying to add text to each item is both redundant and confusing,
> because I am guessing that many people will not even know what a commit
> is, and will be confused by clicking on the link.

Uh, I 100% disagree that Postgres users reading the release notes would
not know what a commit is.  I think 99.9%(*) of them would know that(**).
Does a small fraction _care_ about the commit that each release note
item is related to?  Sure, it's a small audience, and I think the
current implementation far too intrusive for the PDF form to be
acceptable, given that the audience is so small.  But the audience is
not an empty set, so it's acceptable to have something nicer-looking.

IMO we should be looking at a more surgical approach to implement this,
perhaps using a custom SGML tag and some custom XSLT code to process
such tags that adds links the way we want, rather than generic <ulink>
tags.  Or maybe <ulink> is OK if we add some class to it that XSLT knows
to process differently than generic ulinks, like func_table_entry and
catalog_table_entry.

I tend to agree with Peter that this came in way too late, and looking
at the PDF I think it should be reverted for now.


-- 
Álvaro Herrera               48°01'N 7°57'E  —  https://www.EnterpriseDB.com/
"No tengo por qué estar de acuerdo con lo que pienso"
                             (Carlos Caszeli)

(*) Not a scientifically-determined number

(**) You said "many people will not even know", and I said 99.9% will
know.  Maybe we're both right, and if we accept both things to be true,
then we conclude that 0.01% of Postgres users is many people.  Whatever
else results from this thread, I think that's a fantastic conclusion.

On Wed, 18 Sept 2024 at 02:55, Bruce Momjian <bruce@momjian.us> wrote:
> > Also very clutter-y.  I'm not convinced that any of this is a good
> > idea that will stand the test of time: I estimate that approximately
> > 0.01% of people who read the release notes will want these links.
>
> Yes, I think 0.01% is accurate.

I think that is a severe underestimation. People that read the release
notes obviously read it because they want to know what changed. But
the release notes are very terse (on purpose, and with good reason),
and people likely want a bit more details on some of the items that
they are particularly interested in. These links allow people to
easily find details on those items. They might not care about the
actual code from the commit, but the commit message is very likely
useful to them.

On Wed, 18 Sept 2024 at 11:26, Alvaro Herrera <alvherre@alvh.no-ip.org> wrote:
>
> On 2024-Sep-17, Bruce Momjian wrote:
>
> > I think trying to add text to each item is both redundant and confusing,
> > because I am guessing that many people will not even know what a commit
> > is, and will be confused by clicking on the link.
>
> Uh, I 100% disagree that Postgres users reading the release notes would
> not know what a commit is.

+1, IMO it seems completely reasonable to assume that anyone
interested enough in postgres to read the release notes also knows
what a commit is.

> IMO we should be looking at a more surgical approach to implement this,
> perhaps using a custom SGML tag and some custom XSLT code to process
> such tags that adds links the way we want, rather than generic <ulink>
> tags.  Or maybe <ulink> is OK if we add some class to it that XSLT knows
> to process differently than generic ulinks, like func_table_entry and
> catalog_table_entry.

Is it easy to just remove/hide the links completely from the PDF? I
doubt many people read the release notes by going to Appendix E in the
PDF anyway.

It seems a shame to remove those links from the HTML view where they
look acceptable and which most people will use, just because they look
bad in the pdf. And honestly, they don't even look that terrible in
the PDF imo.

On 2024-Sep-18, Jelte Fennema-Nio wrote:

> It seems a shame to remove those links from the HTML view where they
> look acceptable and which most people will use, just because they look
> bad in the pdf. And honestly, they don't even look that terrible in
> the PDF imo.

Eh, someday maybe we should just get rid of the PDF build of the docs.
It's given a ton of trouble over the years, it is not terribly
convenient, and we don't even know whether it has any users or not.

-- 
Álvaro Herrera               48°01'N 7°57'E  —  https://www.EnterpriseDB.com/
"At least to kernel hackers, who really are human, despite occasional
rumors to the contrary" (LWN.net)

On Wed, Sep 18, 2024 at 8:55 AM Bruce Momjian <bruce@momjian.us> wrote:
>
> On Tue, Sep 17, 2024 at 08:22:41PM -0400, Tom Lane wrote:
> > Bruce Momjian <bruce@momjian.us> writes:
> > > On Tue, Sep 17, 2024 at 03:29:54PM -0300, Marcos Pegoraro wrote:
> > >> Em ter., 17 de set. de 2024 às 05:12, Alvaro Herrera <alvherre@alvh.no-ip.org>
> > >>> Add backend support for injection points (Michael Paquier) [commit 1] [2]
> >
> > > I think trying to add text to each item is both redundant and confusing,
> >
> > Also very clutter-y.  I'm not convinced that any of this is a good
> > idea that will stand the test of time: I estimate that approximately
> > 0.01% of people who read the release notes will want these links.
>
> Yes, I think 0.01% is accurate.
>
> > But if we keep it I think the annotations have to be very unobtrusive.
>
> I very much agree.
>

google "PostgreSQL 16: What's New?"
In private browsing mode
shows we have at least 15 English blogs explaining new features.

I think including the git commit info, can help people quickly write
these kinds of blogs.
Without it, writing blog and sql examples would be harder or require
you to know more about postgres internal.

On Wed, 18 Sept 2024 at 13:38, Marcos Pegoraro <marcos@f10.com.br> wrote:
>> Maybe this shouldn't be done between RC1 and GA.  This is clearly a more
>> complex topic that should go through a proper review and testing cycle.
>
> I think this is just a question of decision, not reviewing or testing.
> And I'm sure there will be more people reading Release Notes now, in September and October, than in January or April.

+1. Also, IMHO the links even in their current simple form of "§ § §
§" are a huge net-positive on the release notes. So yes, I'm sure we
can format them more clearly with some bikeshedding, but removing them
completely seems like an overreaction to me.

Jelte Fennema-Nio <postgres@jeltef.nl> writes:
> On Wed, 18 Sept 2024 at 02:55, Bruce Momjian <bruce@momjian.us> wrote:
>>> Also very clutter-y.  I'm not convinced that any of this is a good
>>> idea that will stand the test of time: I estimate that approximately
>>> 0.01% of people who read the release notes will want these links.

>> Yes, I think 0.01% is accurate.

> I think that is a severe underestimation.

I'm sure a very large fraction of the people commenting on this thread
would like to have these links.  But we are by no means representative
of the average Postgres user.

            regards, tom lane

Marcos Pegoraro <marcos@f10.com.br> writes:
> Em qua., 18 de set. de 2024 às 06:02, Peter Eisentraut <peter@eisentraut.org>
> escreveu:
>> Maybe this shouldn't be done between RC1 and GA.  This is clearly a more
>> complex topic that should go through a proper review and testing cycle.

> I think this is just a question of decision, not reviewing or testing.

I'd say the opposite: the thing we lack is exactly testing, in the
sense of how non-hackers will react to this.  Nonetheless, I'm not
upset about trying to do it now.  We will get more feedback about
major-release notes than minor-release notes.  And the key point
is that it's okay to consider this experimental.  Unlike say a SQL
feature, there are no compatibility concerns that put a premium on
getting it right the first time.  We can adjust the annotations or
give up on them without much cost.

            regards, tom lane

I have some good news.  Many of you did not like the use of the section
symbol as a marker for links from the release notes items to the commit
details.

I thought we were restricted to Latin-1 characters, because those are
the only characters that the PDF output supports.

However, since we decided not to have the commit detail links in the PDF
output, it is actually safe to use _any_ Unicode character as the commit
detail link.

Does anyone have suggestions on a character?  We can use 🔗 (looks
like an angled section symbol (§)).  There is no HTML entity for 🔗
so we would have to represent it as a literal UTF8 character.

I can easily modify the Perl script and re-run it.

-- 
  Bruce Momjian  <bruce@momjian.us>        https://momjian.us
  EDB                                      https://enterprisedb.com

  When a patient asks the doctor, "Am I going to die?", he means 
  "Am I going to die soon?"

On Tue, Oct 15, 2024 at 01:25:07PM -0400, Greg Sabino Mullane wrote:
> On Tue, Oct 15, 2024 at 12:25 PM Bruce Momjian <bruce@momjian.us> wrote:
> 
>     Does anyone have suggestions on a character?
> 
> 
> I poked around with a bunch and the scroll character seems to be the most
> appropriate and visibly pleasing.

Uh, yeah, scroll looks nice, 📜, but I have never seen it used.  I would
rather use 🔗 since it is more common.

> See my posted-before-yours blog post :)
> 
> https://www.crunchydata.com/blog/enhanced-postgres-release-notes

Yeah, I checked on conflicting blogs before I wrote mine but by the time
I posted, your was already done.  ;-)

-- 
  Bruce Momjian  <bruce@momjian.us>        https://momjian.us
  EDB                                      https://enterprisedb.com

  When a patient asks the doctor, "Am I going to die?", he means 
  "Am I going to die soon?"

Bruce Momjian <bruce@momjian.us> writes:
> I thought we were restricted to Latin-1 characters, because those are
> the only characters that the PDF output supports.

> However, since we decided not to have the commit detail links in the PDF
> output, it is actually safe to use _any_ Unicode character as the commit
> detail link.

I don't think that gives us carte blanche to use anything whatsoever.
It has to be something that will be present in the fonts available on
Joe Average's web browser, and I think that means it had better be
something that has been around a long time.  Sticking to LATIN-1 is
not such a bad idea from this perspective.  (As an example, the
slightly old version of Emacs I'm using is failing to render
Ÿ”— at all.)

Also, at least when looking at your message in Safari, Ÿ”—
is just enormous in comparison to §.  I think it would be quite
visually distracting, especially for release notes with several links.

            regards, tom lane

On Tue, Oct 15, 2024 at 02:01:05PM -0400, Tom Lane wrote:
> Bruce Momjian <bruce@momjian.us> writes:
> > I thought we were restricted to Latin-1 characters, because those are
> > the only characters that the PDF output supports.
> 
> > However, since we decided not to have the commit detail links in the PDF
> > output, it is actually safe to use _any_ Unicode character as the commit
> > detail link.
> 
> I don't think that gives us carte blanche to use anything whatsoever.
> It has to be something that will be present in the fonts available on
> Joe Average's web browser, and I think that means it had better be
> something that has been around a long time.  Sticking to LATIN-1 is
> not such a bad idea from this perspective.  (As an example, the
> slightly old version of Emacs I'm using is failing to render
> Ÿ”— at all.)
> 
> Also, at least when looking at your message in Safari, Ÿ”—
> is just enormous in comparison to §.  I think it would be quite
> visually distracting, especially for release notes with several links.

Oh, good point. I did see the link 🔗 as a double-width character. 
Let's keep §.

-- 
  Bruce Momjian  <bruce@momjian.us>        https://momjian.us
  EDB                                      https://enterprisedb.com

  When a patient asks the doctor, "Am I going to die?", he means 
  "Am I going to die soon?"

On Tue, Oct 15, 2024 at 11:01 AM Tom Lane <tgl@sss.pgh.pa.us> wrote:
>
> Sticking to LATIN-1 is not such a bad idea from this perspective.

Maybe plus-minus (±), to represent the diff?

--Jacob

On Tue, Oct 15, 2024 at 11:04:50AM -0700, Jacob Champion wrote:
> On Tue, Oct 15, 2024 at 11:01 AM Tom Lane <tgl@sss.pgh.pa.us> wrote:
> >
> > Sticking to LATIN-1 is not such a bad idea from this perspective.
> 
> Maybe plus-minus (±), to represent the diff?

Uh, that might make sense to people who vie diffs often, but not the
average reader of the document.

-- 
  Bruce Momjian  <bruce@momjian.us>        https://momjian.us
  EDB                                      https://enterprisedb.com

  When a patient asks the doctor, "Am I going to die?", he means 
  "Am I going to die soon?"

Bruce Momjian <bruce@momjian.us> writes:
> On Tue, Oct 15, 2024 at 11:04:50AM -0700, Jacob Champion wrote:
>> Maybe plus-minus (±), to represent the diff?

> Uh, that might make sense to people who vie diffs often, but not the
> average reader of the document.

Well, the § symbol hasn't got that much mnemonic value either.

However ... wasn't one of the arguments for § that there's some
other project(s) already using it for this purpose?  If so, I think
we'd be better off joining the crowd.

            regards, tom lane

On Tue, Oct 15, 2024 at 02:21:31PM -0400, Tom Lane wrote:
> Bruce Momjian <bruce@momjian.us> writes:
> > On Tue, Oct 15, 2024 at 11:04:50AM -0700, Jacob Champion wrote:
> >> Maybe plus-minus (±), to represent the diff?
> 
> > Uh, that might make sense to people who vie diffs often, but not the
> > average reader of the document.
> 
> Well, the § symbol hasn't got that much mnemonic value either.
> 
> However ... wasn't one of the arguments for § that there's some
> other project(s) already using it for this purpose?  If so, I think
> we'd be better off joining the crowd.

I don't remember anyone else using it, but its purpose to point to a
place with more detail makes logical sense.

-- 
  Bruce Momjian  <bruce@momjian.us>        https://momjian.us
  EDB                                      https://enterprisedb.com

  When a patient asks the doctor, "Am I going to die?", he means 
  "Am I going to die soon?"

On Tue, Oct 15, 2024 at 02:23:15PM -0400, Bruce Momjian wrote:
> On Tue, Oct 15, 2024 at 02:21:31PM -0400, Tom Lane wrote:
>> Bruce Momjian <bruce@momjian.us> writes:
>> > On Tue, Oct 15, 2024 at 11:04:50AM -0700, Jacob Champion wrote:
>> >> Maybe plus-minus (±), to represent the diff?
>> 
>> > Uh, that might make sense to people who vie diffs often, but not the
>> > average reader of the document.
>> 
>> Well, the § symbol hasn't got that much mnemonic value either.
>> 
>> However ... wasn't one of the arguments for § that there's some
>> other project(s) already using it for this purpose?  If so, I think
>> we'd be better off joining the crowd.
> 
> I don't remember anyone else using it, but its purpose to point to a
> place with more detail makes logical sense.

Another option could be delta (Δ or δ).  That's not LATIN-1, but I'd
imagine it's relatively well supported at this point.

-- 
nathan