How to get listed on CPAN Watch

(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.