This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
HACKERS: Add info about Hints and Warnings
[perl5.git] / dist / Devel-PPPort / HACKERS
index c5fe0ed..1c159ff 100644 (file)
@@ -11,238 +11,140 @@ lying around in this distribution.
 
 =head1 DESCRIPTION
 
-=head2 How to build 366 versions of Perl
+=head2 How to backport something
+
+First, make sure that what you want to backport is documented.  If it's worth
+backporting, it surely is worth documenting.  Send a documentation patch to 
+L<perlbug@perl.org|mailto:perlbug@perl.org> if necessary.  Also,
+C<Devel::PPPort> cannot automatically generate proper information about the
+item without at least knowing its API prototype.  It can get this from
+F<embed.fnc> if the item is a function, but if it is a macro, there needs to be
+at least a S<C<=for apidoc>> line for C<Devel::PPPort> to be able to figure
+things out on its own.
+
+Next, figure out where to place your implementation.  Look at all the files in
+F<parts/inc/> for one that fits what you're planning.  If there isn't one,
+just start a new one and remember to include it from within F<PPPort_pm.PL>.
+If you do create a new file, it's usually the best approach to just copy an
+existing file and use it as a template.
 
-C<Devel::PPPort> supports Perl versions between 5.003 and bleadperl.
-To guarantee this support, I need some of these versions on my
-machine. I currently have 366 different Perl version/configuration
-combinations installed on my laptop.
-
-As many of the old Perl distributions need patching to compile
-cleanly on newer systems (and because building 366 Perls by hand
-just isn't fun), I wrote a tool to build all the different
-versions and configurations. You can find it in F<devel/buildperl.pl>.
-It can currently build the following Perl releases:
-
-    5.003
-    5.004 - 5.004_05
-    5.005 - 5.005_04
-    5.6.x
-    5.7.x
-    5.8.x
-    5.9.x
-    5.1x.x
-
-=head2 Fully automatic API checks
-
-Knowing which parts of the API are not backwards compatible and
-probably need C<Devel::PPPort> support is another problem that's
-not easy to deal with manually. If you run
-
-    perl Makefile.PL --with-apicheck
-
-a C file is generated by F<parts/apicheck.pl> that is compiled
-and linked with C<Devel::PPPort>. This C file has the purpose of
-using each of the public API functions/macros once.
-
-The required information is derived from C<parts/embed.fnc> (just
-a copy of bleadperl's C<embed.fnc>), C<parts/apidoc.fnc> (which
-is generated by F<devel/mkapidoc.sh> and simply collects the rest
-of the apidoc entries spread over the Perl source code) and
-C<parts/ppport.fnc> (which lists all API provided purely by
-Devel::PPPort).
-The generated C file C<apicheck.c> is currently about 500k in size
-and takes quite a while to compile.
-
-Usually, C<apicheck.c> won't compile with older perls. And even if
-it compiles, there's still a good chance of the dynamic linker
-failing at C<make test> time. But that's on purpose!
-
-We can use these failures to find changes in the API automatically.
-The two Perl scripts F<devel/mktodo> and F<devel/mktodo.pl>
-repeatedly run C<Devel::PPPort> with the apicheck code through
-all different versions of perl. Scanning the output of the compiler
-and the dynamic linker for errors, the files in F<parts/todo/> are
-generated. These files list all parts of the public API that don't
-work with less than a certain version of Perl.
-
-This information is in turn used by F<parts/apicheck.pl> to mask
-API calls in the generated C file for these versions, so the
-process can be stopped by the time F<apicheck.c> compiles cleanly
-and the dynamic linker is happy. (Actually, this process may generate
-false positives, so by default each API call is checked once more
-afterwards.)
-
-Running C<devel/mktodo> takes about an hour, depending of course
-on the machine you're running it on. If you run it with
-the C<--nocheck> option, it won't recheck the API calls that failed
-in the compilation stage and it'll take significantly less time.
-Running with C<--nocheck> should usually be safe.
-
-When running C<devel/mktodo> with the C<--base> option, it will
-generate the I<baseline> todo files by disabling all functionality
-provided by C<Devel::PPPort>. These are required for implementing
-the C<--compat-version> option of the C<ppport.h> script. The
-baseline todo files hold the information about which version of
-Perl lacks a certain part of the API.
-
-However, only the documented public API can be checked this way.
-And since C<Devel::PPPort> provides more macros, these would not be
-affected by C<--compat-version>. It's the job of F<devel/scanprov>
-to figure out the baseline information for all remaining provided
-macros by scanning the include files in the F<CORE> directory of
-various Perl versions.
-
-The whole process isn't platform independent. It has currently been
-tested only under Linux, and it definitely requires at least C<gcc> and
-the C<nm> utility.
-
-It's not very often that one has to regenerate the baseline and todo
-files. If you have to, you can either run F<devel/regenerate> or just
-execute the following steps by hand:
+Each file holds all relevant data for implementing a certain part
+of the API:
 
-=over 4
+=over 2
 
 =item *
 
-You need a whole bunch of different Perls. The more, the better.
-You can use F<devel/buildperl.pl> to build them. I keep my perls
-in F</tmp/perl>, so most of the tools take this as a default.
+A list of the provided API in the C<=provides> section.
 
 =item *
 
-You also need a freshly built bleadperl that is in the path under
-exactly this name. (The name of the executable is currently hardcoded
-in F<devel/mktodo> and F<devel/scanprov>.)
+The optional C<=dontwarn> section is used to suppress warnings about particular
+API elements.  Don't use this unless you get such a warning, and be sure to
+think about using other other alternatives before resorting to adding something
+in this section.
 
 =item *
 
-Remove all existing todo files in the F<parts/base> and
-F<parts/todo> directories.
+The implementation to add to F<ppport.h> in the C<=implementation>
+section.  See L</Implementation Section Details>.
 
 =item *
 
-Update the API information. Copy the latest F<embed.fnc> file from
-bleadperl to the F<parts> directory and run F<devel/mkapidoc.sh> to
-collect the remaining information in F<parts/apidoc.fnc>.
+The code required to add to PPPort.xs for testing the implementation.
+This code goes into the C<=xshead>, C<=xsinit>, C<=xsmisc>, C<=xsboot>
+and C<=xsubs> section. Have a look at the template at the bottom
+of F<RealPPPort_xs.PL> to see where the code ends up.
 
 =item *
 
-Build the new baseline by running
+The tests in the C<=tests> section. Remember not to use any fancy
+modules or syntax elements, as the test code needs to be able to run
+with Perl 5.003.  (This is because Devel::PPPort itself will run all test files
+in the process of generating the information about when a feature came into
+existence.)  This means, for example
 
-    perl devel/mktodo --base
+=over
 
-in the root directory of the distribution. When it's finished,
-move all files from the F<parts/todo> directory to F<parts/base>.
+=item C<my> isn't supported in C<for>-loops
 
-=item *
+    for my $x (1, 2, 3) { }    # won't work with 5.003
 
-Build the new todo files by running
+Instead declare C<$x> just before the statement
 
-    perl devel/mktodo
+=item The postfix C<for> statement modifier isn't supported
 
-in the root directory of the distribution.
+    foo for 1..2
 
-=item *
+won't compile.  Instead enclose C<foo> in a loop.
 
-Finally, add the remaining baseline information by running
+=item You can't use plain C<qr//>
 
-    perl Makefile.PL && make
-    perl devel/scanprov --mode=write
+Instead, wrap it in a string eval C<eval "qr//">, and be sure it's skipped at
+execution time on perls earlier than 5.005
 
 =back
 
-=head2 Implementation
-
-Residing in F<parts/inc/> is the "heart" of C<Devel::PPPort>. Each
-of the files implements a part of the supported API, along with
-hints, dependency information, XS code and tests.
-The files are in a POD-like format that is parsed using the
-functions in F<parts/ppptools.pl>.
-
-The scripts F<PPPort_pm.PL>, F<PPPort_xs.PL> and F<mktests.PL> all
-use the information in F<parts/inc/> to generate the main module
-F<PPPort.pm>, the XS code in F<RealPPPort.xs> and various test files
-in F<t/>.
-
-All of these files could be generated on the fly while building
-C<Devel::PPPort>, but not having the tests in C<t/> will confuse
-TEST/harness in the core. Not having F<PPPort.pm> will be bad for
-viewing the docs on C<search.cpan.org>. So unfortunately, it's
-unavoidable to put some redundancy into the package.
-
-=head2 Adding stuff to Devel::PPPort
-
-First, check if the code you plan to add fits into one of the
-existing files in F<parts/inc/>. If not, just start a new one and
-remember to include it from within F<PPPort_pm.PL>.
-
-Each file holds all relevant data for implementing a certain part
-of the API:
-
-=over 2
-
-=item *
-
-A list of the provided API in the C<=provides> section.
-
-=item *
-
-The implementation to add to F<ppport.h> in the C<=implementation>
-section.
-
-=item *
-
-The code required to add to PPPort.xs for testing the implementation.
-This code goes into the C<=xshead>, C<=xsinit>, C<=xsmisc>, C<=xsboot>
-and C<=xsubs> section. Have a look at the template at the bottom
-of F<PPPort_xs.PL> to see where the code ends up.
-
-=item *
-
-The tests in the C<=tests> section. Remember not to use any fancy
-modules or syntax elements, as the test code should be able to run
-with Perl 5.003, which, for example, doesn't support C<my> in
-C<for>-loops:
-
-    for my $x (1, 2, 3) { }    # won't work with 5.003
-
 You can use C<ok()> to report success or failure:
 
   ok($got == 42);
-    ok($got, $expected);
ok($got, $expected, 'name');
+ ok($got == 42);     # Doesn't give good runtime diagnostics
 
-Regular expressions are not supported as the second argument to C<ok>,
-because older perls do not support the C<qr> operator.
+ ok($got, eval "qr/foo/", 'name') # But don't execute this statement
+                                  # on perls earlier than 5.005
 
 =back
 
-It's usually the best approach to just copy an existing file and
-use it as a template.
+In all sections, lines that begin with C<##> are completely ignored.
+
+=head2 Implementation Section Details
+
+=over
 
-=head2 Implementation Hints
+=item __UNDEFINED__
 
-In the C<=implementation> section, you can use
+If you add the line C<__UNDEFINED__> to the C<=provides> section, you can use
+lines like this in the C<=implementation> section:
 
   __UNDEFINED__ macro    some definition
 
-instead of
+to both define C<macro> and indicate that it is provided by F<ppport.h>.  This
+replaces these C<=implementation> section lines:
 
   #ifndef macro
   #  define macro    some definition
   #endif
 
-The macro can have optional arguments and the definition can even
-span multiple lines, like in
+besides automagically making it be considered to be provided.  C<macro> can
+have optional arguments and the definition can even span multiple lines, like
+in
 
   __UNDEFINED__ SvMAGIC_set(sv, val) \
                 STMT_START { assert(SvTYPE(sv) >= SVt_PVMG); \
                 (((XPVMG*) SvANY(sv))->xmg_magic = (val)); } STMT_END
 
-This usually makes the code more compact and readable. And you
-only have to add C<__UNDEFINED__> to the C<=provided> section.
+This usually makes the code more compact and readable.
+
+But you should only use this on things that you plan to publicly provide.  If
+something, such as a mnemonic for a constant needs to be defined but isn't
+really needed for the public at larget to know about, you should use
+
+ __UNDEF_NOT_PROVIDED__ macro   some definition
+
+instead.  To avoid name space conflicts, follow what's in L</Helper macros>,
+below.
 
-Version checking can be tricky if you want to do it correct.
+=item Helper macros
+
+If you need to define a helper macro which is not part of C<Devel::PPPort> API
+and its usage is only for the definition of other C<Devel::PPPort> macros, then
+use the C<D_PPP_> prefix for this macro name (e.g. C<D_PPP_SVPV_NOLEN_LP_ARG>).
+This suppresses any warnings when a macro is defined which is not part of the
+Perl public API.
+
+=item Version numbers
+
+Version checking can be tricky to get correct.
 You can use
 
   #if { VERSION < 5.9.3 }
@@ -251,7 +153,7 @@ instead of
 
   #if ((PERL_VERSION < 9) || (PERL_VERSION == 9 && PERL_SUBVERSION < 3))
 
-The version number can be either of the new form C<5.x.x> or of the older
+The version number can be either of the new form C<5.x.x> or the older
 form C<5.00x_yy>. Both are translated into the correct preprocessor
 statements. It is also possible to combine this with other statements:
 
@@ -264,11 +166,86 @@ statements. It is also possible to combine this with other statements:
 This not only works in the C<=implementation> section, but also in
 the C<=xsubs>, C<=xsinit>, C<=xsmisc>, C<=xshead> and C<=xsboot> sections.
 
+=item Hints
+
+If you add a comment like so:
+
+ /* Hint: PL_expect, PL_copline, PL_rsfp
+    paragraphs of stuff about foo you want to have
+    shown when ppport.h outputs something about PL_expect or
+    PL_copline or PL_rsfp
+ */
+
+Earlier versions of F<ppport.h> required an asterisk at the beginning of every
+continuation line, or else the content would be silently dropped.
+
+=item Warnings
+
+A more serious caution about C<foo> can be displayed by instead saying
+
+ /* Warning: PL_expect, PL_copline, PL_rsfp
+    paragraphs of stuff about foo you want to have
+    shown when ppport.h outputs something about PL_expect or
+    PL_copline or PL_rsfp
+ */
+
+Earlier versions of F<ppport.h> required an asterisk at the beginning of every
+continuation line, or else the content would be silently dropped.
+
+=item Replace
+
+When F<ppport.h> is run on a file(s), you can cause it to automatically flag
+occurrences of the constructs you specify, encouraging the author to replace
+them with different (presumably better) ones.  These also are used in any
+suggested edits and generated patches.
+
+There are three ways to do this
+
+=over 4
+
+=item in-line comment
+
+You can add a trailing comment like so:
+
+ #define bar foo    /* Replace */
+ __UNDEFINED__ bar foo  /* Replace */
+
+These say that C<foo> should be replaced by C<bar>.  NOT the other way around.
+
+=item separate comment
+
+For situations not amenable to the above, you can say
+
+ /* Replace foo with bar */
+
+=item define a replacement region
+
+It you have several replacements, you can group them together like so:
+
+ /* Replace: 1 */
+ #define foo bar
+ #define bat baz
+ /* Replace: 0 */
+
+These replace C<foo> with C<bar>; C<bat> with C<baz>.
+
+=back
+
+=item Dependencies
+
+F<ppport.h> automatically gathers information as to what functions are
+dependent on what other things from inspecting the source, but if this is
+insufficient for you, you can add lines like the following:
+
+ /* foo, bar depends on baz, bat */
+
+Each of C<foo>, C<bar> depends on each of C<baz>, C<bat>.
+
+=back
+
 =head2 Testing
 
-To automatically test C<Devel::PPPort> with lots of different Perl
-versions, you can use the F<soak> script. Just pass it a list of
-all Perl binaries you want to test.
+After you have furnished your implementation, you need to test it.
 
 =head2 Special Makefile targets
 
@@ -284,12 +261,271 @@ use
 
 That's it.
 
+To automatically test C<Devel::PPPort> with lots of different Perl
+versions, you can use the F<soak> script. Just pass it a list of
+all Perl binaries you want to test.
+
+=head2 Regenerating F<ppport.h> and F<PPPort.pm>
+
+C<Devel::PPPort> keeps two directories of generated files, in F<parts/base> and
+F<parts/todo>.  The files in each are named after Perl version numbers.  When a
+function or macro came into existence is indicated by placing its name in the
+corresponding file in F<parts/base>.  The files in F<parts/todo> are the same,
+except they indicate the earliest release that F<ppport.h> supports the
+element.  The delta is effectively what F<ppport.h> buys you.
+
+The generation process described in this section creates these files.  It does
+so by examining as many perl versions as are available to it.  It tries to make
+sure each element actually compiles, and it runs the test scripts you have
+furnished on every version.
+
+Ideally, this should be done before every release that includes new backporting
+and/or when blead has added new public API.  At a minimum, it should be done as
+the next major Perl release comes out.
+
+The process isn't platform independent. It has currently been tested only under
+Linux, and it definitely requires at least C<gcc> and the C<nm> utility.
+The process used to be problematic, with random failures.  But it has now been
+fixed to be reliable.
+
+Before starting the regeneration, you need to have gathered certain data.
+(Options listed below apply to the tools that eventually will use the data, and
+which are described further below).
+
+=over 4
+
+Here you can add additional information for a given item that will be displayed
+when F<ppport.h> is run.  If your item is named C<foo>, you add a
+comment like so:
+
+ /* Hint: foo
+    paragraphs of stuff about foo you want to have
+    shown when ppport.h outputs something about foo
+ */
+
+This will cause S<C<perl ppport.h>> to display this hint when it outputs
+something about C<foo>.
+
+A more serious caution about C<foo> can be displayed by instead saying
+
+ /* Warning: foo
+    paragraphs of stuff about foo you want to have
+    shown when ppport.h outputs something about foo
+ */
+
+=item *
+
+You will first need a whole bunch of different Perls, the more, the better, but
+only one per version tag (which one is random) will actually get used.
+dromedary has a sufficient set.  They should all have the same Configure
+options with respect to what functions and macros are enabled.  For example,
+they should all be threaded, or all non-threaded.  A mixture will screw up the
+results.  Similarly, they should all or none have quad math (at least as far
+back as that became available).  You can use F<devel/buildperl.pl> to build
+them.
+
+Previous maintainers of this module kept those perls in
+F</tmp/perl/install/default>, so most of the tools use this as a default, but
+you'll likely simply use the C<--install=> option to specify where.  This
+should be a path where a S<C<make install>> has been done, so has immediate
+subdirectories of C</bin> and C</lib>.  C</bin> should contain the binaries.
+It will use all files in this directory whose names begin with C<perl5>.
+
+Actually, not all the binaries need be in this directory.  You can specify
+additional places to look since C<--install=> takes a comma separated list of
+directories.
+
+=item *
+
+You also need a freshly built bleadperl.  The C<--blead=I<path>> option should
+be used to specify it.  (Some of the tools have a default of C<bleadperl-debug>
+if this option is omitted.)  Again, it needs the same Configure options as the
+earlier versions had.
+
+=item *
+
+And you will need updated API information. Copy the latest F<embed.fnc> file
+from bleadperl to the F<parts> directory and run F<devel/mkapidoc.pl> to
+collect the remaining information in F<parts/apidoc.fnc>.
+
+=item *
+
+The final step before regenerating everything is to run F</devel/mkppport.fnc>
+to update the F</parts/ppport.fnc> file.
+
+=back
+
+Having done this, run F<devel/regenerate> which wraps the following steps
+(which you could instead do by hand, but it's easy to forget things):
+
+=over
+
+=item *
+
+It first does some sanity checking
+
+=item *
+
+Then it asks you if it's ok to remove all existing todo files in the
+F<parts/base> and F<parts/todo> directories.  If you answer no, the process
+aborts.
+
+This is crtical to getting accurate results.
+
+=item *
+
+It builds the new baseline by running
+
+    perl devel/mktodo --base
+
+in the root directory of the distribution.
+
+If there are warnings in blead, it will ask you to examine them, and to ok if
+it's all right to go ahead.  If there are issues with blead, everything
+following could be wrong.
+
+=item *
+
+It builds the new todo files by running
+
+    perl devel/mktodo
+
+in the root directory of the distribution.
+
+=item *
+
+Finally, it adds the remaining information by running
+
+    perl Makefile.PL && make
+    perl devel/scanprov --mode=write
+
+=back
+
+=head2 How to build gobs of versions of Perl
+
+C<Devel::PPPort> supports Perl versions between 5.003 and bleadperl.
+To guarantee this support, its good to have as many versions as possible to
+test on.  dromedary currently has many such versions.
+
+There is a tool to build all the different
+versions and configurations. You can find it in F<devel/buildperl.pl>.
+It can currently build the following Perl releases:
+
+    5.003
+    5.004 - 5.004_05
+    5.005 - 5.005_04
+    5.6.x
+    5.7.x
+    5.8.x
+    5.9.x
+    5.1x.x
+    5.2x.x
+    5.3x.x
+
+=head2 Implementation
+
+Knowing which parts of the API are not backwards compatible and
+probably need C<Devel::PPPort> support is another problem that's
+not easy to deal with manually. If you run
+
+    perl Makefile.PL --with-apicheck
+
+a C file is generated by F<parts/apicheck.pl> that is compiled
+and linked with C<Devel::PPPort>. This C file has the purpose of
+using each of the public API functions/macros once.
+
+The required information is derived from F<parts/embed.fnc> (just
+a copy of bleadperl's F<embed.fnc>), F<parts/apidoc.fnc> (which
+is generated by F<devel/mkapidoc.sh> and simply collects the rest
+of the apidoc entries spread over the Perl source code) and
+F<parts/ppport.fnc> (which lists the API provided purely by
+Devel::PPPort, along with other elements that are tested only using
+F<ppport.h>).
+
+The generated C file (usually, F<apicheck.c>) won't compile as-is
+with older perls. And even if it compiles, there's still a good chance of the
+dynamic linker failing at C<make test> time. But that's on purpose!
+
+We can use these failures to find changes in the API automatically.
+The Perl script F<devel/mktodo> calls another script F<devel/mktodo.pl>
+repeatedly to run C<Devel::PPPort> on version after version of perl, in
+decreasing version order, so we start with blead and work backwards.  The
+latter script generates an F<apicheck.c>.  It starts with the code that
+successfully worked in the previously tested Perl version, which should be the
+version one higher than the current one.  Call the current one I<n>, and the
+previous one I<n+1>.  The items that fail to compile in I<n>, but did compile
+in I<n+1> must have become available in I<n+1>.  We run the Linux command C<nm>
+to find those undefined symbols in I<n>.  We change F<apicheck.c> to ignore
+(through C<#ifdef>'s) those and recompile, repeating until F<apicheck.c>
+successfully compiles, the dynamic linker is happy, and C<make test> runs on
+this version.  Then we repeat the process for I<n-1>, and so on.  (Actually,
+this process may generate false positives, so by default each failing API call
+is checked again.  If possible, this is done by generating an F<apicheck.c> for
+just the one failing API.)
+
+Running F<devel/mktodo> currently takes a couple hours on dromedary.
+
+If you run it with the C<--nocheck> option, it won't recheck the API calls
+that failed in the compilation stage and it'll take significantly less time.
+No one currently associated with maintaining this module understands under what
+circumstances it is safe to run with C<--nocheck>.
+
+By repeating the process over and over, we build up information on when every
+element first became supported.  This information is stored in files in the
+F<parts/base> directory, one file per version.  The file for version I<n+1> is
+generated by running version I<n> of perl.
+
+We actually want a second piece of information, which is how much F<ppport.h>
+buys you.  What happens when regenerating is actually two entire runs through
+all the perls.  The first is accomplished by calling F<devel/mktodo> with the
+C<--base> option.  It automically will call F<devel/mktodo.pl> with each
+version of perl, NOT using anything in F<ppport.h>.  When done the results
+indicate  when each API element became available in stock perl, without using
+F<ppport.h>.
+
+And then the whole process is repeated, but this time F<ppport.h> is included.
+The files are placed in F<parts/todo>.  Thus, at the end, we know when each
+element became available in modified perl, using F<ppport.h>.
+
+However, only the public API that is implemented as functions (and must appear
+in F<embed.fnc>) plus macros whose calling sequence is documented can be
+checked this way.  The final step in the process is calling F<devel/scanprov>.
+It looks through the header files for when all the symbols provided by
+C<Devel::PPPort> first became defined.  It doesn't test the symbols or try to
+compile them, as it doesn't generally know the API, but it can tell that
+something exists in release I<n+1> but not I<n> (by scanning the include files
+in the F<CORE> directory of various Perl versions).  (It does know if a macro
+has zero arguments or non-zero arguments, so it does get extra information from
+the zero argument ones.)
+
+=head2 Files
+
+Residing in F<parts/inc/> is the "heart" of C<Devel::PPPort>. Each
+of the files implements a part of the supported API, along with
+hints, dependency information, XS code and tests.
+The files are in a POD-like format that is parsed using the
+functions in F<parts/ppptools.pl>.
+
+The scripts F<PPPort_pm.PL>, F<RealPPPort_xs.PL> and F<mktests.PL> all
+use the information in F<parts/inc/> to generate the main module
+F<PPPort.pm>, the XS code in F<RealPPPort.xs> and various test files
+in F<t/>.
+
+You can get extra information from F<PPPort_pm.PL> by setting the environment
+variable C<DPPP_CHECK_LEVEL> to 1 or 2.
+
+All of these files could be generated on the fly while building
+C<Devel::PPPort>, but not having the tests in F<t/> will confuse
+TEST/harness in the core. Not having F<PPPort.pm> will be bad for
+viewing the docs on C<search.cpan.org>. So unfortunately, it's
+unavoidable to put some redundancy into the package.
+
 =head2 Submitting Patches
 
 If you've added some functionality to C<Devel::PPPort>, please
-consider submitting a patch with your work to GitHub here:
-L<https://github.com/mhx/Devel-PPPort/issues/>, or by sending a
-Pull Request.
+consider submitting a patch with your work to P5P by sending a pull request to
+
+L<https://github.com/Dual-Life/Devel-PPPort/pulls>.
 
 When submitting patches, please only add the relevant changes
 and don't include the differences of the generated files. You
@@ -307,9 +543,12 @@ module in the core:
   META.yml
   PPPort.pm
 
+=head1 BUGS
+
 =head1 COPYRIGHT
 
-Version 3.x, Copyright (C) 2004-2013, Marcus Holland-Moritz.
+Version 3.x, Copyright (C) 2004-2019, Marcus Holland-Moritz
+and Perl 5 porters
 
 Version 2.x, Copyright (C) 2001, Paul Marquess.
 
@@ -320,6 +559,6 @@ modify it under the same terms as Perl itself.
 
 =head1 SEE ALSO
 
-See L<ppport.h> and L<devel/regenerate>.
+See F<ppport.h> and F<devel/regenerate>.
 
 =cut