Re: PG 13 release notes, first draft

On Mon, May 11, 2020 at 08:41:00PM +0300, Alexander Korotkov wrote:
> On Mon, May 11, 2020 at 4:20 PM Bruce Momjian <bruce(at)momjian(dot)us> wrote:
> > Sorry for the delay in replying. Yes, I agree we should list all of
> > those operator class cases where we now take arguments. I looked at the
> > patch but got confused and missed the doc changes that clearly need to
> > be in the release notes. I see these operator classes now taking
> > parameters, as you helpfully listed in your commit message:
> >
> > tsvector_ops
> > gist_ltree_ops
> > gist__ltree_ops
> > gist_trgm_ops
> > gist_hstore_ops
> > gist__int_ops
> > gist__intbig_ops
> >
> > I assume the double-underscore is because the first underscore is to
> > separate words, and the second one is for the array designation, right?
>
> Yes, this is true.

OK.

> > So my big question is whether people will understand when they are using
> > these operator classes, since many of them are defaults. Can you use an
> > operator class parameter when you are just using the default operator
> > class and not specifying its name?
>
> Actually no. Initial version of patch allowed to explicitly specify
> DEFAULT keyword instead of opclass name. But I didn't like idea to
> allow keyword instead of name there.
>
> I've tried to implement syntax allowing specifying parameters without
> both new keyword and opclass name, but that causes a lot of grammar
> problems.
>
> Finally, I've decided to provide parameters functionality only when
> specifying opclass name. My motivation is that opclass parameters is
> functionality for advanced users, who are deeply concerned into what
> opclass do. For this category of users it's natural to know the
> opclass name.

Yes, that is good analysis, and your final decision was probably
correct. I now see that the complexity is not a big problem.

> > What I thinking that just saying
> > the operator class take arguments might not be helpful. I think I see
> > enough detail in the documentation to write release note items for
> > these, but I will have to point out they need to specify the operator
> > class, even if it is the default, right?
>
> My point was that we should specify where to look to find new
> functionality. We can don't write opclass names, because those names
> might be confusing for users who are not aware of them. We may
> briefly say that new parameters are introduced for GiST for tsvector,
> contrib/intarray, contrib/pg_trgm, contrib/ltree, contrib/hstore.
> What do you think?

OK, I have applied the attached patch, which I now think is the right
level of detail, given your information above. Thanks.

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

+ As you are, so once was I. As I am, so you will be. +
+ Ancient Roman grave inscription +