Horton

Re: An improved README experience for PostgreSQL

Nathan Bossart <nathandbossart@gmail.com>

View thread
From: Nathan Bossart <nathandbossart@gmail.com>
To: Andrew Atkinson <andyatkinson@gmail.com>
Cc: Tom Lane <tgl@sss.pgh.pa.us>, "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:21:49Z
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.

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

Thanks.  I'll commit this shortly.

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

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.

-- 
Nathan Bossart
Amazon Web Services: https://aws.amazon.com