Re: An improved README experience for PostgreSQL

On 15.05.24 21:34, Nathan Bossart wrote: On Wed, May 15, 2024 at 07:23:19AM +0200, Peter Eisentraut wrote: I think for CONTRIBUTING.md, a better link would be . WFM This patch version looks good to me.

Re: An improved README experience for PostgreSQL

On Wed, May 15, 2024 at 07:23:19AM +0200, Peter Eisentraut wrote: > I think for CONTRIBUTING.md, a better link would be > . WFM -- Nathan Bossart Amazon Web Services: https://aws.amazon.com >From 74de0e89bea2802bf699397837ebf77252a0e06b Mon Sep 17 00:00:00

Re: An improved README experience for PostgreSQL

On 14.05.24 19:33, Nathan Bossart wrote: On Tue, May 14, 2024 at 06:12:26PM +0200, Alvaro Herrera wrote: On 2024-May-14, Tom Lane wrote: I don't have a position on whether we want these additional files or not; but if we do, I think the best answer is to stick 'em under .github/ where they

Re: An improved README experience for PostgreSQL

On Tue, May 14, 2024 at 06:12:26PM +0200, Alvaro Herrera wrote: > On 2024-May-14, Tom Lane wrote: > >> I don't have a position on whether we want >> these additional files or not; but if we do, I think the best answer >> is to stick 'em under .github/ where they are out of the way but yet >>

Re: An improved README experience for PostgreSQL

On 2024-May-14, Tom Lane wrote: > I don't have a position on whether we want > these additional files or not; but if we do, I think the best answer > is to stick 'em under .github/ where they are out of the way but yet > updatable by any committer. +1 for .github/, that was my first reaction as

Re: An improved README experience for PostgreSQL

Nathan Bossart writes: > On Tue, May 14, 2024 at 10:05:01AM +0200, Peter Eisentraut wrote: >> My point is, in order to get that enhanced GitHub experience, you don't >> actually have to commit these files into the individual source code >> repository. You can add them to the organization and

Re: An improved README experience for PostgreSQL

On Tue, May 14, 2024 at 10:05:01AM +0200, Peter Eisentraut wrote: > On 13.05.24 17:26, Nathan Bossart wrote: >> On Sun, May 12, 2024 at 05:17:42PM +0200, Peter Eisentraut wrote: >> > I don't know, I find these files kind of "yelling". It's fine to have a >> > couple, but now it's getting a bit

Re: An improved README experience for PostgreSQL

On 13.05.24 17:26, Nathan Bossart wrote: On Sun, May 12, 2024 at 05:17:42PM +0200, Peter Eisentraut wrote: I don't know, I find these files kind of "yelling". It's fine to have a couple, but now it's getting a bit much, and there are more that could be added. I'm not sure what you mean by

Re: An improved README experience for PostgreSQL

On 13.05.24 17:43, Alvaro Herrera wrote: On 2024-May-13, Nathan Bossart wrote: If we want to enhance the GitHub experience, we can also add these files to the organization instead:

Re: An improved README experience for PostgreSQL

On Mon, May 13, 2024 at 05:43:45PM +0200, Alvaro Herrera wrote: > Can't we add these two lines per topic to the README.md? That would be fine with me, too. The multiple-files approach is perhaps a bit more tailored to GitHub, but there's something to be said for keeping this information

Re: An improved README experience for PostgreSQL

On 2024-May-13, Nathan Bossart wrote: > > If we want to enhance the GitHub experience, we can also add these files to > > the organization instead: > > https://docs.github.com/en/communities/setting-up-your-project-for-healthy-contributions/creating-a-default-community-health-file > > This was

Re: An improved README experience for PostgreSQL

On Sun, May 12, 2024 at 05:17:42PM +0200, Peter Eisentraut wrote: > I don't know, I find these files kind of "yelling". It's fine to have a > couple, but now it's getting a bit much, and there are more that could be > added. I'm not sure what you mean by this. Do you mean that the contents are

Re: An improved README experience for PostgreSQL

On 17.04.24 04:36, Nathan Bossart wrote: On Wed, Feb 28, 2024 at 02:21:49PM -0600, Nathan Bossart wrote: I see many projects have files like SECURITY.md, CODE_OF_CONDUCT.md, and CONTRIBUTING.md, and I think it would be relatively easy to add content to each of those for PostgreSQL, even if they

Re: An improved README experience for PostgreSQL

On Wed, Feb 28, 2024 at 02:21:49PM -0600, Nathan Bossart wrote: > I see many projects have files like SECURITY.md, CODE_OF_CONDUCT.md, and > CONTRIBUTING.md, and I think it would be relatively easy to add content to > each of those for PostgreSQL, even if they just link elsewhere. Here's a first

Re: An improved README experience for PostgreSQL

On Thu, Mar 21, 2024 at 10:24:12AM -0700, Andres Freund wrote: > I was out while this was proposed and committed. Just wanted to say: Thanks! > It was high time that we added this... Definitely. I hope we are able to build on this in the near future. -- Nathan Bossart Amazon Web Services:

Re: An improved README experience for PostgreSQL

On 2024-02-28 14:59:16 -0600, Nathan Bossart wrote: > On Wed, Feb 28, 2024 at 02:21:49PM -0600, Nathan Bossart wrote: > > On Wed, Feb 28, 2024 at 02:07:34PM -0600, Andrew Atkinson wrote: > >> I agree that starting with the direct conversion is reasonable. Markdown > >> "modernizes" the file using

Re: An improved README experience for PostgreSQL

On Thu, Mar 21, 2024 at 03:24:17PM +0100, Daniel Gustafsson wrote: >> On 21 Mar 2024, at 15:11, Nathan Bossart wrote: >> I added that to maintain the line break that was in the non-Markdown >> version. I'd rather match the style of the following paragraph (patch >> attached) than mess with

Re: An improved README experience for PostgreSQL

> On 21 Mar 2024, at 15:11, Nathan Bossart wrote: > > On Thu, Mar 21, 2024 at 02:42:27PM +0100, Peter Eisentraut wrote: >> The committed README.md contains trailing whitespace on one line: >> >> General documentation about this version of PostgreSQL can be found at:$ >>

Re: An improved README experience for PostgreSQL

On Thu, Mar 21, 2024 at 02:42:27PM +0100, Peter Eisentraut wrote: > The committed README.md contains trailing whitespace on one line: > > General documentation about this version of PostgreSQL can be found at:$ > -https://www.postgresql.org/docs/devel/$ >

Re: An improved README experience for PostgreSQL

On Wed, Feb 28, 2024 at 11:55 AM David E. Wheeler wrote: > > IME the keys to decent-looking Markdown are: > > 1. Wrapping lines to a legible width (76-80 chars) > 2. Link references rather than inline links +1 on Markdown including David's suggestions above. Agree that without proper

Re: An improved README experience for PostgreSQL

On 28.02.24 20:30, Nathan Bossart wrote: On Wed, Feb 28, 2024 at 01:08:03PM -0600, Nathan Bossart wrote: -PostgreSQL Database Management System -= +# PostgreSQL Database Management System This change can be omitted, which makes the conversion even simpler.

Re: An improved README experience for PostgreSQL

Looks good! Presentation of Markdown file as HTML on mirrors I know of: https://github.com/postgres/postgres/blob/master/README.md https://gitlab.com/postgres/postgres/-/blob/master/README.md On Wed, Feb 28, 2024 at 2:59 PM Nathan Bossart wrote: > On Wed, Feb 28, 2024 at 02:21:49PM -0600,

Re: An improved README experience for PostgreSQL

On Wed, Feb 28, 2024 at 02:21:49PM -0600, Nathan Bossart wrote: > On Wed, Feb 28, 2024 at 02:07:34PM -0600, Andrew Atkinson wrote: >> I agree that starting with the direct conversion is reasonable. Markdown >> "modernizes" the file using a popular plain text file format that's >> renderable. > >

Re: An improved README experience for PostgreSQL

On Wed, Feb 28, 2024 at 02:07:34PM -0600, Andrew Atkinson wrote: > I've grabbed Nathan's patch, and pushed it to GitHub simply to preview the > rendered Markdown there. This isn't intended to be reviewed, this is just > for anyone else that's interested in easily seeing the HTML version of the >

Re: An improved README experience for PostgreSQL

On 2/28/24 14:36, Tom Lane wrote: Nathan Bossart writes: On Wed, Feb 28, 2024 at 01:08:03PM -0600, Nathan Bossart wrote: -PostgreSQL Database Management System -= +# PostgreSQL Database Management System This change can be omitted, which makes the

Re: An improved README experience for PostgreSQL

> On 28 Feb 2024, at 20:36, Tom Lane wrote: > > Nathan Bossart writes: >> On Wed, Feb 28, 2024 at 01:08:03PM -0600, Nathan Bossart wrote: >>> -PostgreSQL Database Management System >>> -= >>> +# PostgreSQL Database Management System > >> This change can be

Re: An improved README experience for PostgreSQL

I've grabbed Nathan's patch, and pushed it to GitHub simply to preview the rendered Markdown there. This isn't intended to be reviewed, this is just for anyone else that's interested in easily seeing the HTML version of the Markdown file compared with the earlier one. Nathan's direct conversion:

Re: An improved README experience for PostgreSQL

Nathan Bossart writes: > On Wed, Feb 28, 2024 at 01:08:03PM -0600, Nathan Bossart wrote: >> -PostgreSQL Database Management System >> -= >> +# PostgreSQL Database Management System > This change can be omitted, which makes the conversion even simpler. That's

Re: An improved README experience for PostgreSQL

On Wed, Feb 28, 2024 at 01:08:03PM -0600, Nathan Bossart wrote: > -PostgreSQL Database Management System > -= > +# PostgreSQL Database Management System This change can be omitted, which makes the conversion even simpler. -- Nathan Bossart Amazon Web

Re: An improved README experience for PostgreSQL

On Wed, Feb 28, 2024 at 01:54:59PM -0500, David E. Wheeler wrote: > On Feb 28, 2024, at 1:51 PM, Alvaro Herrera wrote: >> *IF* people don't go overboard, yes. I agree, but let's keep an eye so >> that it doesn't become an unreadable mess. I've seen some really >> horrible markdown files that

Re: An improved README experience for PostgreSQL

> On 28 Feb 2024, at 19:51, Alvaro Herrera wrote: > > On 2024-Feb-28, Joe Conway wrote: > >> Markdown is pretty readable as text, I'm not sure why we need both. > > *IF* people don't go overboard, yes. I agree, but let's keep an eye so > that it doesn't become an unreadable mess. I've seen

Re: An improved README experience for PostgreSQL

On Feb 28, 2024, at 1:51 PM, Alvaro Herrera wrote: > *IF* people don't go overboard, yes. I agree, but let's keep an eye so > that it doesn't become an unreadable mess. I've seen some really > horrible markdown files that I'm sure most of you would object to. Markdown++ IME the keys to

Re: An improved README experience for PostgreSQL

On 2024-Feb-28, Joe Conway wrote: > Markdown is pretty readable as text, I'm not sure why we need both. *IF* people don't go overboard, yes. I agree, but let's keep an eye so that it doesn't become an unreadable mess. I've seen some really horrible markdown files that I'm sure most of you

Re: An improved README experience for PostgreSQL

On 2/28/24 12:25, Daniel Gustafsson wrote: On 28 Feb 2024, at 18:02, Nathan Bossart wrote: On Wed, Feb 28, 2024 at 02:46:11PM +0100, Daniel Gustafsson wrote: On 26 Feb 2024, at 21:30, Tom Lane wrote: Nathan Bossart writes: I think this would be nice. If the Markdown version is reasonably

Re: An improved README experience for PostgreSQL

> On 28 Feb 2024, at 18:02, Nathan Bossart wrote: > > On Wed, Feb 28, 2024 at 02:46:11PM +0100, Daniel Gustafsson wrote: >>> On 26 Feb 2024, at 21:30, Tom Lane wrote: >>> Nathan Bossart writes: I think this would be nice. If the Markdown version is reasonably readable as plain-text,

Re: An improved README experience for PostgreSQL

Nathan Bossart writes: > Sorry, my suggestion wasn't meant to imply that I have any strong concerns > about maintaining two README files. If we can automate generating one or > the other, that'd be great, but I don't see that as a prerequisite to > adding a Markdown version. Agreed, and I'd go

Re: An improved README experience for PostgreSQL

On Wed, Feb 28, 2024 at 09:56:57AM -0500, Greg Sabino Mullane wrote: > +1 on the general idea. Maybe make that COPYRIGHT link go to an absolute > URI, like all the other links, in case this file gets copied somewhere? > Perhaps point it to https://www.postgresql.org/about/licence/ I suspect there

Re: An improved README experience for PostgreSQL

On Wed, Feb 28, 2024 at 02:46:11PM +0100, Daniel Gustafsson wrote: >> On 26 Feb 2024, at 21:30, Tom Lane wrote: >> Nathan Bossart writes: >>> I think this would be nice. If the Markdown version is reasonably readable >>> as plain-text, maybe we could avoid maintaining two READMEs files, too.

Re: An improved README experience for PostgreSQL

+1 on the general idea. Maybe make that COPYRIGHT link go to an absolute URI, like all the other links, in case this file gets copied somewhere? Perhaps point it to https://www.postgresql.org/about/licence/ Cheers, Greg

Re: An improved README experience for PostgreSQL

> On 26 Feb 2024, at 21:30, Tom Lane wrote: > > Nathan Bossart writes: >> I think this would be nice. If the Markdown version is reasonably readable >> as plain-text, maybe we could avoid maintaining two READMEs files, too. >> But overall, +1 to modernizing the README a bit. > > Per past

Re: An improved README experience for PostgreSQL

Thanks for the feedback Nathan and Tom. Samay also suggested adding the patch. I've added a .patch with the file for consideration. On Mon, Feb 26, 2024 at 2:30 PM Tom Lane wrote: > Nathan Bossart writes: > > I think this would be nice. If the Markdown version is reasonably > readable > > as

Re: An improved README experience for PostgreSQL

Nathan Bossart writes: > I think this would be nice. If the Markdown version is reasonably readable > as plain-text, maybe we could avoid maintaining two READMEs files, too. > But overall, +1 to modernizing the README a bit. Per past track record, we change the top-level README only once every

Re: An improved README experience for PostgreSQL

On Mon, Feb 26, 2024 at 11:31:19AM -0600, Andrew Atkinson wrote: > Hello Hackers. We’re proposing an improved README for PostgreSQL that > includes more helpful links for prospective PostgreSQL contributors and has > a nicer presentation. > > Although development does not take place on GitHub or

An improved README experience for PostgreSQL

Hello Hackers. We’re proposing an improved README for PostgreSQL that includes more helpful links for prospective PostgreSQL contributors and has a nicer presentation. Although development does not take place on GitHub or GitLab for PostgreSQL, many developers might view the PostgreSQL source