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@momjian.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@momjian.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 +