Horton

Thread

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.

  1. An improved README experience for PostgreSQL

    Andrew Atkinson <andyatkinson@gmail.com> — 2024-02-26T17:31:19Z

    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 code using one
of those mirrors (I do myself). Since both support Markdown files, a
Markdown version of the README (as README.md) gets presentational benefits
that I think are helpful.

For a head-to-head comparison of what that looks like, review the current
README and a proposed README.md version below:

Current version:

https://github.com/andyatkinson/postgres/blob/master/README

Markdown README.md version on GitHub:

https://github.com/andyatkinson/postgres/blob/e88138765750b6f7898089b4016641eee01bf616/README.md


---- Feedback Requested ----

Samay Sharma are both interested in the initial developer experience for
PostgreSQL. We had a chat about the role the README plays in that, while
it's a small role, we thought this might be a place to start.


We'd love some feedback.

Prospective contributors need to know about compilation, the mailing lists,
and how the commitfest events work. This information is scattered around on
wiki pages, but we're wondering if more could be brought into the README
and whether that would help?

If you do check out the new file, we'd love to know whether you think
there's useful additions, or there's content that's missing.

If there's any kind of feedback or consensus on this thread, I'm happy to
create and send a patch.

Thanks for taking a look!

Andrew Atkinson w/ reviews from Samay Sharma

  2. Re: An improved README experience for PostgreSQL

    Nathan Bossart <nathandbossart@gmail.com> — 2024-02-26T18:30:18Z

    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 GitLab for
> PostgreSQL, many developers might view the PostgreSQL source code using one
> of those mirrors (I do myself). Since both support Markdown files, a
> Markdown version of the README (as README.md) gets presentational benefits
> that I think are helpful.

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.

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

  3. Re: An improved README experience for PostgreSQL

    Tom Lane <tgl@sss.pgh.pa.us> — 2024-02-26T20:30:36Z

    Nathan Bossart <nathandbossart@gmail.com> 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
three years or so, so I doubt it'd be too painful to maintain two
versions of it.

Having said that, any proposal for this ought to be submitted as
a patch, rather than expecting people to go digging around on
some other repo.

			regards, tom lane

  4. Re: An improved README experience for PostgreSQL

    Andrew Atkinson <andyatkinson@gmail.com> — 2024-02-26T20:40:05Z

    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 <tgl@sss.pgh.pa.us> wrote:

> Nathan Bossart <nathandbossart@gmail.com> 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
> three years or so, so I doubt it'd be too painful to maintain two
> versions of it.
>
> Having said that, any proposal for this ought to be submitted as
> a patch, rather than expecting people to go digging around on
> some other repo.
>
>                         regards, tom lane
>

  5. Re: An improved README experience for PostgreSQL

    Daniel Gustafsson <daniel@yesql.se> — 2024-02-28T13:46:11Z

    > On 26 Feb 2024, at 21:30, Tom Lane <tgl@sss.pgh.pa.us> wrote:
> 
> Nathan Bossart <nathandbossart@gmail.com> 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
> three years or so, so I doubt it'd be too painful to maintain two
> versions of it.

It wont be, and we kind of already have two since there is another similar
README displayed at https://www.postgresql.org/ftp/.  That being said, a
majority of those reading the README will likely be new developers accustomed
to Markdown (or doing so via interfaces such as Github) so going to Markdown
might not be a bad idea.  We can also render a plain text version with pandoc
for release builds should we want to.

--
Daniel Gustafsson

  6. Re: An improved README experience for PostgreSQL

    Greg Sabino Mullane <htamfids@gmail.com> — 2024-02-28T14:56:57Z

    +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

  7. Re: An improved README experience for PostgreSQL

    Nathan Bossart <nathandbossart@gmail.com> — 2024-02-28T17:02:37Z

    On Wed, Feb 28, 2024 at 02:46:11PM +0100, Daniel Gustafsson wrote:
>> On 26 Feb 2024, at 21:30, Tom Lane <tgl@sss.pgh.pa.us> wrote:
>> Nathan Bossart <nathandbossart@gmail.com> 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
>> three years or so, so I doubt it'd be too painful to maintain two
>> versions of it.
> 
> It wont be, and we kind of already have two since there is another similar
> README displayed at https://www.postgresql.org/ftp/.  That being said, a
> majority of those reading the README will likely be new developers accustomed
> to Markdown (or doing so via interfaces such as Github) so going to Markdown
> might not be a bad idea.  We can also render a plain text version with pandoc
> for release builds should we want to.

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.

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

  8. Re: An improved README experience for PostgreSQL

    Nathan Bossart <nathandbossart@gmail.com> — 2024-02-28T17:10:48Z

    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 will be quite a bit of discussion about what to add to the
README, which is great, but I think we should establish an order of
operations here.  We could either add suggested content to the README and
then create an identical Markdown version, or we could create a Markdown
version and add content to both afterwards.  The former has my vote since
it seems like it would require less churn.  In any case, I think it would
be useful to keep the Markdown effort separate from the content effort
somehow (e.g., separate threads).

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

  9. Re: An improved README experience for PostgreSQL

    Tom Lane <tgl@sss.pgh.pa.us> — 2024-02-28T17:17:04Z

    Nathan Bossart <nathandbossart@gmail.com> 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 so far as to say that adding automation now
would be investing work that might well go to waste.  When and
if we get annoyed by the manual labor involved in maintaining
two copies, it'd be time to put work into automating it.

			regards, tom lane

  10. Re: An improved README experience for PostgreSQL

    Daniel Gustafsson <daniel@yesql.se> — 2024-02-28T17:25:32Z

    > On 28 Feb 2024, at 18:02, Nathan Bossart <nathandbossart@gmail.com> wrote:
> 
> On Wed, Feb 28, 2024 at 02:46:11PM +0100, Daniel Gustafsson wrote:
>>> On 26 Feb 2024, at 21:30, Tom Lane <tgl@sss.pgh.pa.us> wrote:
>>> Nathan Bossart <nathandbossart@gmail.com> 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
>>> three years or so, so I doubt it'd be too painful to maintain two
>>> versions of it.
>> 
>> It wont be, and we kind of already have two since there is another similar
>> README displayed at https://www.postgresql.org/ftp/.  That being said, a
>> majority of those reading the README will likely be new developers accustomed
>> to Markdown (or doing so via interfaces such as Github) so going to Markdown
>> might not be a bad idea.  We can also render a plain text version with pandoc
>> for release builds should we want to.
> 
> 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 didn't say we should do it but rather that we can do it based on
the toolchain we already have.  Personally I think just having a Markdown
version is enough, it's become the de facto standard for such documentation for
good reasons.

--
Daniel Gustafsson

  11. Re: An improved README experience for PostgreSQL

    Joe Conway <mail@joeconway.com> — 2024-02-28T17:43:24Z

    On 2/28/24 12:25, Daniel Gustafsson wrote:
>> On 28 Feb 2024, at 18:02, Nathan Bossart <nathandbossart@gmail.com> wrote:
>> 
>> On Wed, Feb 28, 2024 at 02:46:11PM +0100, Daniel Gustafsson wrote:
>>>> On 26 Feb 2024, at 21:30, Tom Lane <tgl@sss.pgh.pa.us> wrote:
>>>> Nathan Bossart <nathandbossart@gmail.com> 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
>>>> three years or so, so I doubt it'd be too painful to maintain two
>>>> versions of it.
>>> 
>>> It wont be, and we kind of already have two since there is another similar
>>> README displayed at https://www.postgresql.org/ftp/.  That being said, a
>>> majority of those reading the README will likely be new developers accustomed
>>> to Markdown (or doing so via interfaces such as Github) so going to Markdown
>>> might not be a bad idea.  We can also render a plain text version with pandoc
>>> for release builds should we want to.
>> 
>> 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 didn't say we should do it but rather that we can do it based on
> the toolchain we already have.  Personally I think just having a Markdown
> version is enough, it's become the de facto standard for such documentation for
> good reasons.

+1

Markdown is pretty readable as text, I'm not sure why we need both.

-- 
Joe Conway
PostgreSQL Contributors Team
RDS Open Source Databases
Amazon Web Services: https://aws.amazon.com

  12. Re: An improved README experience for PostgreSQL

    Alvaro Herrera <alvherre@alvh.no-ip.org> — 2024-02-28T18:51:02Z

    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 would object to.

-- 
Álvaro Herrera               48°01'N 7°57'E  —  https://www.EnterpriseDB.com/

  13. Re: An improved README experience for PostgreSQL

    David E. Wheeler <david@justatheory.com> — 2024-02-28T18:54:59Z

    On Feb 28, 2024, at 1:51 PM, Alvaro Herrera <alvherre@alvh.no-ip.org> 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 decent-looking Markdown are:

1. Wrapping lines to a legible width (76-80 chars)
2. Link references rather than inline links

I try to follow these for my blog; posts end up looking like this:

https://justatheory.com/2024/02/extension-metadata-typology.text

(Append `.text` to any post to see the raw(ish) Markdown.

Best,

David

  14. Re: An improved README experience for PostgreSQL

    Daniel Gustafsson <daniel@yesql.se> — 2024-02-28T19:07:30Z

    > On 28 Feb 2024, at 19:51, Alvaro Herrera <alvherre@alvh.no-ip.org> 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 some really
> horrible markdown files that I'm sure most of you would object to.

Absolutely, I agree. Considering the lengths we go to to keep our code readable I’m not worried, I expect that a markdown README would end up pretty close to the txt version we have today.

./daniel

  15. Re: An improved README experience for PostgreSQL

    Nathan Bossart <nathandbossart@gmail.com> — 2024-02-28T19:08:03Z

    On Wed, Feb 28, 2024 at 01:54:59PM -0500, David E. Wheeler wrote:
> On Feb 28, 2024, at 1:51 PM, Alvaro Herrera <alvherre@alvh.no-ip.org> 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 decent-looking Markdown are:
> 
> 1. Wrapping lines to a legible width (76-80 chars)
> 2. Link references rather than inline links
> 
> I try to follow these for my blog; posts end up looking like this:
> 
> https://justatheory.com/2024/02/extension-metadata-typology.text
> 
> (Append `.text` to any post to see the raw(ish) Markdown.

Here is what converting the current README to Markdown with no other
content changes might look like.

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

  16. Re: An improved README experience for PostgreSQL

    Nathan Bossart <nathandbossart@gmail.com> — 2024-02-28T19:30:36Z

    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 Services: https://aws.amazon.com

  17. Re: An improved README experience for PostgreSQL

    Tom Lane <tgl@sss.pgh.pa.us> — 2024-02-28T19:36:13Z

    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

  18. Re: An improved README experience for PostgreSQL

    Andrew Atkinson <andyatkinson@gmail.com> — 2024-02-28T20:07:34Z

    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
>

  19. Re: An improved README experience for PostgreSQL

    Daniel Gustafsson <daniel@yesql.se> — 2024-02-28T20:13:56Z

    > On 28 Feb 2024, at 20:36, 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.

+1

--
Daniel Gustafsson

  20. Re: An improved README experience for PostgreSQL

    Joe Conway <mail@joeconway.com> — 2024-02-28T20:17:34Z

    On 2/28/24 14:36, Tom Lane 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.

+1

-- 
Joe Conway
PostgreSQL Contributors Team
RDS Open Source Databases
Amazon Web Services: https://aws.amazon.com

  21. Re: An improved README experience for PostgreSQL

    Nathan Bossart <nathandbossart@gmail.com> — 2024-02-28T20:21:49Z

    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

  22. Re: An improved README experience for PostgreSQL

    Nathan Bossart <nathandbossart@gmail.com> — 2024-02-28T20:59:16Z

    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.
> 
> Thanks.  I'll commit this shortly.

Committed.

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

  23. Re: An improved README experience for PostgreSQL

    Andrew Atkinson <andyatkinson@gmail.com> — 2024-02-28T21:43:27Z

    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 <nathandbossart@gmail.com>
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 a popular plain text file format that's
> >> renderable.
> >
> > Thanks.  I'll commit this shortly.
>
> Committed.
>
> --
> Nathan Bossart
> Amazon Web Services: https://aws.amazon.com
>

  24. Re: An improved README experience for PostgreSQL

    Peter Eisentraut <peter@eisentraut.org> — 2024-03-21T13:42:27Z

    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.

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/$
+<https://www.postgresql.org/docs/devel/>  $

If this is intentional (it could be, since trailing whitespace is 
potentially significant in Markdown), then please add something to 
.gitattributes.  Otherwise, please fix that.

  25. Re: An improved README experience for PostgreSQL

    Roberto Mello <roberto.mello@gmail.com> — 2024-03-21T13:52:38Z

    On Wed, Feb 28, 2024 at 11:55 AM David E. Wheeler <david@justatheory.com>
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 guidelines,
md files can become messy looking.

Roberto

  26. Re: An improved README experience for PostgreSQL

    Nathan Bossart <nathandbossart@gmail.com> — 2024-03-21T14:11:30Z

    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/$
> +<https://www.postgresql.org/docs/devel/>  $
> 
> If this is intentional (it could be, since trailing whitespace is
> potentially significant in Markdown), then please add something to
> .gitattributes.  Otherwise, please fix that.

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

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

  27. Re: An improved README experience for PostgreSQL

    Daniel Gustafsson <daniel@yesql.se> — 2024-03-21T14:24:17Z

    > On 21 Mar 2024, at 15:11, Nathan Bossart <nathandbossart@gmail.com> 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:$
>> -https://www.postgresql.org/docs/devel/$
>> +<https://www.postgresql.org/docs/devel/>  $
>> 
>> If this is intentional (it could be, since trailing whitespace is
>> potentially significant in Markdown), then please add something to
>> .gitattributes.  Otherwise, please fix that.
> 
> 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 .gitattributes.

+1, this looks better IMHO.

--
Daniel Gustafsson

  28. Re: An improved README experience for PostgreSQL

    Nathan Bossart <nathandbossart@gmail.com> — 2024-03-21T15:20:32Z

    On Thu, Mar 21, 2024 at 03:24:17PM +0100, Daniel Gustafsson wrote:
>> On 21 Mar 2024, at 15:11, Nathan Bossart <nathandbossart@gmail.com> 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 .gitattributes.
> 
> +1, this looks better IMHO.

Committed.

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

  29. Re: An improved README experience for PostgreSQL

    Andres Freund <andres@anarazel.de> — 2024-03-21T17:24:12Z

    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 a popular plain text file format that's
> >> renderable.
> > 
> > Thanks.  I'll commit this shortly.
> 
> Committed.

I was out while this was proposed and committed. Just wanted to say: Thanks!
It was high time that we added this...

  30. Re: An improved README experience for PostgreSQL

    Nathan Bossart <nathandbossart@gmail.com> — 2024-03-21T18:39:37Z

    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: https://aws.amazon.com

  31. Re: An improved README experience for PostgreSQL

    Nathan Bossart <nathandbossart@gmail.com> — 2024-04-17T02:36:09Z

    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 attempt at this.  You can see some of the effects of these
files at [0].  More information about these files is available at [1] [2]
[3].

I figured we'd want to keep these pretty bare-bones to avoid duplicating
information that's already available at postgresql.org, but perhaps it's
worth filling them out a bit more.  Anyway, I just wanted to gauge interest
in this stuff.

[0] https://github.com/nathan-bossart/postgres/tree/special-files
[1] https://docs.github.com/en/code-security/getting-started/adding-a-security-policy-to-your-repository
[2] https://docs.github.com/en/communities/setting-up-your-project-for-healthy-contributions/adding-a-code-of-conduct-to-your-project
[3] https://docs.github.com/en/communities/setting-up-your-project-for-healthy-contributions/setting-guidelines-for-repository-contributors

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

  32. Re: An improved README experience for PostgreSQL

    Peter Eisentraut <peter@eisentraut.org> — 2024-05-12T15:17:42Z

    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 just link elsewhere.
> Here's a first attempt at this.  You can see some of the effects of these
> files at [0].  More information about these files is available at [1] [2]
> [3].
> 
> I figured we'd want to keep these pretty bare-bones to avoid duplicating
> information that's already available at postgresql.org, but perhaps it's
> worth filling them out a bit more.  Anyway, I just wanted to gauge interest
> in this stuff.

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.

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

  33. Re: An improved README experience for PostgreSQL

    Nathan Bossart <nathandbossart@gmail.com> — 2024-05-13T15:26:09Z

    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?

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

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

  34. Re: An improved README experience for PostgreSQL

    Alvaro Herrera <alvherre@alvh.no-ip.org> — 2024-05-13T15:43:45Z

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

Can't we add these two lines per topic to the README.md?

-- 
Álvaro Herrera        Breisgau, Deutschland  —  https://www.EnterpriseDB.com/
"No hay hombre que no aspire a la plenitud, es decir,
la suma de experiencias de que un hombre es capaz"

  35. Re: An improved README experience for PostgreSQL

    Nathan Bossart <nathandbossart@gmail.com> — 2024-05-13T15:55:53Z

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

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

  36. Re: An improved README experience for PostgreSQL

    Peter Eisentraut <peter@eisentraut.org> — 2024-05-14T07:55:49Z

    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: 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.
> 
> Can't we add these two lines per topic to the README.md?

The point of these special file names is that GitHub will produce 
special links to them.  If you look at Nathan's tree

https://github.com/nathan-bossart/postgres/tree/special-files

and scroll down to the README display, you will see links for "Code of 
Conduct", "License", and "Security" across the top.

Whether it's worth having these files just to produce these links is the 
debate.

  37. Re: An improved README experience for PostgreSQL

    Peter Eisentraut <peter@eisentraut.org> — 2024-05-14T08:05:01Z

    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.

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

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.

  38. Re: An improved README experience for PostgreSQL

    Nathan Bossart <nathandbossart@gmail.com> — 2024-05-14T15:54:48Z

    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

  39. Re: An improved README experience for PostgreSQL

    Tom Lane <tgl@sss.pgh.pa.us> — 2024-05-14T16:06:17Z

    Nathan Bossart <nathandbossart@gmail.com> 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 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.

FWIW, I'd vote against doing it that way, because then
maintaining/updating those files would only be possible for whoever
owns the github repo.  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.

			regards, tom lane

  40. Re: An improved README experience for PostgreSQL

    Alvaro Herrera <alvherre@alvh.no-ip.org> — 2024-05-14T16:12:26Z

    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 well after reading the
link Peter posted.

-- 
Álvaro Herrera         PostgreSQL Developer  —  https://www.EnterpriseDB.com/
"Los trabajadores menos efectivos son sistematicamente llevados al lugar
donde pueden hacer el menor daño posible: gerencia."  (El principio Dilbert)

  41. Re: An improved README experience for PostgreSQL

    Nathan Bossart <nathandbossart@gmail.com> — 2024-05-14T17:33:21Z

    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
>> updatable by any committer.
> 
> +1 for .github/, that was my first reaction as well after reading the
> link Peter posted.

Here's an updated patch that uses .github/.

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

  42. Re: An improved README experience for PostgreSQL

    Peter Eisentraut <peter@eisentraut.org> — 2024-05-15T05:23:19Z

    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 are out of the way but yet
>>> updatable by any committer.
>>
>> +1 for .github/, that was my first reaction as well after reading the
>> link Peter posted.
> 
> Here's an updated patch that uses .github/.

I'm fine with putting them under .github/.

I think for CONTRIBUTING.md, a better link would be 
<https://www.postgresql.org/developer/>.

  43. Re: An improved README experience for PostgreSQL

    Nathan Bossart <nathandbossart@gmail.com> — 2024-05-15T19:34:09Z

    On Wed, May 15, 2024 at 07:23:19AM +0200, Peter Eisentraut wrote:
> I think for CONTRIBUTING.md, a better link would be
> <https://www.postgresql.org/developer/>.

WFM

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

  44. Re: An improved README experience for PostgreSQL

    Peter Eisentraut <peter@eisentraut.org> — 2024-05-16T10:07:32Z

    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
>> <https://www.postgresql.org/developer/>.
> 
> WFM

This patch version looks good to me.

  45. Re: An improved README experience for PostgreSQL

    Nathan Bossart <nathandbossart@gmail.com> — 2024-06-03T15:10:58Z

    +Andres

On Thu, May 16, 2024 at 12:07:32PM +0200, Peter Eisentraut wrote:
> This patch version looks good to me.

At pgconf.dev, Andres opined that it would be better to put these files in
the top-level directory so that they would be more visible to non-GitHub
users.  I personally don't have any strong opinion on the matter, but I
will note that even though the files I have staged for commit are pretty
bare-bones, I do think we should eventually build on their content so that
they are more than just links to the website.  My goal here is to get
something basic in place so that future discussion can be focused on the
content.

Tom, Alvaro, and Peter have all expressed a preference to use the .github/
directory, so at the moment I still intend to proceed with the v3 patch
unless further discussion changes things.

-- 
nathan

  46. Re: An improved README experience for PostgreSQL

    Nathan Bossart <nathandbossart@gmail.com> — 2024-07-02T18:11:04Z

    On Mon, Jun 03, 2024 at 10:10:58AM -0500, Nathan Bossart wrote:
> Tom, Alvaro, and Peter have all expressed a preference to use the .github/
> directory, so at the moment I still intend to proceed with the v3 patch
> unless further discussion changes things.

Committed.

We could also add a GOVERNANCE.md file that points to the new
https://www.postgresql.org/about/governance/ page, but I couldn't find
where that gets displayed on GitHub, so AFAICT it would just be buried in
.github/.

-- 
nathan

  47. Re: An improved README experience for PostgreSQL

    Tom Lane <tgl@sss.pgh.pa.us> — 2024-07-02T18:15:09Z

    Nathan Bossart <nathandbossart@gmail.com> writes:
> We could also add a GOVERNANCE.md file that points to the new
> https://www.postgresql.org/about/governance/ page, but I couldn't find
> where that gets displayed on GitHub, so AFAICT it would just be buried in
> .github/.

Not much point then.  IMV this subdirectory is just there to provide
things that GitHub displays specially.

			regards, tom lane