pyversion.mk considered confusing

[Greg Troxel <gdt%lexort.com@localhost>]

I am finding myself not understanding pyversion.mk from the user
interface viewpoint.  It would be great if someone who is expert could
adjust commments.  Or, I can add some and then those people can correct
me if necessary.  Specific things I don't get are:

  - We have a concept of a python version being in pkgsrc, but excluded
    by default.  The comments don't explain that.

  - There's a variable for accepting 27, but it's not documented, and
    the docs say 27 can go into accepted.  Which is right?  (I think
    it's the variable and it's a bug to add 27 into
    PYTHON_VERSIONS_ACCEPTED.)

  - When does one set INCOMPATIBLE?  I think it's only when something
    in the default accepted is not ok.

  - if a package is ok with 310 in addition to default, should one add
    that to ACCEPTED?  It seems the point of removing 310 from default
    accepted is that so many things are breaking, that we'd rather just
    say no to 310 than deal with it, so no.  That leaves "put 310 in
    accepted if 310 is the highest acceptable version".  But the
    comments say that 310 is not valid in ACCEPTED.  Does that mean that
    pkgsrc will not ever build any py-foo that is 310 (unless someone
    edits pyversion.mk), and really the only aspeect of 310 remaining is
    python3.10?

  - What controls which versions are done in bulk builds?  I am guessing
    it is not in this file, in which case it's ok not to mention it.


This is not a complaint about what is.  Just pointing out that reading
the comments is not sufficient to understand what to do or what will
happen.