search.cpan.org prepares to hand documentation to MetaCPAN

Retiring a package documentation site creates a different problem from retiring a package archive. Readers need to find the same documentation, while installation tools need to resolve and retrieve distributions. The Perl NOC announcement of May 16 concerns search.cpan.org. It schedules retirement for June 25 and says traffic will redirect to equivalent MetaCPAN pages after a notice period. That distinction matters to anyone reading the announcement as a change to CPAN itself.

The NOC explains that maintenance has become burdensome and that much of the site runs code from around 2005. Graham Barr originally wrote the service, which went live in early 1999. MetaCPAN now provides a viable replacement, and its team has been preparing for the transition. Those facts describe a transfer of responsibility for a working service, with continuity of access as part of the plan.

I regard CPAN as an important part of what makes Perl useful. Finding an existing distribution and understanding its interface are closely related tasks, but they do not have to run through the same implementation. The handoff makes that separation visible to users who normally experience a search result, a documentation page, and a package installation as one activity.

What the installation client actually does

The CPAN.pm documentation shipped with Perl 5.26.2 describes a client with its own configuration and distribution handling. It documents mirror selection through urllist, local build directories, module dependency information, and installation commands. These are concrete responsibilities beyond displaying a module page in a browser.

For example, the client can help choose mirrors with o conf init urllist. Its documentation describes selection in terms of network proximity, reliability, and how current a mirror is. A browser destination for reading a module does not by itself define those configured download destinations. Treating a search-site replacement as an instruction to rewrite all package retrieval settings would confuse two separate interfaces.

The client also has to distinguish a module name from the distribution containing it. Its documentation says a developer release requires an explicit path beginning with the author identifier to the desired archive. By default, installation selects the latest non-developer release. A documentation link and a request to install a particular archive therefore convey different degrees of version specificity.

That difference is relevant when replacing documentation links. A link used to explain an interface may need to identify a particular release, while a casual lookup may be intended to find the current documentation. Preserving the subject of a link requires understanding which of those purposes it served. Sending every old URL to one generic search form would leave that work to each reader.

The announced plan for equivalent destination pages is consequently an important part of the handoff. It gives the transition a more precise goal than simply keeping a hostname reachable. A reachable address is useful only if it still helps the reader recover the intended module or distribution context.

Documentation and installed code can disagree

CPAN.pm documents a case where installing a newer module still leaves the older version visible. A module can install into a different directory in @INC, leaving another copy earlier in the lookup path. The documentation describes this as a path issue that can also occur with manual installation. The version a reader sees on a website cannot settle which local copy a program loads.

This gives documentation migration a practical limit. Better search and successful redirects help users find published material. They do not inspect a local interpreter or its library path. When a program behaves differently from the page being read, identifying the installed distribution and its location remains part of understanding the discrepancy.

The same client documentation describes why installation can depend on metadata quality. CPAN.pm uses information in META.yml or generated build files to discover prerequisites. Missing declarations can cause installation failure. A later retry may succeed if another installation has supplied the missing dependency in the meantime. Documentation lookup cannot replace that dependency information either.

These distinctions make the ecosystem easier to describe accurately. The archive supplies distributions, the client performs local installation work, and a documentation service helps people understand what those distributions contain. The services cooperate, but each can change without becoming a replacement for every other part.

I prefer a transition framed in those terms. It allows appreciation for the old service without treating its implementation as inseparable from all the package work built around it. Maintaining access to documentation is a substantial responsibility even when it does not include changing how the client builds or installs code.

Continuity includes material outside the website

A documentation URL can appear in a module description, a tutorial, or another project description. Its usefulness extends beyond the page that originally emitted it. That is why the redirect plan affects more than habitual visitors who type the old hostname. A handoff that preserves the destination context reduces the amount of coordination required across independent authors.

CPAN.pm itself demonstrates how documentation records knowledge of the surrounding ecosystem. Its manual links other modules and tools, explains alternatives such as CPANPLUS and cpanminus, and points readers to supporting material. Those references connect separate projects without requiring their maintainers to release on the same schedule. A web-service change has to coexist with already published documentation that cannot all change at once.

There is also a distinction between preserving access and preserving the old user interface. Equivalent destination pages can retain the requested subject while presenting it through another service. Readers may still need to learn a different arrangement of information. The announcement makes the operational case for the handoff, but does not establish that every user will prefer the replacement interface.

The practical scope is clear enough for now. The planned change concerns where users search for and read CPAN documentation, with redirects intended to preserve existing routes to that material. Installation still involves the client configuration, dependency declarations, and local library lookup rules documented by CPAN.pm. Those mechanisms explain why replacing the documentation service does not by itself constitute a package migration.