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 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
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
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
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:
Show quoted text
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
Attachments:
0001-Adds-modernized-README.md.patchapplication/octet-stream; name=0001-Adds-modernized-README.md.patchDownload
From 3847f3e07ba55c441c7d3432d721ae00d94cc995 Mon Sep 17 00:00:00 2001
From: Andy Atkinson <andyatkinson@gmail.com>
Date: Mon, 26 Feb 2024 14:36:55 -0600
Subject: [PATCH] Adds modernized README.md
Incorporate feedback from Samay
---
README.md | 26 ++++++++++++++++++++++++++
1 file changed, 26 insertions(+)
create mode 100644 README.md
diff --git a/README.md b/README.md
new file mode 100644
index 0000000000..987bd06979
--- /dev/null
+++ b/README.md
@@ -0,0 +1,26 @@
+# PostgreSQL
+[PostgreSQL](https://www.postgresql.org/) is an advanced object-relational database management system
+that supports an extended subset of the SQL standard, including
+transactions, foreign keys, subqueries, triggers, user-defined types
+and functions. This distribution also contains C language bindings.
+
+## Download Binaries
+The latest version of this software, and related software, may be
+obtained at <https://www.postgresql.org/download/>.
+
+## Source Code Contributions and CommitFest
+Follow the instructions in
+[Installation from Source Code](https://www.postgresql.org/docs/current/installation.html)
+to learn how to compile PostgreSQL for your platform.
+
+Changes to PostgreSQL source code are proposed as patches, attached to
+emails that are sent to the [pgsql-hackers](https://www.postgresql.org/list/pgsql-hackers/) mailing list.
+
+During [CommitFest](https://wiki.postgresql.org/wiki/CommitFest) events,
+patches are reviewed and committed to PostgreSQL, for release in a future version.
+
+Read more about making contributions on the
+[So, you want to be a developer?](https://wiki.postgresql.org/wiki/So,_you_want_to_be_a_developer%3F) wiki page.
+
+## Copyright and License
+Copyright and license information can be found in the file [COPYRIGHT](COPYRIGHT).
--
2.43.0
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
+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
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
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
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
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
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
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/
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
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
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 linksI 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
Attachments:
0001-Convert-README-to-Markdown.patchtext/x-diff; charset=us-asciiDownload
From 5d618e3c0e33854d1afe7230b0ca6ad8f0177996 Mon Sep 17 00:00:00 2001
From: Nathan Bossart <nathan@postgresql.org>
Date: Wed, 28 Feb 2024 13:05:39 -0600
Subject: [PATCH 1/1] Convert README to Markdown.
---
README => README.md | 11 +++++------
1 file changed, 5 insertions(+), 6 deletions(-)
rename README => README.md (68%)
diff --git a/README b/README.md
similarity index 68%
rename from README
rename to README.md
index e40e610ccb..dfdf7415a5 100644
--- a/README
+++ b/README.md
@@ -1,5 +1,4 @@
-PostgreSQL Database Management System
-=====================================
+# PostgreSQL Database Management System
This directory contains the source code distribution of the PostgreSQL
database management system.
@@ -12,11 +11,11 @@ and functions. This distribution also contains C language bindings.
Copyright and license information can be found in the file COPYRIGHT.
General documentation about this version of PostgreSQL can be found at:
-https://www.postgresql.org/docs/devel/
+<https://www.postgresql.org/docs/devel/>
In particular, information about building PostgreSQL from the source
code can be found at:
-https://www.postgresql.org/docs/devel/installation.html
+<https://www.postgresql.org/docs/devel/installation.html>
The latest version of this software, and related software, may be
-obtained at https://www.postgresql.org/download/. For more information
-look at our web site located at https://www.postgresql.org/.
+obtained at <https://www.postgresql.org/download/>. For more information
+look at our web site located at <https://www.postgresql.org/>.
--
2.25.1
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
Attachments:
0001-Convert-README-to-Markdown.patchtext/x-diff; charset=us-asciiDownload
From f627354ab3795e17f81fb94fd85f389f72fc79de Mon Sep 17 00:00:00 2001
From: Nathan Bossart <nathan@postgresql.org>
Date: Wed, 28 Feb 2024 13:05:39 -0600
Subject: [PATCH 1/1] Convert README to Markdown.
---
README => README.md | 8 ++++----
1 file changed, 4 insertions(+), 4 deletions(-)
rename README => README.md (75%)
diff --git a/README b/README.md
similarity index 75%
rename from README
rename to README.md
index e40e610ccb..445eb2f2d0 100644
--- a/README
+++ b/README.md
@@ -12,11 +12,11 @@ and functions. This distribution also contains C language bindings.
Copyright and license information can be found in the file COPYRIGHT.
General documentation about this version of PostgreSQL can be found at:
-https://www.postgresql.org/docs/devel/
+<https://www.postgresql.org/docs/devel/>
In particular, information about building PostgreSQL from the source
code can be found at:
-https://www.postgresql.org/docs/devel/installation.html
+<https://www.postgresql.org/docs/devel/installation.html>
The latest version of this software, and related software, may be
-obtained at https://www.postgresql.org/download/. For more information
-look at our web site located at https://www.postgresql.org/.
+obtained at <https://www.postgresql.org/download/>. For more information
+look at our web site located at <https://www.postgresql.org/>.
--
2.25.1
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
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:
Show quoted text
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 SystemThis 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
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 SystemThis 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
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 SystemThis 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
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.mdOriginal email version with more sections and content:
https://github.com/andyatkinson/postgres/blob/e88138765750b6f7898089b4016641eee01bf616/README.mdI 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
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
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:
Show quoted text
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
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 SystemThis 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.
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
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
Attachments:
readme_fix.patchtext/x-diff; charset=us-asciiDownload
diff --git a/README.md b/README.md
index 445eb2f2d0..f6104c038b 100644
--- a/README.md
+++ b/README.md
@@ -11,11 +11,10 @@ and functions. This distribution also contains C language bindings.
Copyright and license information can be found in the file COPYRIGHT.
-General documentation about this version of PostgreSQL can be found at:
-<https://www.postgresql.org/docs/devel/>
-In particular, information about building PostgreSQL from the source
-code can be found at:
-<https://www.postgresql.org/docs/devel/installation.html>
+General documentation about this version of PostgreSQL can be found at
+<https://www.postgresql.org/docs/devel/>. In particular, information
+about building PostgreSQL from the source code can be found at
+<https://www.postgresql.org/docs/devel/installation.html>.
The latest version of this software, and related software, may be
obtained at <https://www.postgresql.org/download/>. For more information
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
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
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...
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
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]https://github.com/nathan-bossart/postgres/tree/special-files. More information about these files is available at [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
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
Attachments:
v1-0001-Add-code-of-conduct-contributing-and-security-fil.patchtext/x-diff; charset=us-asciiDownload
From d2a7f5ae384dde6305571bd7042e6e03846dd1d5 Mon Sep 17 00:00:00 2001
From: Nathan Bossart <nathan@postgresql.org>
Date: Tue, 16 Apr 2024 21:23:52 -0500
Subject: [PATCH v1 1/1] Add code of conduct, contributing, and security files.
---
CODE_OF_CONDUCT.md | 2 ++
CONTRIBUTING.md | 2 ++
SECURITY.md | 2 ++
3 files changed, 6 insertions(+)
create mode 100644 CODE_OF_CONDUCT.md
create mode 100644 CONTRIBUTING.md
create mode 100644 SECURITY.md
diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md
new file mode 100644
index 0000000000..99bb1905d6
--- /dev/null
+++ b/CODE_OF_CONDUCT.md
@@ -0,0 +1,2 @@
+The PostgreSQL code of conduct can be found at
+<https://www.postgresql.org/about/policies/coc/>.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 0000000000..ff93024352
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,2 @@
+For information about contributing to PostgreSQL, see
+<https://wiki.postgresql.org/wiki/Submitting_a_Patch>.
diff --git a/SECURITY.md b/SECURITY.md
new file mode 100644
index 0000000000..ebdbe609db
--- /dev/null
+++ b/SECURITY.md
@@ -0,0 +1,2 @@
+For information about reporting security issues, see
+<https://www.postgresql.org/support/security/>.
--
2.25.1
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
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
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-fileThis 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"
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
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-fileThis 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.
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-fileThis 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.
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-fileThis 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
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
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)
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
Attachments:
v2-0001-Add-code-of-conduct-contributing-and-security-fil.patchtext/x-diff; charset=us-asciiDownload
From d6e27e9acf65bf77c54e2292f6e02590d34adeb6 Mon Sep 17 00:00:00 2001
From: Nathan Bossart <nathan@postgresql.org>
Date: Tue, 16 Apr 2024 21:23:52 -0500
Subject: [PATCH v2 1/1] Add code of conduct, contributing, and security files.
---
.github/CODE_OF_CONDUCT.md | 2 ++
.github/CONTRIBUTING.md | 2 ++
.github/SECURITY.md | 2 ++
3 files changed, 6 insertions(+)
create mode 100644 .github/CODE_OF_CONDUCT.md
create mode 100644 .github/CONTRIBUTING.md
create mode 100644 .github/SECURITY.md
diff --git a/.github/CODE_OF_CONDUCT.md b/.github/CODE_OF_CONDUCT.md
new file mode 100644
index 0000000000..99bb1905d6
--- /dev/null
+++ b/.github/CODE_OF_CONDUCT.md
@@ -0,0 +1,2 @@
+The PostgreSQL code of conduct can be found at
+<https://www.postgresql.org/about/policies/coc/>.
diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md
new file mode 100644
index 0000000000..ff93024352
--- /dev/null
+++ b/.github/CONTRIBUTING.md
@@ -0,0 +1,2 @@
+For information about contributing to PostgreSQL, see
+<https://wiki.postgresql.org/wiki/Submitting_a_Patch>.
diff --git a/.github/SECURITY.md b/.github/SECURITY.md
new file mode 100644
index 0000000000..ebdbe609db
--- /dev/null
+++ b/.github/SECURITY.md
@@ -0,0 +1,2 @@
+For information about reporting security issues, see
+<https://www.postgresql.org/support/security/>.
--
2.25.1
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/>.
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
Attachments:
v3-0001-Add-code-of-conduct-contributing-and-security-fil.patchtext/x-diff; charset=us-asciiDownload
From 74de0e89bea2802bf699397837ebf77252a0e06b Mon Sep 17 00:00:00 2001
From: Nathan Bossart <nathan@postgresql.org>
Date: Tue, 16 Apr 2024 21:23:52 -0500
Subject: [PATCH v3 1/1] Add code of conduct, contributing, and security files.
---
.github/CODE_OF_CONDUCT.md | 2 ++
.github/CONTRIBUTING.md | 2 ++
.github/SECURITY.md | 2 ++
3 files changed, 6 insertions(+)
create mode 100644 .github/CODE_OF_CONDUCT.md
create mode 100644 .github/CONTRIBUTING.md
create mode 100644 .github/SECURITY.md
diff --git a/.github/CODE_OF_CONDUCT.md b/.github/CODE_OF_CONDUCT.md
new file mode 100644
index 0000000000..99bb1905d6
--- /dev/null
+++ b/.github/CODE_OF_CONDUCT.md
@@ -0,0 +1,2 @@
+The PostgreSQL code of conduct can be found at
+<https://www.postgresql.org/about/policies/coc/>.
diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md
new file mode 100644
index 0000000000..0108e72956
--- /dev/null
+++ b/.github/CONTRIBUTING.md
@@ -0,0 +1,2 @@
+For information about contributing to PostgreSQL, see
+<https://www.postgresql.org/developer/>.
diff --git a/.github/SECURITY.md b/.github/SECURITY.md
new file mode 100644
index 0000000000..ebdbe609db
--- /dev/null
+++ b/.github/SECURITY.md
@@ -0,0 +1,2 @@
+For information about reporting security issues, see
+<https://www.postgresql.org/support/security/>.
--
2.25.1
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.
+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
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
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