Re: cutting down the TODO list thread

On Tue, Jan 24, 2023 at 10:46:34AM +0700, John Naylor wrote:
>
> On Wed, Jan 18, 2023 at 3:13 AM Bruce Momjian <bruce(at)momjian(dot)us> wrote:
>
> > I think we risk overloading people with too many words above, and they
> > will not read it fully.  Can it be simplified?  I wonder if some of this
> > belows in the developer's FAQ and linked to that from the TODO list.
>
> I think you're right. That further drives home what I mentioned a few days ago:
> Maybe we don't need to change much in the actual list itself, but rephrase
> references to it from elsewhere. Here's a first draft to see what that would

The TODO list started as a way to record items that were either bugs or
features we couldn't yet implement. At this point, it is more features
we are either not sure we want or don't know how to implement. This
should be clearly specified wherever the TODO list is referenced. I
think once this is done it should be clear how users and developers
should view that list. I think the top of the TODO list makes that
clear:

This list contains some known PostgreSQL bugs, some feature
requests, and some things we are not even sure we want. Many of
these items are hard, and some are perhaps impossible. If you
would like to work on an item, please read the Developer FAQ
first. There is also a development information page.

The rest of the text appears clear to me too.

> look like:
> --
> https://wiki.postgresql.org/wiki/So,_you_want_to_be_a_developer%3F#TODOs
>
> from:
> "PostgreSQL maintains a TODO list on our wiki: http://wiki.postgresql.org/wiki/
> TODO
>
> We have attempted to organize issues and link in relevant discussions from our
> mailing list archives. Please read background information if it is available
> before attempting to resolve a TODO. If no background information is available,
> it is appropriate to post a question to pgsql-hackers(at)postgresql(dot)org and
> request additional information and inquire about the status of any ongoing work
> on the problem."
>
> to:
> "It's worth checking if the feature of interest is found in the TODO list on
> our wiki: http://wiki.postgresql.org/wiki/TODO. That list contains some known
> PostgreSQL bugs, some feature requests, and some things we are not even sure we
> want. Many entries have a link to an email thread containing prior discussion,
> or perhaps attempts that for whatever reason didn't make it as far as getting
> committed."
>
> ...which might make more sense if moved below the "brand new features" section.

I think we just point them at the TODO list and they will read the top
of the list first, no? I think you are right that we updated the top of
the TODO but didn't update the places that link to it. I am thinking we
should just trim down the text linking to it and let the top of the TODO
list do its job.

> --
> https://wiki.postgresql.org/wiki/Developer_FAQ
>
> 1)
> from:
> "What areas need work?
> Outstanding features are detailed in Todo.
>
> You can learn more about these features by consulting the archives, the SQL
> standards and the recommended texts (see books for developers)."
>
> to:
> ??? -> For "what areas need work?", we need to have a different answer, but I'm
> not sure what it is.

Wow, I would not send a new person to the SQL standard docs. ;-) I am
thinking we just don't have a good answer to this so let's say less.

> 2)
> from:
> "What do I do after choosing an item to work on?
>
> Send an email to pgsql-hackers with a proposal for what you want to do
> (assuming your contribution is not trivial). Working in isolation is not
> advisable because others might be working on the same TODO item, or you might
> have misunderstood the TODO item. In the email, discuss both the internal
> implementation method you plan to use, and any user-visible changes (new
> syntax, etc)."
>
> to:
> "What do I do after choosing an area to work on?
>
> Send an email to pgsql-hackers with a proposal for what you want to do
> (assuming your contribution is not trivial). Working in isolation is not

Can new people identify trivial?

> advisable because experience has shown that there are often requirements that
> are not obvious, and if those are not agreed on beforehand it leads to wasted
> effort. In the email, discuss both the internal implementation method you plan
> to use, and any user-visible changes (new syntax, etc)."
>
> > On Wed, Jan 11, 2023 at 02:09:56PM +0700, John Naylor wrote:
> > > I've come up with some revised language, including s/15/16/ and removing
> the
> > > category of "[E]" (easier to implement), since it wouldn't be here if it
> were
> > > actually easy:
> >
> > I think it is still possible for a simple item to be identified as
> > wanted and easy, but not completed and put on the TODO list.
>
> Theoretically it's possible, but in practice no one puts any easy items here.
> Currently, there are three marked as easy:
>
> pg_dump:
> - Dump security labels and comments on databases in a way that allows to load a
> dump into a differently named database
> - Add full object name to the tag field. eg. for operators we need '=(integer,
> integer)', instead of just '='.
>
> Dump and restore is critical to get right, and the code base is pretty large
> and hairy, so I don't actually believe for a second that these items are easy.
>
> ECPG:
> - sqlwarn[6] should be 'W' if the PRECISION or SCALE value specified
>
> In one sentence there are four uses of jargon that only someone with experience
> would understand. I have hacked around ECPG multiple times and have no idea
> what this means.
>
> The last two also don't have any motivation spelled out, much less an email
> thread.
>
> So my inclination is, the [E] marker here is unjustified.

I can now see that just removing the [E] label totally is the right
answer. Yes, there might be an easy item on there, but the fact we have
three labeled and they are not easy makes me thing [E] is causing more
problems than it solves.

--
Bruce Momjian <bruce(at)momjian(dot)us> https://momjian.us
EDB https://enterprisedb.com

Embrace your flaws. They make you human, rather than perfect,
which you will never be.