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
and get MetaCPAN to present it on a distribution's home page,
like it does for the Changes in the most recent release?
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.
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
and there are probably others as well.
Of course could go for a more complicated spec like:
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 :-)