├── LICENSE └── README.md /LICENSE: -------------------------------------------------------------------------------- 1 | MIT License 2 | 3 | Copyright (c) 2019 Tina Müller (tinita) 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE. 22 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Perl5 Module Meta - Best Practices 2 | 3 | This is a collection of things that help making your CPAN module "portable" 4 | with regard to metadata. 5 | 6 | CPAN/PAUSE itself is not very strict about these things. But turning a module 7 | into an RPM or Debian package for example can be hard if it is missing 8 | meta data. 9 | 10 | People maintaining `rpm` or `deb` repositories for perl often have to do a lot 11 | of manual work, although theoretically most of it can be automated. 12 | 13 | ## Table of Contents 14 | 15 | * [Versions](#Versions) - Use a consistent versioning scheme 16 | * [Description](#Description) - Create a useful description 17 | * [Archive filename](#Archive-filename) - Create a correct archive 18 | * [`.` in `@INC`](#INC) - The current directory `.` is not in `@INC` 19 | * [Changelog](#Changelog) - Use a common filename and format 20 | * [License](#License) - Correctly specify license 21 | * [Dependencies](#Dependencies) - Specify all dependencies 22 | * [Shebang](#Shebang) - Use a portable shebang for scripts 23 | * [MANIFEST](#MANIFEST) - Exclude certain files from your archive 24 | * [Bugtracker](#Bugtracker) - Specify URL to Bugtracker 25 | * [Tests](#Tests) - Make sure tests are passing everywhere 26 | * [Installer](#Installer) 27 | * [Author Tests](#Author-Tests) - Useful Author tests 28 | * [Other Resources](#Other-Resources) 29 | 30 | ## Versions 31 | 32 | ### Use a consistent versioning scheme 33 | 34 | The short story: Always use the same amount of digits after the major version. 35 | 36 | The long story: 37 | 38 | Perl versions are different from common versioning schemes. 39 | 40 | In Perl, the version `1.1901` is semantically equal to `v1.190.100`, 41 | and `1.20` to `v1.200`. 42 | 43 | So it can happen that a CPAN module was released with version `1.1901`, and 44 | a year later a new version `1.20` is released. For perl, the new version is 45 | bigger. 46 | 47 | If vendors want to turn the module into an `rpm` or `deb`, they would have to 48 | turn the version into `1.190.100`/`1.200` to be correct. The only disadvantage 49 | is that the version may not look the same as the original CPAN version anymore. 50 | 51 | But if they take the version as it is, then `1.190` is bigger than the following 52 | `1.20`. 53 | 54 | Make it easier for vendors and always use the same amounts of digits. If you want 55 | to change to a different versioning scheme, then at least change the major 56 | version before. 57 | 58 | Use the same distribution version everywhere (`META.*` files, `Makefile.PL`, 59 | archive name, Changelog). 60 | 61 | ### Do not reuse versions 62 | 63 | Always increase the version for a new upload and do not reuse the same version. 64 | 65 | Also have a look at Grinnz' [Guide to Versions in 66 | Perl](http://blogs.perl.org/users/grinnz/2018/04/a-guide-to-versions-in-perl.html). 67 | 68 | ## Description 69 | 70 | Every module should have a `DESCRIPTION` section in the pod documentation. 71 | 72 | =head1 NAME 73 | 74 | Module::Name - Abstract 75 | 76 | =head1 SYNOPSIS 77 | 78 | use Module::Name; 79 | # example code 80 | 81 | =head1 DESCRIPTION 82 | 83 | A few paragraphs with a description of your module. 84 | 85 | This description is usually what ends up in the vendor package description. 86 | Don't make it too long and create extra headers for more specific parts. 87 | 88 | Also check for spelling mistakes. See [Author Tests](#Author-Tests). 89 | 90 | ## Archive filename 91 | 92 | The filename you upload should match the distribution name and version, e.g. 93 | 94 | Your-Module-1.23.tar.gz 95 | Your-Module-1.23.zip 96 | Your-Module-v1.23.tar.gz 97 | Your-Module-v1.23.zip 98 | 99 | `tgz` and `tar.bz2` might also work. 100 | 101 | The archive should unpack to `Your-Module-version`. Do not omit the version. 102 | If people unpack different versions of your module, they should not end up 103 | in the same directory. 104 | 105 | The contents of the module should be in the top folder of the archive, e.g. 106 | 107 | Your-Module-1.23/ 108 | lib/Your/Module.pm 109 | t/... 110 | LICENSE 111 | Makefile.PL 112 | 113 | ## `@INC` 114 | 115 | In perl 5.26, the current directory `.` was removed from `@INC`. Make sure 116 | you don't rely on `.`, for example when using `Module::Install`, or when 117 | using modules in your test directory. 118 | 119 | Don't use 120 | 121 | use t::lib::Some::Module; 122 | 123 | Instead do: 124 | 125 | use lib 't/lib'; 126 | use Some::Module; 127 | 128 | Or: 129 | 130 | use FindBin '$Bin'; 131 | use lib "$Bin/lib"; 132 | use Some::Module; 133 | 134 | ## Changelog 135 | 136 | Use a common format and filename for your changelog file. The most common filename 137 | is `Changes`. 138 | 139 | For vendors to be able to parse the file, use a format like this: 140 | 141 | 1.23 2019-11-02 12:34:56+02:00 142 | 143 | - Bug fix: ... 144 | - New Feature: ... 145 | 146 | The version should exactly match the version of the distribution. 147 | 148 | Newer versions should be above older versions. 149 | 150 | If you fixed a bug that was reported in an issue, mention the issue. 151 | Vendors often create local patches for modules and, if they have time, create 152 | an issue. 153 | If you fixed the issue and mention it in the changelog, vendors can more 154 | easily remove outdated patches. 155 | 156 | 157 | ## License 158 | 159 | The license should appear ideally in four places: 160 | 161 | * META.json 162 | * META.yml 163 | * LICENSE file 164 | * The pod documentation of your main module 165 | 166 | ## Dependencies 167 | 168 | List *all* dependencies. The list of modules contained in core may change over 169 | time. It's best to include all dependencies including the ones that are 170 | currently in core. 171 | 172 | If possible, add the minimum required version of the dependency. For example, 173 | when using `Test::More::done_testing()`, require `Test::More` version `0.88`, 174 | as it was added in this version. 175 | 176 | Also don't forget to specify the minimum perl version. 177 | 178 | Also have a look at Neil's [Specifying dependencies for your CPAN 179 | distribution](http://blogs.perl.org/users/neilb/2017/05/specifying-dependencies-for-your-cpan-distribution.html). 180 | 181 | ### Non-perl dependencies 182 | 183 | If your module needs an external library, there is currently no way to specify 184 | this in `META.json`/`META.yml`. But you can help vendors by documenting 185 | the external libaries your module needs in pod. 186 | 187 | ## Shebang 188 | 189 | The first line of any perl scripts included in your distribution, especially 190 | the ones that will be installed, should look like that: 191 | 192 | #!/usr/bin/perl 193 | 194 | When the module is installed, this line will be automatically replaced with 195 | the path to perl that was used for building. 196 | 197 | Alternatively `#!perl` should also work. 198 | 199 | Note that if you use 200 | 201 | #!/usr/bin/env perl 202 | 203 | the line is currently not rewritten. See 204 | [Perl-Toolchain-Gang/ExtUtils-MakeMaker#58](https://github.com/Perl-Toolchain-Gang/ExtUtils-MakeMaker/issues/58) 205 | for a discussion on this. If the line is not rewritten and your installed 206 | script is executed with a different perl, this can lead to problems, for example 207 | dependencies will not be found. 208 | 209 | ## MANIFEST 210 | 211 | Make sure to not include files in your archive that don't belong there, 212 | like editor backup files (`.swp`), the `.git` folder, forgotten tarballs. 213 | 214 | Usually build tools will skip files listed in `MANIFEST.SKIP`. 215 | 216 | ## Bugtracker 217 | 218 | If your repository is hosted at a site like GitHub or BitBucket, and you are 219 | using the bugtracker it provides, add the URL to the bugtracker in the 220 | `META.json/META.yml`. That makes it easier for people to find existing 221 | and file new bugs. 222 | 223 | ## Tests 224 | 225 | Regularly look at the CPAN Testers site (linked from your module page on MetaCPAN) 226 | to see if there are any test failures. 227 | 228 | If possible, don't rely on a working network and mock network operations. 229 | 230 | Don't rely on a fixed order of hash keys. 231 | 232 | Tests should not create or alter files in the distribution. 233 | If you have to create files for tests, delete them at the end. 234 | 235 | This can be done in an `END` block, so the files will be deleted also when 236 | a test fails and exits unexpectedly. 237 | 238 | use File::Path 'rmtree'; 239 | ... 240 | END { 241 | rmtree "/path/to/temporary/testfiles"; 242 | } 243 | 244 | ## Installer 245 | 246 | Don't prompt for input in the install process, for example in `Makefile.PL` or 247 | `Build.PL`. This will break automatic installations. 248 | If you need a prompt, use `ExtUtils::MakeMaker::prompt()`, as it will detect 249 | if it's running interactively or not and use a default. 250 | 251 | ## Author Tests 252 | 253 | There are a number of Test modules that help you avoiding some of the mentioned 254 | issues. 255 | 256 | * [Test::Pod](https://metacpan.org/pod/Test::Pod) - Check for correct POD 257 | * [Test::Spelling](https://metacpan.org/pod/Test::Spelling) - Check for spelling mistakes in POD 258 | * [Test::CPAN::Meta](https://metacpan.org/pod/Test::CPAN::Meta) - Validate `META.yml` 259 | * [Test::Kwalitee](https://metacpan.org/pod/Test::Kwalitee) - Includes a number of different checks 260 | * [Test::CheckChanges](https://metacpan.org/pod/Test::CheckChanges) - Check that the Changes file matches the distribution 261 | * [Test::CPAN::Changes](https://metacpan.org/pod/Test::CPAN::Changes) - Check format of Changes file 262 | 263 | Place them in the `xt/` directory so they are not run by default. They 264 | should be run by the author before releasing. 265 | 266 | ## Other resources 267 | 268 | ### openSUSE 269 | 270 | You can find a lot of CPAN modules in the [devel:languages:perl](https://build.opensuse.org/project/show/devel:languages:perl) 271 | repository of openSUSE Build Service (OBS). 272 | 273 | Look if you can find your module there. Maybe you'll find out that it contains 274 | local patches. 275 | 276 | The most used tool to create `.spec` files for CPAN modules is 277 | [cpanspec](https://github.com/openSUSE/cpanspec). It can use a `cpanspec.yml` 278 | file for any changes necessary to make the module build successfully. 279 | 280 | You will also see a lot of modules not using `cpanspec.yml` yet. The spec was 281 | probably created manually. 282 | 283 | The `cpanspec.yml` can be used for adding forgotten dependencies, but also for 284 | non-perl dependencies, like you can see in the 285 | [Gtk3](https://build.opensuse.org/package/show/devel:languages:perl/perl-Gtk3) 286 | distribution. 287 | 288 | `cpanspec` is not perfect, and OBS maintainers will be glad for help in making 289 | it handle more distributions correctly. 290 | 291 | ### Debian 292 | 293 | See the [Debian Perl Group](https://perl-team.pages.debian.net/) 294 | 295 | * List of [perl modules maintained by the Debian Perl 296 | Group](https://salsa.debian.org/perl-team/modules/packages) 297 | * [Debian Package Tracker](https://tracker.debian.org/teams/pkg-perl/) 298 | * [How to request a package](https://perl-team.pages.debian.net/howto/RFP.html) 299 | * Presentation [From Debian, with ♥](https://perl-team.pages.debian.net/docs/yapc-europe-2016/from_debian_with_love.pdf) 300 | 301 | The tool to create debian packages from Perl modules is 302 | [dh-make-perl](https://salsa.debian.org/perl-team/modules/packages/dh-make-perl). 303 | 304 | ### Fedora 305 | 306 | [List of perl packages](https://apps.fedoraproject.org/packages/s/perl) 307 | 308 | 309 | --------------------------------------------------------------------------------