Horton

Re: An improved README experience for PostgreSQL

Nathan Bossart <nathandbossart@gmail.com>

View thread
From: Nathan Bossart <nathandbossart@gmail.com>
To: Peter Eisentraut <peter@eisentraut.org>
Cc: Andrew Atkinson <andyatkinson@gmail.com>, 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-05-14T15:54:48Z
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 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 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 too
>> blunt?  That there are too many files?  Something else?
> 
> I mean the all-caps file names, cluttering up the top-level directory.

It looks like we could also put these files in .github/ or docs/ to avoid
the clutter.

>> > 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 the intent of my patch.  There might be a few others that we could
>> use, but I figured we could start with the low-hanging fruit that would
>> have the most impact on the GitHub experience.
> 
> 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 they will apply to all
> repositories under the organization.  This is explained at the above link.

Oh, I apologize, my brain skipped over the word "organization" in your
message.

> However, I don't think these files are actually that useful.  People can go
> to the web site to find out about things about the PostgreSQL community.  We
> don't need to add bunch of $X.md files that just say, essentially, got to
> postgresql.org/$X.

That's a reasonable stance.  I think the main argument in favor of these
extra files is to make things a tad more accessible to folks who are
accustomed to using GitHub when contributing to open-source projects, but
you're right that this information is already pretty easy to find.

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