From 663f08976b6c38b9ccb2b610b851ce3e913e6865 Mon Sep 17 00:00:00 2001 From: Robert Rothenberg Date: Sun, 29 Mar 2026 12:41:36 +0100 Subject: [PATCH 1/6] perlmodstyle: Update POD sections for DOCUMENTING YOUR MODULE This updates the sections to correspond to current usage. --- pod/perlmodstyle.pod | 29 ++++++++++++++++++++++++++--- 1 file changed, 26 insertions(+), 3 deletions(-) diff --git a/pod/perlmodstyle.pod b/pod/perlmodstyle.pod index 695d4713358f..034b7b7a21a2 100644 --- a/pod/perlmodstyle.pod +++ b/pod/perlmodstyle.pod @@ -542,11 +542,35 @@ DESCRIPTION =item * One or more sections or subsections giving greater detail of available -methods and routines and any other relevant information. +methods and routines and any other relevant information. For example, + +=over 4 + +=item * + +EXPORTS + +=item * + +METHODS + +=back =item * -BUGS/CAVEATS/etc +SECURITY CONSIDERATIONS + +=item * + +KNOWN ISSUES/CAVEATS/LIMITATIONS + +=item * + +SOURCE + +=item * + +SUPPORT/REPORTING ISSUES/BUGS =item * @@ -805,4 +829,3 @@ authors. =head1 AUTHOR Kirrily "Skud" Robert - From 22ef1af9dacb76652de3ac411af44b211dde20c9 Mon Sep 17 00:00:00 2001 From: Robert Rothenberg Date: Sun, 29 Mar 2026 12:54:41 +0100 Subject: [PATCH 2/6] perlmodstyle: Update section on the README, INSTALL etc This updates the section to mention that the README should be plain text or a markdown file, and that the installation instructions can be included in the README or as a separate file. It also improves the formatting and provides links to modules. --- pod/perlmodstyle.pod | 40 +++++++++++++++------------------------- 1 file changed, 15 insertions(+), 25 deletions(-) diff --git a/pod/perlmodstyle.pod b/pod/perlmodstyle.pod index 034b7b7a21a2..256d941b530e 100644 --- a/pod/perlmodstyle.pod +++ b/pod/perlmodstyle.pod @@ -594,37 +594,27 @@ POD and once in comments). =head2 README, INSTALL, release notes, changelogs -Your module should also include a README file describing the module and +Your module should also include a F file describing the module +and any requirements (including external libraries or files), and giving pointers to further information (website, author email). -An INSTALL file should be included, and should contain simple installation -instructions. When using ExtUtils::MakeMaker this will usually be: +The F should be a plain text file or markdown (F) file. -=over 4 - -=item perl Makefile.PL +Installation instructions should be included, either as a section in F +or as a separate F file. It should contain simple installation +instructions. When using L this will usually be: -=item make + perl Makefile.PL + make + make test + make install -=item make test +When using L, this will usually be: -=item make install - -=back - -When using Module::Build, this will usually be: - -=over 4 - -=item perl Build.PL - -=item perl Build - -=item perl Build test - -=item perl Build install - -=back + perl Build.PL + perl Build + perl Build test + perl Build install Release notes or changelogs should be produced for each release of your software describing user-visible changes to your module, in terms From f613603c7c9e4040df45d42bc6b953931e2e777c Mon Sep 17 00:00:00 2001 From: Robert Rothenberg Date: Sun, 29 Mar 2026 13:01:41 +0100 Subject: [PATCH 3/6] perlmodstyle: Refer users to perlpodstyle for more details --- pod/perlmodstyle.pod | 2 ++ 1 file changed, 2 insertions(+) diff --git a/pod/perlmodstyle.pod b/pod/perlmodstyle.pod index 256d941b530e..83c2f3120e61 100644 --- a/pod/perlmodstyle.pod +++ b/pod/perlmodstyle.pod @@ -592,6 +592,8 @@ method's subroutine. This makes it easier to keep the documentation up to date, and avoids having to document each piece of code twice (once in POD and once in comments). +The sections are described in more detail in L. + =head2 README, INSTALL, release notes, changelogs Your module should also include a F file describing the module From 2d5d321509e9ee1c03abb7b3d715b74697d0bf5a Mon Sep 17 00:00:00 2001 From: Robert Rothenberg Date: Sun, 29 Mar 2026 13:23:57 +0100 Subject: [PATCH 4/6] perlmodstyle: Add a section on community health documents --- pod/perlmodstyle.pod | 51 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 51 insertions(+) diff --git a/pod/perlmodstyle.pod b/pod/perlmodstyle.pod index 83c2f3120e61..c59cec64fe19 100644 --- a/pod/perlmodstyle.pod +++ b/pod/perlmodstyle.pod @@ -627,6 +627,57 @@ Unless you have good reasons for using some other format the convention is to name your changelog file C, and to follow the simple format described in L. +=head2 Community Health Documents + +You may want to add additional documents to your distribution. + +=over 4 + +=item F + +This contains the full text of the license. + +=item F + +This is a security policy that tells users how to report a security +vulnerability, and how you will handle such reports. See the CPAN +L for more information. + +=item F + +This outlines your policy on using AI/LLM tools for your distribution. +Is AI used to identify bugs? Is AI used to fix bugs and add new features? +Can AI tools make changes to code automatically without human interaction? + +=item F + +This describes how users can participate in development and contribute +issues or code changes. + +=item F + +This document describes standards of behaviour of maintainers, conteributors and other community members of the project. +This is often used for larger projects or projects with a large community of users. + +=item F + +This is used to identify sponsors of projects, and to indicate how the +project can be supported financially. + +=item F + +This will describe how the project is run, the different roles of +people in the project, and how decisions are made. + +=item F + +This will describe how users can get support for a project. It +indicates what aspects of the project you support (e.g. what Perl +versions and releases), and where people can find help (forums, IRC +channels, etc.) + +=back + =head1 RELEASE CONSIDERATIONS =head2 Version numbering From b63fdf545326cf1f7429cdcc13b150b401066c41 Mon Sep 17 00:00:00 2001 From: Robert Rothenberg Date: Wed, 1 Apr 2026 13:46:45 +0100 Subject: [PATCH 5/6] perlmodstyle: mention why README.pod should not be used --- pod/perlmodstyle.pod | 3 +++ 1 file changed, 3 insertions(+) diff --git a/pod/perlmodstyle.pod b/pod/perlmodstyle.pod index c59cec64fe19..9423e71f111a 100644 --- a/pod/perlmodstyle.pod +++ b/pod/perlmodstyle.pod @@ -601,6 +601,9 @@ and any requirements (including external libraries or files), and giving pointers to further information (website, author email). The F should be a plain text file or markdown (F) file. +Note that files like F should not be included in the +distribution, as they may confuse tools that interpret it as module +documentation, including the installer. Installation instructions should be included, either as a section in F or as a separate F file. It should contain simple installation From 98a5d72320b66da5649d534f9d8d01ffe96b8171 Mon Sep 17 00:00:00 2001 From: Robert Rothenberg Date: Tue, 7 Apr 2026 11:26:06 +0100 Subject: [PATCH 6/6] Add COPYING as an alternative to LICENSE --- pod/perlmodstyle.pod | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pod/perlmodstyle.pod b/pod/perlmodstyle.pod index 9423e71f111a..80f5a5afc10c 100644 --- a/pod/perlmodstyle.pod +++ b/pod/perlmodstyle.pod @@ -636,7 +636,7 @@ You may want to add additional documents to your distribution. =over 4 -=item F +=item F or F This contains the full text of the license.