I have decided to write a successor to Pod::Readme that works as a Dist::Zilla plugin that plays well with Pod::Weaver.

The idea for Pod::Readme is that a README file that is simply a version of the module documentation isn't all that useful. It often lacks important details like the prerequisites or installation instructions, and it includes a lot of unnecessary details about functions and methods.

A README file should be short and sweet: a synopsis and description, installation instructions and requirements, links to issue trackers, source repos and author/copyright info.

As I am rewriting this, I am wondering if the installation instructions are necessary now?

Many distributions have a generic INSTALL file, generally created by something like Dist::Zilla::Plugin::InstallGuide.

Before Dist::Zilla was as widely used, another option was to add installation instructions to the README file, usually with a few boilerplate along the lines of

perl Makefile.PL
make
make test
make install

or the equivalent for Module::Build.

But this seems unnecessary. Most people are not installing modules that way.

Usually they are using a tool like cpan, cpanm, cpm or even carton. And there's arely anything unusual about a module that requires specialised installation instructions.

The only use case I can think of is to document non-Perl external libraries that are required. But that can be overcome using Alien modules or adding a separate REQUIREMENTS section to the README.

I am considering removing the generic INSTALL file from modules.

I am curious as to what other people in the Perl community think about this.

Is it still worthwhile to add generic installation instructions to distributions nowadays?

I was inspired by Daniel Stenberg's recent article Detecting malicious Unicode to write Test::MixedScripts, which tests Perl source code and other text files for unexpected Unicode scripts.

Why should you care about this?

There are Unicode characters in different scripts (alphabets) that look similar and are easily confused.

A malicious person could replace a domain name or other important token with one that looks correct, for is associated with a host or other resource that they control.

Consider the two domain names, "оnе.example.com" and "one.example.com". They look indistinguishable in many fonts, but the first one has Cyrillic letters.

Confusing Unicode might be added to your codebase through a malicious patch submission or pull request. Or it could be added as text from an email or web page that you copied and pasted into your code.

The module is easy to use, and defaults to testing for Latin and Common characters:

use Test::V0;
use Test::MixedScripts v0.3.0 qw/ all_perl_files_scripts_ok /;

all_perl_files_scripts_ok();

done_testing;

If you ran this test against a file with the URLs in the above example, you would see an error such as

Unexpected Cyrillic character on line 11 character 32

If your code has Cyrillic characters then you can add line- or region-specific notations, for example

my $host = "оnе.example.com"; ## Text::MixedScripts Common,Cyrillic,Latin

or you could use this for the entire codebase

all_perl_files_scripts_ok( { scripts => [qw/ Common Cyrillic Latin /] } );

You can also test specific non-Perl files:

file_scripts_ok( "Makefile" );
file_scripts_ok( "bin/service.sh" );
file_scripts_ok( "assets/script.js" );
file_scripts_ok( "assets/style.css" );
file_scripts_ok( "templates/index.tmpl" );

There's also a Dist::Zilla::Plugin::Test::MixedScripts to generate an author test for Dist::Zilla-managed distributions.

This is a new new project, so there are likely bugs. But please give it a try, especially if you work on modules with mixed scripts in the codebase.

Adding a SECURITY or SECURITY.md file to your Perl distributions will let people know:

1. How to contact the maintainers if they find a security issue with your software
2. What software will be supported for security issues

The contact point is very important for modules that have been around for a long time and have had several authors over the years. When there is a long list of maintainers, it's not clear who to contact.

You don't want people reporting security vulnerabilities in public on the RT or GitHub issues for your project, nor do you want a post on IRC, Reddit or social media about it.

If your software is on GitHub, you can set up private vulnerability reporting. GitLab has a similar system.

Otherwise, a single email address is acceptable. An alias that forwards to all of the maintainers or at the very least, a single maintainer who has agreed to that role will work.

It's also important to realise as a maintainer that you are not on your own when you receive a vulnerability report. You are welcome and even encouraged to reach out to CPANSec for assistance triaging and fixing the issue, as well as handling notifications and reporting.

The supported software version may seem obvious, but it's important to spell out: will you be updating only the latest version? What versions of Perl will you support? If your module uses or embeds other libraries, how will they be supported?

Fortunately it is not difficult to write a security policy. The CPAN Security Group (CPANSec) has written Guidelines for Adding a Security Policy to Perl Distributions. (Note: I am one of the authors of that document.)

The guidelines include a template for a Perl distribution with a single author that you can use as a basis for your distributions. There is also Software::Security::Policy that will be integrated with build tools in the future to help generate one.

We'd like more people to use the document and provide feedback to CPANSec to improve the advice, and perhaps add alternative templates.

You don't even have to release a new version of your modules immediately. Just adding a SECURITY.md file in the root of the GitHub repo will be helpful enough.

Note: edited for typos.

I’ve released a new module PerlX::Let that adds a new “let” keyword so that you can do the following:

let $x = 1,
     $y = "string" {

  if ( ($a->($y} - $x) > ($b->{$y} + $x) )
  {
    something( $y, $x );
  }

}

with this, you can have lexical readonly variables, and avoid bugs due to typos.

A nice feature of this is that it uses state variables if the assigned value is a constant, and the value is a scalar (for Perls older than 5.28).

A few days ago, I released Const::Exporter to CPAN.

Basically, it's a module that allows you to define a module with exportable constants that:

• can be read-only scalars, arrays, or hashes (as well as the standard constant functions);
• can refer to each other;
• can be grouped into export tags, and added to multiple tags without repeating the value;
• and easily interspersed with POD describing the constants.

A more detailed discussion of it is on my blog /users/robert_rothenberg/module-releases/index.html