NEILB's Blog

I think it would be helpful to establish (more of) a convention for recording your todo list for a distribution with the distribution itself. Some dists already have a TODO file. I can't find any proposed conventions for this (eg in Perl Best Practices), so how about we say it's markdown, call it TODO.md, and get MetaCPAN to present it on a distribution's home page, like it does for the Changes in the most recent release?

With the 24 pull requests challenge, and the 2015 CPAN pull request challenge we could help prospective pull requesters by recording our ideas for our distributions.

This might make it more likely that people will do pull requests, and more likely that you'll get PRs aligned with your idea of the future of your module.

This would be a file called TODO.md in the top level of your distribution, written in markdown. A minimal todo list would just contain markdown bullets:

* Work out what the hell's going on with ETHER's bug (RT#96433).
* Add tests for all the different permutations with symlinks
* Full test coverage with Devel::Cover

If you want more structure, you could just have sections, with markdown headers:

# Script

* Add more command-line options
* Should probably add some tests

# Modules

* Get test coverage up
* Add a SEE ALSO section
* Create some examples

If MetaCPAN sees this file, it could put a link in the left sidebar, and possibly also put it at the bottom of the distribution's page, just below where it puts the latest section of your Changes file. It would auto-link the RT issue references. Maybe GH#1234 for GitHub issues?

When you've done everything in your todo list, I think you should delete the file from the dist, but MetaCPAN could also ignore empty files.

Some dists already have a file called TODO, and others have TODO.pod, and there are probably others as well. Of course could go for a more complicated spec like:

• You can have TODO.md, TODO.pod, TODO.txt, or TODO.
• If the latter, then we could try and guess the right format, falling back on 'plain text'.

But given that most todo lists are just going to be a handful of bullets, I think we should go for the simplest thing that will be useful. That makes life easier for new authors, and for tool writers, both of which make it more likely people will adopt the convention. Here's what the pod version of that simple todo list looks like:

=over 4

=item * Work out what the hell's going on with ETHER's bug (RT#96433).

=item * Add tests for all the different permutations with symlinks

=item * Full test coverage with Devel::Cover

=back

Markdown bullets are very easy to read in the raw, and this way github will also present them nicely for you.

Obviously there's some overlap here with RT / github issues, but in my experience most authors don't put their ideas for future work in the bugtracker. Plus there are multiple bug-trackers in use, and MetaCPAN doesn't present their contents inline (for good reason).

Another way of thinking about the file is "these are pull requests I'd be happy to receive" — that's what started me thinking about it.

I was tempted to just add some TODO.md files to some of my distributions and send a pull request for MetaCPAN, but figured I should give a chance for others to chip in, before I start hacking (or try and inspire someone else to :-)