How to get listed on CPAN Watch

| 4 Comments

(Note: A permanent page about this is here.)

I've been filtering the full CPAN uploads feed for a few days now and posting the highlights to our CPAN Watch blog. I thought I'd take this opportunity to publicise a few tips on how to get your module listed on CPAN watch.

Do...

  • Include a Changes file. It can be named Changes, CHANGES, ChangeLog, or anything of the kind, just as long as it exists.
  • Document the changes for each release. I can't tell what's changed if you don't tell me.
  • Put your change log in reverse chronological order. This makes it easy to see the most recent change.
  • Give me an easy headline by listing the most significant changes first.
  • Be specific. Don't just say "bugfixes", tell me which bugs in particular.

Don't...

  • Make me go to an external website or Subversion repository to find out what's changed.
  • Refer to "improvements", "new features", or "bugfixes" without explaining what they are.
  • Leave your Changes file completely empty. (Yes, I've seen this!)
  • Release a list of your Subversion commit messages as a change log.

If you follow these guidelines, I'll read your change log and try to determine whether your release is "significant". This is a bit of a fuzzy judgment, but here are some of the guidelines I use:

Significant

  • New features added
  • Major bugfixes
  • Breaking backward compatibility
  • Many changes grouped together, even if each is individually small
  • First release of a major module in some time
  • New release of something that looks to be of broad interest and usefulness

Insignificant

  • Documentation/packaging/test changes
  • Internals-only changes, refactoring, etc.
  • Small changes (eg. one small bug fixed)
  • Developer releases
  • Unauthorized releases

I hope this will help clarify what criteria I use for CPAN Watch. Not surprisingly, these are the same sorts of things potential users of your module look for as well. As time permits, I'll be automating some of this process, so it will be increasingly important for distributions to document their changes in a way I can pick up programatically.

4 Comments

Just what I needed to hear! I'm starting to go down the path of being a CPAN module releaser, so this advice is helpful!

Obviously most of it is obvious, yet it is nice to have a checklist to go over before final packaging and shipping.

*bookmarked*

> Developer releases
> Unauthorized releases

These are actually the most interesting. I often upload a developer version of a module where the API changes to get people's feedback without breaking their apps immediately. Inevitably, nobody checks for the developer release and then whine when I release a stable version 6 months later.

As for "unauthorized releases", there's no such thing. What search.cpan refers to "UNAUTHORIZED RELEASE" should be called "release where the uploader didn't happen to have permission to upload every single module in the distribution at this exact point in time". When that feature was first implemented, nobody has permission to upload DBIx::Class and autarch++ didn't have permission to upload Mason.

Even if the PAUSE permissions don't quite align right, anyone is authorized to release any CPAN module at any time, assuming the package is actually allowed to be on the CPAN. That's the magic of free software, you're allowed to fork it :)

Anyway, my point is that you shouldn't ignore something just because PAUSE doesn't index the dist.

Jrockway: For developer releases, we'd rather people announced them to Project Hum. For "unauthorized" ones, unfortunately there's no easy way for me to look at an upload and tell whether it's really unauthorized or is just CPAN being weird. Therefore I skip them all. If you can advise a straightforward way of telling the difference just by looking at the search.cpan.org page for the release, please let me know.

CPAN Recent Changes might help you.
It provides a CPAN update feed with latest changes.

Job hunting for programmers


Land the Tech Job You Love, Andy Lester's guide to job hunting for programmers and other technical professionals, is available in PDF, ePub and .mobi formats, all DRM-free, as well as good old-fashioned paper.