[opam-devel] Repository format tools

[Daniel Bünzli]

Le jeudi, 28 mars 2013 à 17:42, Anil Madhavapeddy a écrit :

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

I also sometimes add a DEVEL file for developer instructions (e.g. https://github.com/dbuenzli/uunf/blob/master/DEVEL). Do you think this should go in CONTRIBUTING ? (I'd still prefer DEVEL it's less intrusive when you `ls`).  

> 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.
Seems a good idea to me. I currently use the metadata of _oasis to generate my READMEs, but it is suboptimal on github. The thing is that I don't want to repeat myself. Maybe the extraction should be done the other way round.  
   
> 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).

I think it should be tweaked to at least:

1) Be fully markdown renderable. That means I'd use proper sections (#) for releases.

2) Use the yyyy-mm-dd time stamp format (rfc 3339). This format has a lot of good properties (e.g. ascii order gives you time order, clear month vs day order, etc.).  

3) (That's really a pointless obsession of mine) I like to give the physical location I'm in when I release. For me it gives a little human touch to all these virtual bits.

Example, https://github.com/dbuenzli/xmlm/blob/master/CHANGES (with a release made from 大足县…, I can precisely remember that hotel room with a good wired connection, worked on Vg for a few days there).

Best,

Daniel