Date: Wed, 28 May 2025 18:46:18 -0400
From: Bruce Momjian <bruce@momjian.us>
To: Joe Conway <mail@joeconway.com>
Cc: =?utf-8?Q?=C3=81lvaro?= Herrera <alvherre@kurilemu.de>,
	Nazir Bilal Yavuz <byavuz81@gmail.com>,
	PostgreSQL-development <pgsql-hackers@lists.postgresql.org>,
	Thomas Munro <thomas.munro@gmail.com>
Subject: Re: PG 18 release notes draft committed
Message-ID: <aDeSOswKY5ALdAbK@momjian.us>
References: <aCyUrG9vu1eDo26b@momjian.us>
 <202505230754.fsspbpqhybqt@alvherre.pgsql>
 <aDB8fjawTe679ZCa@momjian.us>
 <03b04188-02e2-4bd8-b65b-18c3e1cc40c4@joeconway.com>
 <aDYuXN8gG_oQQD71@momjian.us>
 <74750dd6-d2aa-4876-8c30-d241c1273f4e@joeconway.com>
MIME-Version: 1.0
Content-Type: text/plain; charset=utf-8
Content-Disposition: inline
Content-Transfer-Encoding: 8bit
In-Reply-To: <74750dd6-d2aa-4876-8c30-d241c1273f4e@joeconway.com>
Archived-At: 
 <https://www.postgresql.org/message-id/aDeSOswKY5ALdAbK%40momjian.us>
Precedence: bulk

On Wed, May 28, 2025 at 02:54:29PM -0400, Joe Conway wrote:
> On 5/27/25 17:27, Bruce Momjian wrote:
> > On Mon, May 26, 2025 at 10:20:08AM -0400, Joe Conway wrote:
> > > On 5/23/25 09:47, Bruce Momjian wrote:
> > > > On Fri, May 23, 2025 at 09:54:54AM +0200, Álvaro Herrera wrote:
> > > > > I also think that showing an XML-ish format of a commit message is
> > > > > unhelpful, not to mention hard to read.  Showing a few actual examples
> > > > > would be better.
> > > > > Agreed, but the XML came from Joe Conway so I am hesitant to
> > > remove it
> > > > myself without feedback from him.
> > > 
> > > 
> > > I am not married to it, but I would say that I find pure examples
> > > confusing/ambiguous. To me at least the XML-ish specification is easier to
> > > understand.
> > > 
> > > Perhaps both the specification as-is and one or two examples added?
> > 
> > Yeah, I think some people like syntax, others like examples.
> 
> What do you think about providing links into the archives for good
> representative log messages rather than making up a contrived example and/or
> copy/pasting them into the wiki page itself?

Sure, we can just link to:

	https://www.postgresql.org/list/pgsql-committers/

and they can choose any recent commit.

> Also, looking at the wiki page, my inclination would be to add an "Examples"
> section at the bottom of the wiki page -- does that work or do you think it
> ought to go just under the "General layout" syntax section?

Sure, makes sense.

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

  Do not let urgent matters crowd out time for investment in the future.