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+26-1
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+5-7
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+4-5
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
