How to get listed on CPAN Watch

The CPAN Watch blog is designed to keep you informed about what's new and interesting on the CPAN. As we search the full CPAN uploads feed, we look for certain things to help us decide if the release is noteworthy. You can help potential users, and us, more easily tell what your module is all about.

Do...

• Think like a new person seeing your module for the first time. Stand back and look at it from a distance, not as the author.
• Explain what the module does, without assuming that the reader knows what you're talking about. Explain why you would want to use the module at all.
• 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. We can't tell what's changed if you don't tell us, and neither can your users.
• 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. Summarize it.

If you follow these guidelines, we'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 we 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 (although they may get mentioned over in Project Hum)

I hope this will help clarify what criteria we 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.