NEILB's Blog

We recently established an informal metadata standard for marking a distribution as deprecated, using the x_deprecated key. This is useful when automatically processing distributions, rather than pattern matching on the word 'deprecated' and variants. MetaCPAN will probably visually identify a distribution as deprecated based on this metadata. Here I'll describe how to add this to a distribution, using some of the distribution builders.

The discussion for this was held on the #toolchain channel, and involved DAGOLDEN, LEONT, ETHER, ETJ, and probably others that I've forgotten.

Added the field to your distribution just requires setting one field:

x_deprecated: 1

If this is part of the distribution's metadata, then it will be available via the MetaCPAN API. For example, if you look at this release:

HTTP-Headers-UserAgent

Search for x_deprecated, and you'll see it's set to 1.

Marking a distribution as deprecated

If you want to mark a distribution as deprecated:

• Add the text "(DEPRECATED)" to the abstract
• Make this clear in the first paragraph of the DESCRIPTION section.
• If there are other modules than can be used in place of this one, list them in the DESCRIPTION as well as the SEE ALSO section.
• Set the x_deprecated field to 1.

Adding the metadata with Dist::Zilla

If you're using Dist::Zilla, then ETHER has made it very easy, releasing a plugin which adds this to your dist's metadata. Just add the following to your dist.ini:

[Deprecated]

Adding the metadata with ExtUtils::MakeMaker

If your dist has a Makefile.PL based on ExtUtils::MakeMaker, then you can add the key to your metadata using META_MERGE:

META_MERGE => {
    x_deprecated => 1,
    # whatever else you already have here
},

Assuming your repo doesn't contain META.yml, then when you run make dist, you'll get a META.yml which contains this.

Adding the metadata with Module::Build

If your dist has a Build.PL based on Module::Build, then you can add the key to your metadata using meta_merge:

my $builder = Module::Build->new(
    module_name    => 'Foo::Bar',
    meta_merge   => {
        x_deprecated => 1,
        # other stuff
    },
    # ...
);

$builder->create_build_script();

Adding the metadata with Module::Install

If your dist uses Module::Install, then you just need the following line:

add_metadata x_deprecated => 1;

Thanks to Mark Lawrence for that.

Other dist builders

I'll add details for other dist builders as I work them out, or as other people tell me...

Deprecating a module, not the whole dist

The discussion also covered how to deprecate a single module without deprecating the containing distribution: Put the x_deprecated key inside the provides hash for the particular module(s). Maybe someone else will cover that somewhere?

PR Challenge

For the CPAN Pull Request challenge I'm going to add a +1 to the suitability score for a distribution if the abstract appears to mark it as deprecated, but the metadata doesn't contain the x_deprecated key.

If a distribution does have the x_deprecated key set to a true value, I'll exclude it as a candidate for assignment.