Add known bugs in class feature to perlclass.pod

[johannessen]

When the experimental class feature was added in v5.38, it had some known problems that could cause segmentation faults, including #20956, #20947, and #20890 (duplicate: #21221).

As these issues persist to this day, I think they should be mentioned somewhere in Perl’s documentation. This change adds them to perl5380delta, and includes a brief erratum in the new v5.40 perldelta.

[Leont]

I'm not sure perldelta is really the right place for this.

[rwp0]

Good to know about those specific cases.

Since there's no perlbugs, I'd go to perldelta by default to check the status for v5.38 updates, as a user.

[rwp0]

I don't know why but "Known Issues" sounds more familiar 🙂

[johannessen]

In general, I’d tend to agree, but in perldelta, “known problems” is the usual terminology:

https://github.com/Perl/perl5/blob/blead/Porting/perldelta_template.pod#known-problems

[leonerd]

=head1 KNOWN BUGS would be the traditional heading. level-1 headings are all-caps.

[johannessen]

Actually I think =heads1 BUGS is the traditional heading in Perl reference documents other than perldelta, see e. g. perlre or perlebcdic. But I’m happy with “known bugs” if you prefer it.

[johannessen]

The description of the ”Known Problems” section in perldelta_template.pod is as follows:

XXX Descriptions of platform agnostic bugs we know we can't fix go here. Any tests that had to be TODOed for the release would be noted here. Unfixed platform specific bugs also go here.

There is certainly room to split some hairs about what exactly this language means. But I think it’s not meant to be exclusive.

The way I see it, the intention is that any unfixed platform-agnostic bugs which simply happen to not have TODO tests yet should indeed be listed as “known problems,” too.

[Leont]

We don't usually update perldelta like that (except minor edits like typos and broken links). Perhaps perlexperimental is a more logical place.

[johannessen]

I see your point, but a “KNOWN PROBLEMS” section in perlexperiment might imply to readers that all known issues for experiments are listed. I’m not in a position to produce such a comprehensive list.

I suppose adding a “BUGS” section to perlclass might work, plus a pointer in the new 5.40 perldelta for “updated documentation.” Would that be more appropriate?

[Leont]

@leonerd probably some ideas about where the best place would be

[leonerd]

I imagine a "KNOWN BUGS" section in perlclass.pod would be handy.

[leonerd]

I imagine putting a KNOWN BUGS section into perlclass.pod would be better than perldelta. perldelta is where people look for changes between versions. These bugs aren't new here, they've always been around. Listing them as known alongside the place where the feature itself is documented would be the best place.

[johannessen]

Thank you all for your guidance! PR updated.

I’m not sure how much detail I should go into when describing the issues in perlclass.pod. I’ve opted for just a brief summary plus a GH link. Is that appropriate here?

[khwilliamson]

I don't know anything about the accuracy of the wording, but stylistically, it LGTM. A brief mention and a GH link are appropriate, I think.

requested changes were made

[haarg]

If this is fixed, why are we listing it here?

[johannessen]

It’s been frustrating trying to write code that uses the ongoing class experiment because bugs like this prevent some code from working properly on certain versions of perl. So this information can help to make the evaluation of the experiment a bit easier.

Another reason would be completeness: We forgot to mention several of these issues in the v5.38 release entirely. Now that the list of known bugs is added, it might not hurt to mention the fixed one as well.

There also seems to be precedent for this in the one of the documents I mentioned earlier, perlebcdic. Seeing that is, in fact, what gave me the idea.