Thread: 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:
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
Attachment
> 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 markdownREADME 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 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
Attachment
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
Attachment
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:
Original email version with more sections and content:
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
> 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
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
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
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:
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
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.
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
Attachment
> 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 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]. 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
Attachment
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-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"
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-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.
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.
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
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
Attachment
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
Attachment
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