Repository format tools

[Anil Madhavapeddy <anil@xxxxxxxxxx>]

A number of us are assembling quite a few repositories for proper open-source 
releases. In particular, between Mirage and Xen, I think we have about 40 to 
work through in the next couple of months.

One thing I'd like to have is some tooling to make it easier to manipulate 
these groups of repositories.  I've started a repository here:

https://github.com/avsm/opam-repo-tools

...which builds an opam-changelog binary that can connect to Github and parses 
the CHANGES file from the repository.  For example:

> $ opam-changelog OCamlPro opam
> 
> 1.0.1
> * By default, turn-on checking of certificates for downloaded dependency 
> archives: use `./configure --disable-certificate-check` to go back to the 
> previous behavior
> * Check the md5sum of downloaded archives when compiling OPAM
> * Improved `opam info` command (more information, non-zero error code when no 
> patterns match)
> * Display OS and OPAM version on internal errors to ease error reporting
> * Fix `opam reinstall` when reinstalling a package wich is a dependency of 
> installed packages (regression introduced in 0.9.5)
> * Export and read `OPAMSWITCH` to be able to call OPAM in different switches
> * `opam-client` can now be used in a toplevel
> * `-n` now means `--no-setup` and not `--no-checksums` anymore
> * Fix stupid typo in detection of FreeBSD archs
> * Fix installation of local compilers with local paths endings with 
> `.../ocaml/`
> 
> 1.0.0
> * Improve the lexer performance (thx to @oandrieu)
> * Fix various typos (thx to @chaudhuri)
> * Fix build issue (thx to @avsm)
> 

I wanted to find out what else people want.  I'd like to know:

* README: What a repository is for
* TODO: "There be dragons here"
* CONTRIBUTING: Guidelines for sending pull requests, see 
https://github.com/blog/1184-contributing-guidelines
* CHANGES: See above -- this would be particularly useful to display after an 
OPAM update, for example.

Some of these are subsumed by various metadata files such as _oasis, but not 
all the repositories use OASIS, so I'd prefer simple text files in Markdown 
where possible.

So, does anyone have any strong opinions on this?  I'm inclined to go for the 
simple CHANGES format that OPAM currently uses (and several Mirage libraries).  
But I also notice the Debian changelog format is quite simple and we could 
adopt that: http://www.debian.org/doc/debian-policy/ch-source.html

     package (version) distribution(s); urgency=urgency
     [optional blank line(s), stripped]
       * change details
       more change details    
       [blank line(s), included in output of dpkg-parsechangelog]
       * even more change details
     [optional blank line(s), stripped]
      -- maintainer name <email address>[two spaces]  date


-anil