Обсуждение: Uniform policy for author credits in contrib module documentation?
As of CVS HEAD, some of the contrib module documentation pages have extensive credit screeds, eg http://developer.postgresql.org/pgdocs/postgres/cube.html and some just have the author's name, with or without an <email> link, and some don't have anything at all. This bothers me; it seems like we should have a more uniform approach. There are some arguments to be made for not having credits at all. We don't make a habit of crediting individuals anywhere else in the SGML docs; credits in the source code and/or CVS logs are supposed to be enough. And we do still have author credits in contrib/README, not to mention the individual source code files. And there's the whole issue that files that have been there awhile have probably been tweaked by a number of people besides the original author. OTOH I dislike removing credits that the authors might have expected to be there, and the contrib modules mostly do have identifiable original authors. If we do want to keep credits in the SGML pages, how extensive should they be? I already took it on myself to remove Gene Selkov's snailmail address, but do we even want email addresses there? A lot of them are probably dead, and the ones that aren't are causing their owners to get extra spam, because an <email> link is about the easiest thing to scrape from a webpage that there could possibly be. I don't have a strong opinion one way or the other, except that I think we should have a uniform policy for all the contrib modules. Comments? regards, tom lane
Tom Lane wrote: > As of CVS HEAD, some of the contrib module documentation pages have > extensive credit screeds, eg > http://developer.postgresql.org/pgdocs/postgres/cube.html > and some just have the author's name, with or without an <email> link, > and some don't have anything at all. > > This bothers me; it seems like we should have a more uniform approach. [snip] > I don't have a strong opinion one way or the other, except that I think > we should have a uniform policy for all the contrib modules. > > Comments? As far as I'm concerned, you can remove any credits for me from the contrib modules I've worked on (or I can do it if you'd prefer). In any case +1 for a uniform policy, and +1 for removing credits from documentation. Joe
Re: [HACKERS] Uniform policy for author credits in contrib module documentation?
От
"Joshua D. Drake"
Дата:
Tom Lane wrote: > As of CVS HEAD, some of the contrib module documentation pages have > extensive credit screeds, eg > http://developer.postgresql.org/pgdocs/postgres/cube.html > and some just have the author's name, with or without an <email> link, > and some don't have anything at all. > I don't have a strong opinion one way or the other, except that I think > we should have a uniform policy for all the contrib modules. Well once we push directly into the core documentation I agree that outside of release notes (although you just brought that up in another thread) we don't need to be mentioning contributions like that. Those who have contributed are in the logs. Further those who have provided reasonable contribution really should be mentioned on the contributors page that is up for discussion which would make the rest of this moot yes? Sincerely, Joshua D. Drake > > Comments? > > regards, tom lane > > ---------------------------(end of broadcast)--------------------------- > TIP 2: Don't 'kill -9' the postmaster >
"Joshua D. Drake" <jd@commandprompt.com> writes: > ...Further those who have provided reasonable contribution really should be > mentioned on the contributors page that is up for discussion which would > make the rest of this moot yes? I don't have any objection to listing people on the contributors page on the strength of their work on contrib modules. But that seems orthogonal to the question of what should be in the SGML docs ... regards, tom lane
Re: [HACKERS] Uniform policy for author credits in contrib module documentation?
От
"Joshua D. Drake"
Дата:
Tom Lane wrote: > "Joshua D. Drake" <jd@commandprompt.com> writes: >> ...Further those who have provided reasonable contribution really should be >> mentioned on the contributors page that is up for discussion which would >> make the rest of this moot yes? > > I don't have any objection to listing people on the contributors page > on the strength of their work on contrib modules. But that seems > orthogonal to the question of what should be in the SGML docs ... All I was saying is I don't think we need the redundancy :). E.g; if they are worthy in the docs, they are worthy on the contributors page and thus not needed in the docs. I am not of a strong opinion either way but it seems having names plastered everywhere just creates more management of information for no particular purpose. Sincerely, Joshua D. Drake > > regards, tom lane >
Re: Re: [HACKERS] Uniform policy for author credits in contrib module documentation?
От
Magnus Hagander
Дата:
On Wed, Dec 05, 2007 at 10:46:51PM -0800, Joshua D. Drake wrote: > Tom Lane wrote: > >As of CVS HEAD, some of the contrib module documentation pages have > >extensive credit screeds, eg > >http://developer.postgresql.org/pgdocs/postgres/cube.html > >and some just have the author's name, with or without an <email> link, > >and some don't have anything at all. > > >I don't have a strong opinion one way or the other, except that I think > >we should have a uniform policy for all the contrib modules. > > Well once we push directly into the core documentation I agree that > outside of release notes (although you just brought that up in another > thread) we don't need to be mentioning contributions like that. Those > who have contributed are in the logs. > > Further those who have provided reasonable contribution really should be > mentioned on the contributors page that is up for discussion which would > make the rest of this moot yes? +1, since they are listed in the release notes when the contrib modules are added - just like any other piece of code. IMO no reason to treat contrib differently from any other code in this case. //Magnus
On Dec 5, 2007 8:58 PM, Tom Lane <tgl@sss.pgh.pa.us> wrote: > If we do want to keep credits in the SGML pages, how extensive should > they be? ... > I don't have a strong opinion one way or the other, except that I think > we should have a uniform policy for all the contrib modules. One of the things that I used to do with the old HOWTO documentation from the Linux Documentation Project was jump directly to the Acknowledgement or Credit sections and read who the author had decided to thank, and then search for more information about those people and what they had done. While it might be a pain to maintain that information, it does humanize and provide context for a document. Also, the tradition of thanking people (or higher powers) and taking a few moments to reflect on who might have helped one accomplish something is a good one. Maybe I'm just being nostalgic, but I like that the content of credit sections is not uniform. Rather than remove credits, we could apply a regex to obfuscate the email addresses, and offer a mention to authors in the more general contributors area when packages are added. -selena -- Selena Deckelmann PDXPUG - Portland PostgreSQL Users Group http://pugs.postgresql.org/pdx http://www.chesnok.com/daily
Re: [HACKERS] Uniform policy for author credits in contrib module documentation?
От
Josh Berkus
Дата:
Tom, > If we do want to keep credits in the SGML pages, how extensive should > they be? I already took it on myself to remove Gene Selkov's snailmail > address, but do we even want email addresses there? A lot of them are > probably dead, and the ones that aren't are causing their owners to get > extra spam, because an <email> link is about the easiest thing to scrape > from a webpage that there could possibly be. Historically, the only way to troubleshoot some of the contrib modules was to e-mail the author. If people think that we've reached a standard that everything in /contrib is now well-documented and supported by the general community, the I suppose we don't need contact information. I'm not so sure myself. --Josh
Josh Berkus <josh@agliodbs.com> writes: > Historically, the only way to troubleshoot some of the contrib modules > was to e-mail the author. If people think that we've reached a standard > that everything in /contrib is now well-documented and supported by the > general community, the I suppose we don't need contact information. I'm > not so sure myself. I do not think that we should encourage people to mail the authors first rather than pgsql-bugs. For one thing, a lot of those addresses are dead, and some of the ones that aren't don't respond especially fast. If the community-at-large can't handle a bug, we certainly have enough institutional memory to try to contact the original author, even if that address isn't in the SGML docs. regards, tom lane
Re: [HACKERS] Uniform policy for author credits in contrib module documentation?
От
"Joshua D. Drake"
Дата:
Tom Lane wrote: > Josh Berkus <josh@agliodbs.com> writes: >> Historically, the only way to troubleshoot some of the contrib modules >> was to e-mail the author. If people think that we've reached a standard >> that everything in /contrib is now well-documented and supported by the >> general community, the I suppose we don't need contact information. I'm >> not so sure myself. > > I do not think that we should encourage people to mail the authors first > rather than pgsql-bugs. For one thing, a lot of those addresses are > dead, and some of the ones that aren't don't respond especially fast. > > If the community-at-large can't handle a bug, we certainly have enough > institutional memory to try to contact the original author, even if that > address isn't in the SGML docs. > Perhaps the at a minimum the email goes in the commit? Joshua D. Drake > regards, tom lane > > ---------------------------(end of broadcast)--------------------------- > TIP 5: don't forget to increase your free space map settings >
Re: [HACKERS] Uniform policy for author credits in contrib module documentation?
От
Andrew Dunstan
Дата:
Joshua D. Drake wrote: > Tom Lane wrote: >> Josh Berkus <josh@agliodbs.com> writes: >>> Historically, the only way to troubleshoot some of the contrib >>> modules was to e-mail the author. If people think that we've >>> reached a standard that everything in /contrib is now >>> well-documented and supported by the general community, the I >>> suppose we don't need contact information. I'm not so sure myself. >> >> I do not think that we should encourage people to mail the authors first >> rather than pgsql-bugs. For one thing, a lot of those addresses are >> dead, and some of the ones that aren't don't respond especially fast. >> >> If the community-at-large can't handle a bug, we certainly have enough >> institutional memory to try to contact the original author, even if that >> address isn't in the SGML docs. >> > > Perhaps the at a minimum the email goes in the commit? > I don't see any reason, unless we're going to start doing that for all contributions. 'contrib' is a serious misnomer anyway, and there's no reason to think in general that the original author is specially responsible for any of it. I think Tom's point is entirely valid. cheers andrew
Re: [HACKERS] Uniform policy for author credits in contrib module documentation?
От
"Selena Deckelmann"
Дата:
On Dec 7, 2007 9:03 AM, Andrew Dunstan <andrew@dunslane.net> wrote: > > > Joshua D. Drake wrote: > > Tom Lane wrote: > >> Josh Berkus <josh@agliodbs.com> writes: > >>> Historically, the only way to troubleshoot some of the contrib > >>> modules was to e-mail the author. If people think that we've > >>> reached a standard that everything in /contrib is now > >>> well-documented and supported by the general community, the I > >>> suppose we don't need contact information. I'm not so sure myself. > >> > >> I do not think that we should encourage people to mail the authors first > >> rather than pgsql-bugs. For one thing, a lot of those addresses are > >> dead, and some of the ones that aren't don't respond especially fast. > >> > >> If the community-at-large can't handle a bug, we certainly have enough > >> institutional memory to try to contact the original author, even if that > >> address isn't in the SGML docs. > >> > > > > Perhaps the at a minimum the email goes in the commit? > > > > I don't see any reason, unless we're going to start doing that for all > contributions. 'contrib' is a serious misnomer anyway, and there's no > reason to think in general that the original author is specially > responsible for any of it. I think Tom's point is entirely valid. I think it is totally appropriate to replace the email address contact information with a link to pgsql-bugs. But there are reasons other than bugfixing to contact the original author of a patch or contrib packages. Some of those could include: * collaboration on a professional, hobby or academic research level * journalism/books written about PostgreSQL * academic or historical research into the development of PostgreSQL * job prospects * socializing For those reasons, I think it would be a huge loss to the community to remove the credit sections or to prevent their inclusion in future documentation. Maintaining them leaves a breadcrumb trail that otherwise would be lost in mailing list threads and commit logs that are very difficult for a person without specialized knowledge to navigate. Why make contacting people hard? Some of the contrib features are likely targets for future research and development (for example: tsearch, HOT, pl/lolcode - not contrib, but awesome!) and in that context, the specific people involved are important. Contrib documentation will get folded into the main docs eventually (and at that point, the credits are removed). But the record of that evolution is easily accessed, without any special knowledge of a revision control system, or mailing list culture. And I realize that the logical extension of what I am saying is a research and documentation project about the people who all have contributed to the development of PostgreSQL. -selena -- Selena Deckelmann PDXPUG - Portland PostgreSQL Users Group http://pugs.postgresql.org/pdx http://www.chesnok.com/daily
Re: Re: [HACKERS] Uniform policy for author credits in contrib module documentation?
От
Robert Treat
Дата:
On Thursday 06 December 2007 03:54, Magnus Hagander wrote: > On Wed, Dec 05, 2007 at 10:46:51PM -0800, Joshua D. Drake wrote: > > Tom Lane wrote: > > >As of CVS HEAD, some of the contrib module documentation pages have > > >extensive credit screeds, eg > > >http://developer.postgresql.org/pgdocs/postgres/cube.html > > >and some just have the author's name, with or without an <email> link, > > >and some don't have anything at all. > > > > > >I don't have a strong opinion one way or the other, except that I think > > >we should have a uniform policy for all the contrib modules. > > > > Well once we push directly into the core documentation I agree that > > outside of release notes (although you just brought that up in another > > thread) we don't need to be mentioning contributions like that. Those > > who have contributed are in the logs. > > > > Further those who have provided reasonable contribution really should be > > mentioned on the contributors page that is up for discussion which would > > make the rest of this moot yes? > > +1, since they are listed in the release notes when the contrib modules are > added - just like any other piece of code. IMO no reason to treat contrib > differently from any other code in this case. > Hmm, I have often seen that the person listed in the contrib docs was considered the person to contact if you had questions/comments/patches/etc... about a specific contrib module. I wonder if people would still get the same level of help if those names are removed and they have to go to the regular mailing lists for help (which contrib authors may not follow). -- Robert Treat Build A Brighter LAMP :: Linux Apache {middleware} PostgreSQL