Adding upstream version 4.22.0.upstream/4.22.0

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 546 insertions, 0 deletions

diff --git a/upstream/debian-bookworm/man3/Test2::Transition.3perl b/upstream/debian-bookworm/man3/Test2::Transition.3perl
new file mode 100644
index 00000000..1fe45298
--- /dev/null
+++ b/upstream/debian-bookworm/man3/Test2::Transition.3perl
@@ -0,0 +1,546 @@
+.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" Set up some character translations and predefined strings.  \*(-- will
+.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
+.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
+.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
+.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
+.\" nothing in troff, for use with C<>.
+.tr \(*W-
+.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
+.ie n \{\
+.    ds -- \(*W-
+.    ds PI pi
+.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
+.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
+.    ds L" ""
+.    ds R" ""
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds -- \|\(em\|
+.    ds PI \(*p
+.    ds L" ``
+.    ds R" ''
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "Test2::Transition 3perl"
+.TH Test2::Transition 3perl "2023-11-25" "perl v5.36.0" "Perl Programmers Reference Guide"
+.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
+.\" way too many mistakes in technical documents.
+.if n .ad l
+.nh
+.SH "NAME"
+Test2::Transition \- Transition notes when upgrading to Test2
+.SH "DESCRIPTION"
+.IX Header "DESCRIPTION"
+This is where gotchas and breakages related to the Test2 upgrade are
+documented. The upgrade causes Test::Builder to defer to Test2 under the hood.
+This transition is mostly transparent, but there are a few cases that can trip
+you up.
+.SH "THINGS THAT BREAK"
+.IX Header "THINGS THAT BREAK"
+This is the list of scenarios that break with the new internals.
+.SS "Test::Builder1.5/2 conditionals"
+.IX Subsection "Test::Builder1.5/2 conditionals"
+\fIThe Problem\fR
+.IX Subsection "The Problem"
+.PP
+a few years back there were two attempts to upgrade/replace Test::Builder.
+Confusingly these were called Test::Builder2 and Test::Builder1.5, in that
+order. Many people put conditionals in their code to check the Test::Builder
+version number and adapt their code accordingly.
+.PP
+The Test::Builder2/1.5 projects both died out. Now the conditional code people
+added has become a mine field. A vast majority of modules broken by Test2 fall
+into this category.
+.PP
+\fIThe Fix\fR
+.IX Subsection "The Fix"
+.PP
+The fix is to remove all Test::Builder1.5/2 related code. Either use the
+legacy Test::Builder \s-1API,\s0 or use Test2 directly.
+.SS "Replacing the Test::Builder singleton"
+.IX Subsection "Replacing the Test::Builder singleton"
+\fIThe Problem\fR
+.IX Subsection "The Problem"
+.PP
+Some test modules would replace the Test::Builder singleton instance with their
+own instance or subclass. This was usually done to intercept or modify results
+as they happened.
+.PP
+The Test::Builder singleton is now a simple compatibility wrapper around
+Test2. The Test::Builder singleton is no longer the central place for
+results. Many results bypass the Test::Builder singleton completely, which
+breaks and behavior intended when replacing the singleton.
+.PP
+\fIThe Fix\fR
+.IX Subsection "The Fix"
+.PP
+If you simply want to intercept all results instead of letting them go to \s-1TAP,\s0
+you should look at the Test2::API docs and read about pushing a new hub onto
+the hub stack. Replacing the hub temporarily is now the correct way to
+intercept results.
+.PP
+If your goal is purely monitoring of events use the \f(CW\*(C`Test2::Hub\->listen()\*(C'\fR
+method exported by Test::More to watch events as they are fired. If you wish to
+modify results before they go to \s-1TAP\s0 look at the \f(CW\*(C`Test2::Hub\->filter()\*(C'\fR
+method.
+.SS "Directly Accessing Hash Elements"
+.IX Subsection "Directly Accessing Hash Elements"
+\fIThe Problem\fR
+.IX Subsection "The Problem"
+.PP
+Some modules look directly at hash keys on the Test::Builder singleton. The
+problem here is that the Test::Builder singleton no longer holds anything
+important.
+.PP
+\fIThe Fix\fR
+.IX Subsection "The Fix"
+.PP
+The fix is to use the \s-1API\s0 specified in Test2::API to look at or modify state
+as needed.
+.SS "Subtest indentation"
+.IX Subsection "Subtest indentation"
+\fIThe Problem\fR
+.IX Subsection "The Problem"
+.PP
+An early change, in fact the change that made Test2 an idea, was a change to
+the indentation of the subtest note. It was decided it would be more readable
+to outdent the subtest note instead of having it inline with the subtest:
+.PP
+.Vb 4
+\&    # subtest foo
+\&        ok 1 \- blah
+\&        1..1
+\&    ok 1 \- subtest foo
+.Ve
+.PP
+The old style indented the note:
+.PP
+.Vb 4
+\&        # subtest foo
+\&        ok 1 \- blah
+\&        1..1
+\&    ok 1 \- subtest foo
+.Ve
+.PP
+This breaks tests that do string comparison of \s-1TAP\s0 output.
+.PP
+\fIThe Fix\fR
+.IX Subsection "The Fix"
+.PP
+.Vb 1
+\&    my $indent = $INC{\*(AqTest2/API.pm\*(Aq} ? \*(Aq\*(Aq : \*(Aq    \*(Aq;
+\&
+\&    is(
+\&        $subtest_output,
+\&        "${indent}# subtest foo",
+\&        "Got subtest note"
+\&    );
+.Ve
+.PP
+Check if \f(CW$INC{\*(AqTest2/API.pm\*(Aq}\fR is set, if it is then no indentation should be
+expected. If it is not set, then the old Test::Builder is in use, indentation
+should be expected.
+.SH "DISTRIBUTIONS THAT BREAK OR NEED TO BE UPGRADED"
+.IX Header "DISTRIBUTIONS THAT BREAK OR NEED TO BE UPGRADED"
+This is a list of cpan modules that have been known to have been broken by the
+upgrade at one point.
+.SS "\s-1WORKS BUT TESTS WILL FAIL\s0"
+.IX Subsection "WORKS BUT TESTS WILL FAIL"
+These modules still function correctly, but their test suites will not pass. If
+you already have these modules installed then you can continue to use them. If
+you are trying to install them after upgrading Test::Builder you will need to
+force installation, or bypass the broken tests.
+.IP "Test::DBIx::Class::Schema" 4
+.IX Item "Test::DBIx::Class::Schema"
+This module has a test that appears to work around a Test::Builder bug. The bug
+appears to have been fixed by Test2, which means the workaround causes a
+failure. This can be easily updated, but nobody has done so yet.
+.Sp
+Known broken in versions: 1.0.9 and older
+.IP "Device::Chip" 4
+.IX Item "Device::Chip"
+Tests break due to subtest indentation.
+.Sp
+Known broken in version 0.07. Apparently works fine in 0.06 though. Patch has
+been submitted to fix the issue.
+.SS "\s-1UPGRADE SUGGESTED\s0"
+.IX Subsection "UPGRADE SUGGESTED"
+These are modules that did not break, but had broken test suites that have
+since been fixed.
+.IP "Test::Exception" 4
+.IX Item "Test::Exception"
+Old versions work fine, but have a minor test name behavior that breaks with
+Test2. Old versions will no longer install because of this. The latest version
+on \s-1CPAN\s0 will install just fine. Upgrading is not required, but is recommended.
+.Sp
+Fixed in version: 0.43
+.IP "Data::Peek" 4
+.IX Item "Data::Peek"
+Some tests depended on \f(CW$!\fR and \f(CW$?\fR being modified in subtle ways. A patch
+was applied to correct things that changed.
+.Sp
+The module itself works fine, there is no need to upgrade.
+.Sp
+Fixed in version: 0.45
+.IP "circular::require" 4
+.IX Item "circular::require"
+Some tests were fragile and required base.pm to be loaded at a late stage.
+Test2 was loading base.pm too early. The tests were updated to fix this.
+.Sp
+The module itself never broke, you do not need to upgrade.
+.Sp
+Fixed in version: 0.12
+.IP "Test::Module::Used" 4
+.IX Item "Test::Module::Used"
+A test worked around a now-fixed planning bug. There is no need to upgrade if
+you have an old version installed. New versions install fine if you want them.
+.Sp
+Fixed in version: 0.2.5
+.IP "Test::Moose::More" 4
+.IX Item "Test::Moose::More"
+Some tests were fragile, but have been fixed. The actual breakage was from the
+subtest comment indentation change.
+.Sp
+No need to upgrade, old versions work fine. Only new versions will install.
+.Sp
+Fixed in version: 0.025
+.IP "Test::FITesque" 4
+.IX Item "Test::FITesque"
+This was broken by a bugfix to how planning is done. The test was updated after
+the bugfix.
+.Sp
+Fixed in version: 0.04
+.IP "Test::Kit" 4
+.IX Item "Test::Kit"
+Old versions work fine, but would not install because Test::Aggregate was in
+the dependency chain. An upgrade should not be needed.
+.Sp
+Fixed in version: 2.15
+.IP "autouse" 4
+.IX Item "autouse"
+A test broke because it depended on Scalar::Util not being loaded. Test2 loads
+Scalar::Util. The test was updated to load Test2 after checking Scalar::Util's
+load status.
+.Sp
+There is no need to upgrade if you already have it installed.
+.Sp
+Fixed in version: 1.11
+.SS "\s-1NEED TO UPGRADE\s0"
+.IX Subsection "NEED TO UPGRADE"
+.IP "Test::SharedFork" 4
+.IX Item "Test::SharedFork"
+Old versions need to directly access Test::Builder singleton hash elements. The
+latest version on \s-1CPAN\s0 will still do this on old Test::Builder, but will defer
+to Test2::IPC on Test2.
+.Sp
+Fixed in version: 0.35
+.IP "Test::Builder::Clutch" 4
+.IX Item "Test::Builder::Clutch"
+This works by doing overriding methods on the singleton, and directly accessing
+hash values on the singleton. A new version has been released that uses the
+Test2 \s-1API\s0 to accomplish the same result in a saner way.
+.Sp
+Fixed in version: 0.07
+.IP "Test::Dist::VersionSync" 4
+.IX Item "Test::Dist::VersionSync"
+This had Test::Builder2 conditionals. This was fixed by removing the
+conditionals.
+.Sp
+Fixed in version: 1.1.4
+.IP "Test::Modern" 4
+.IX Item "Test::Modern"
+This relied on \f(CW\*(C`Test::Builder\->_try()\*(C'\fR which was a private method,
+documented as something nobody should use. This was fixed by using a different
+tool.
+.Sp
+Fixed in version: 0.012
+.IP "Test::UseAllModules" 4
+.IX Item "Test::UseAllModules"
+Version 0.14 relied on \f(CW\*(C`Test::Builder\->history\*(C'\fR which was available in
+Test::Builder 1.5. Versions 0.12 and 0.13 relied on other Test::Builder
+internals.
+.Sp
+Fixed in version: 0.15
+.IP "Test::More::Prefix" 4
+.IX Item "Test::More::Prefix"
+Worked by applying a role that wrapped \f(CW\*(C`Test::Builder\->_print_comment\*(C'\fR.
+Fixed by adding an event filter that modifies the message instead when running
+under Test2.
+.Sp
+Fixed in version: 0.007
+.SS "\s-1STILL BROKEN\s0"
+.IX Subsection "STILL BROKEN"
+.IP "Test::Aggregate" 4
+.IX Item "Test::Aggregate"
+This distribution directly accesses the hash keys in the Test::Builder
+singleton. It also approaches the problem from the wrong angle, please consider
+using Test2::Aggregate for similar functionality and Test2::Harness
+which allows module preloading at the harness level.
+.Sp
+Still broken as of version: 0.373
+.IP "Test::Wrapper" 4
+.IX Item "Test::Wrapper"
+This module directly uses hash keys in the Test::Builder singleton. This
+module is also obsolete thanks to the benefits of Test2. Use \f(CW\*(C`intercept()\*(C'\fR
+from Test2::API to achieve a similar result.
+.Sp
+Still broken as of version: 0.3.0
+.IP "Test::ParallelSubtest" 4
+.IX Item "Test::ParallelSubtest"
+This module overrides \f(CW\*(C`Test::Builder::subtest()\*(C'\fR and
+\&\f(CW\*(C`Test::Builder::done_testing()\*(C'\fR. It also directly accesses hash elements of
+the singleton. It has not yet been fixed.
+.Sp
+Alternatives: Test2::AsyncSubtest and Test2::Workflow (not stable).
+.Sp
+Still broken as of version: 0.05
+.IP "Test::Pretty" 4
+.IX Item "Test::Pretty"
+See https://github.com/tokuhirom/Test\-Pretty/issues/25
+.Sp
+The author admits the module is crazy, and he is awaiting a stable release of
+something new (Test2) to completely rewrite it in a sane way.
+.Sp
+Still broken as of version: 0.32
+.IP "Net::BitTorrent" 4
+.IX Item "Net::BitTorrent"
+The tests for this module directly access Test::Builder hash keys. Most, if
+not all of these hash keys have public \s-1API\s0 methods that could be used instead
+to avoid the problem.
+.Sp
+Still broken in version: 0.052
+.IP "Test::Group" 4
+.IX Item "Test::Group"
+It monkeypatches Test::Builder, and calls it \*(L"black magic\*(R" in the code.
+.Sp
+Still broken as of version: 0.20
+.IP "Test::Flatten" 4
+.IX Item "Test::Flatten"
+This modifies the Test::Builder internals in many ways. A better was to
+accomplish the goal of this module is to write your own subtest function.
+.Sp
+Still broken as of version: 0.11
+.IP "Log::Dispatch::Config::TestLog" 4
+.IX Item "Log::Dispatch::Config::TestLog"
+Modifies Test::Builder internals.
+.Sp
+Still broken as of version: 0.02
+.IP "Test::Able" 4
+.IX Item "Test::Able"
+Modifies Test::Builder internals.
+.Sp
+Still broken as of version: 0.11
+.SH "MAKE ASSERTIONS \-> SEND EVENTS"
+.IX Header "MAKE ASSERTIONS -> SEND EVENTS"
+.SS "\s-1LEGACY\s0"
+.IX Subsection "LEGACY"
+.Vb 1
+\&    use Test::Builder;
+\&
+\&    # A majority of tools out there do this:
+\&    # my $TB = Test::Builder\->new;
+\&    # This works, but has always been wrong, forcing Test::Builder to implement
+\&    # subtests as a horrific hack. It also causes problems for tools that try
+\&    # to replace the singleton (also discouraged).
+\&
+\&    sub my_ok($;$) {
+\&        my ($bool, $name) = @_;
+\&        my $TB = Test::Builder\->new;
+\&        $TB\->ok($bool, $name);
+\&    }
+\&
+\&    sub my_diag($) {
+\&        my ($msg) = @_;
+\&        my $TB = Test::Builder\->new;
+\&        $TB\->diag($msg);
+\&    }
+.Ve
+.SS "\s-1TEST2\s0"
+.IX Subsection "TEST2"
+.Vb 1
+\&    use Test2::API qw/context/;
+\&
+\&    sub my_ok($;$) {
+\&        my ($bool, $name) = @_;
+\&        my $ctx = context();
+\&        $ctx\->ok($bool, $name);
+\&        $ctx\->release;
+\&    }
+\&
+\&    sub my_diag($) {
+\&        my ($msg) = @_;
+\&        my $ctx = context();
+\&        $ctx\->diag($msg);
+\&        $ctx\->release;
+\&    }
+.Ve
+.PP
+The context object has \s-1API\s0 compatible implementations of the following methods:
+.ie n .IP "ok($bool, $name)" 4
+.el .IP "ok($bool, \f(CW$name\fR)" 4
+.IX Item "ok($bool, $name)"
+.PD 0
+.IP "diag(@messages)" 4
+.IX Item "diag(@messages)"
+.IP "note(@messages)" 4
+.IX Item "note(@messages)"
+.ie n .IP "subtest($name, $code)" 4
+.el .IP "subtest($name, \f(CW$code\fR)" 4
+.IX Item "subtest($name, $code)"
+.PD
+.PP
+If you are looking for helpers with \f(CW\*(C`is\*(C'\fR, \f(CW\*(C`like\*(C'\fR, and others, see
+Test2::Suite.
+.SH "WRAP EXISTING TOOLS"
+.IX Header "WRAP EXISTING TOOLS"
+.SS "\s-1LEGACY\s0"
+.IX Subsection "LEGACY"
+.Vb 1
+\&    use Test::More;
+\&
+\&    sub exclusive_ok {
+\&        my ($bool1, $bool2, $name) = @_;
+\&
+\&        # Ensure errors are reported 1 level higher
+\&        local $Test::Builder::Level = $Test::Builder::Level + 1;
+\&
+\&        $ok = $bool1 || $bool2;
+\&        $ok &&= !($bool1 && $bool2);
+\&        ok($ok, $name);
+\&
+\&        return $bool;
+\&    }
+.Ve
+.PP
+Every single tool in the chain from this, to \f(CW\*(C`ok\*(C'\fR, to anything \f(CW\*(C`ok\*(C'\fR calls
+needs to increment the \f(CW$Level\fR variable. When an error occurs Test::Builder
+will do a trace to the stack frame determined by \f(CW$Level\fR, and report that
+file+line as the one where the error occurred. If you or any other tool you use
+forgets to set \f(CW$Level\fR then errors will be reported to the wrong place.
+.SS "\s-1TEST2\s0"
+.IX Subsection "TEST2"
+.Vb 1
+\&    use Test::More;
+\&
+\&    sub exclusive_ok {
+\&        my ($bool1, $bool2, $name) = @_;
+\&
+\&        # Grab and store the context, even if you do not need to use it
+\&        # directly.
+\&        my $ctx = context();
+\&
+\&        $ok = $bool1 || $bool2;
+\&        $ok &&= !($bool1 && $bool2);
+\&        ok($ok, $name);
+\&
+\&        $ctx\->release;
+\&        return $bool;
+\&    }
+.Ve
+.PP
+Instead of using \f(CW$Level\fR to perform a backtrace, Test2 uses a context
+object. In this sample you create a context object and store it. This locks the
+context (errors report 1 level up from here) for all wrapped tools to find. You
+do not need to use the context object, but you do need to store it in a
+variable. Once the sub ends the \f(CW$ctx\fR variable is destroyed which lets future
+tools find their own.
+.SH "USING UTF8"
+.IX Header "USING UTF8"
+.SS "\s-1LEGACY\s0"
+.IX Subsection "LEGACY"
+.Vb 3
+\&    # Set the mode BEFORE anything loads Test::Builder
+\&    use open \*(Aq:std\*(Aq, \*(Aq:encoding(utf8)\*(Aq;
+\&    use Test::More;
+.Ve
+.PP
+Or
+.PP
+.Vb 5
+\&    # Modify the filehandles
+\&    my $builder = Test::More\->builder;
+\&    binmode $builder\->output,         ":encoding(utf8)";
+\&    binmode $builder\->failure_output, ":encoding(utf8)";
+\&    binmode $builder\->todo_output,    ":encoding(utf8)";
+.Ve
+.SS "\s-1TEST2\s0"
+.IX Subsection "TEST2"
+.Vb 1
+\&    use Test2::API qw/test2_stack/;
+\&
+\&    test2_stack\->top\->format\->encoding(\*(Aqutf8\*(Aq);
+.Ve
+.PP
+Though a much better way is to use the Test2::Plugin::UTF8 plugin, which is
+part of Test2::Suite.
+.SH "AUTHORS, CONTRIBUTORS AND REVIEWERS"
+.IX Header "AUTHORS, CONTRIBUTORS AND REVIEWERS"
+The following people have all contributed to this document in some way, even if
+only for review.
+.IP "Chad Granum (\s-1EXODIST\s0) <exodist@cpan.org>" 4
+.IX Item "Chad Granum (EXODIST) <exodist@cpan.org>"
+.SH "SOURCE"
+.IX Header "SOURCE"
+The source code repository for Test2 can be found at
+\&\fIhttp://github.com/Test\-More/test\-more/\fR.
+.SH "MAINTAINER"
+.IX Header "MAINTAINER"
+.IP "Chad Granum <exodist@cpan.org>" 4
+.IX Item "Chad Granum <exodist@cpan.org>"
+.SH "COPYRIGHT"
+.IX Header "COPYRIGHT"
+Copyright 2020 Chad Granum <exodist@cpan.org>.
+.PP
+This program is free software; you can redistribute it and/or
+modify it under the same terms as Perl itself.
+.PP
+See \fIhttp://www.perl.com/perl/misc/Artistic.html\fR