Re: [opam-devel] Repository format tools

[Daniel BÃnzli <daniel.buenzli@xxxxxxxxxxxx>]

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