Re: Commitfest Update - Mailing list pgsql-hackers

> On 11 Jul 2022, at 15:07, Matthias van de Meent <boekewurm+postgres@gmail.com> wrote:

> No objections, but this adds another item to the implicit commitfest
> app user manual, that to the best of my knowledge seems to be mostly
> implicit institutional knowledge plus bits of information spread
> around the mailing lists.

That's mostly true yes, which means that anything I write below is to be taken
with n grains of salt as it's my interpretation of said institutional
knowledge.

> Do we have an actual manual or otherwise a (single?) place with
> documentation on how certain fields of the CFA should be used or
> interpreted, so that (new) hackers know what to expect or where to
> look?

We don't AFAIK, but we should.  Either an actual written manual (which may end
up in many tldr folders) or inline help within the app (the latter being my
preference I think).

> Examples of information about using the CFA that I couldn't find:
> - The Version field may contain a single specific postgresql version
> number, 'stable', or nothing. If my patch needs backpatching to all
> backbranches, which do I select? The oldest supported PG version, or
> 'stable'? Related to that: which version is indicated by 'stable'?

I'll refer to the commitmessage from the CF app repo on this:

commit a3bac5922db76efd5b6bb331a7141e9ca3209c4a
Author: Magnus Hagander <magnus@hagander.net>
Date:   Wed Feb 6 21:05:06 2019 +0100

    Add a field to each patch for target version

    This is particularly interesting towards the end of a cycle where it can
    be used to flag patches that are not intended for the current version
    but still needs review.

The thread on -hackers which concluded on adding the field has a lot more of
the reasoning but some quick digging didn't find it.

> - When creating or updating a CF entry, who are responsible for
> filling in which fields? May the author assign reviewers/committers,
> or should they do so themselves?

Reviewers and committers sign themselves up.

> - Should the 'git link' be filled with a link to the committed patch
> once committed, or is it a general purpose link to share a git
> repository with the proposed changes?

The gitlink field is (was?) primarily meant to hold links to external repos for
large patchsets where providing a repo on top of the patches in the thread is
valuable.  An example would be Andres et.al's IO work where being able to
follow the work as it unfolds in a repo is valuable for reviewers.

> - What should (or shoudn't) Annotations be used for?

Annotations are used for indicating that certain emails are specifically
important and/or highlight them as taking specific design decisions etc.  It
can be used for anything that is providing value to the a new reader of the
thread really.

> - What should I expect of the comment / review system of the CFA?
> Should I use feature over direct on-list mails?

I think that's up to personal preference, for reviewers who aren't subscribed
to -hackers it's clearly useful to attach it to the thread.  For anyone already
subscribed and used to corresponding on the mailinglist I would think that's
the easiest option.

> I'm not asking anyone to drop all and get all the features of the CFA
> documented, but for my almost 2 years of following the -hackers list I
> feel like I still haven't gotten a good understanding of the
> application that is meant to coordinate the shared state in patch
> development, and I think that's a quite a shame.

There has been a lot of discussions around how to improve the CF app but they
have to a large extent boiled down to ENOTENOUGHTIME.  I still have my hopes
that we can address these before too long, and adding user documentation is
clearly an important one.

--
Daniel Gustafsson        https://vmware.com/