Horton

Re: An improved README experience for PostgreSQL

Andrew Atkinson <andyatkinson@gmail.com>

View thread
From: Andrew Atkinson <andyatkinson@gmail.com>
To: Tom Lane <tgl@sss.pgh.pa.us>
Cc: Nathan Bossart <nathandbossart@gmail.com>, "David E. Wheeler" <david@justatheory.com>, Alvaro Herrera <alvherre@alvh.no-ip.org>, Joe Conway <mail@joeconway.com>, Daniel Gustafsson <daniel@yesql.se>, PostgreSQL Hackers <pgsql-hackers@postgresql.org>, Samay Sharma <samay@tembo.io>
Date: 2024-02-28T20:07:34Z
Lists: pgsql-hackers

Commits

Same data as JSON: GET /api/v1/messages/:b64id/commits the thread's linked commits as JSON, with link sources. API reference →

  1. Add CODE_OF_CONDUCT.md, CONTRIBUTING.md, and SECURITY.md.

  2. Revise the style of a paragraph in README.md.

  3. Convert README to Markdown.

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:
https://github.com/postgres/postgres/blob/9c0f1dd350ee29ad3ade2816c4338b7ca5186bba/README.md

Original email version with more sections and content:
https://github.com/andyatkinson/postgres/blob/e88138765750b6f7898089b4016641eee01bf616/README.md

I agree that starting with the direct conversion is reasonable. Markdown
"modernizes" the file using a popular plain text file format that's
renderable.

However, I also think it would be cool to get some input on what the most
useful 2-3 content items are for new developers and make any additions
possible there. In writing this, I had an idea to ask about whether this
topic could be covered as an upcoming PostgreSQL community blog post
series. In theory, we could gather a variety of perspectives that way. That
could make it less subjective if we see several people independently
suggesting a particular wiki page for example, for inclusion in the README.
I'll pursue that outside the mailing list and report back!



On Wed, Feb 28, 2024 at 1:36 PM Tom Lane <tgl@sss.pgh.pa.us> wrote:

> Nathan Bossart <nathandbossart@gmail.com> 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 a pretty convincing proof-of-concept.  Let's just do this,
> and then make sure to keep the file legible as plain text.
>
>                         regards, tom lane
>