[opam-devel] Repository format tools

[Anil Madhavapeddy]

On 30 Mar 2013, at 15:08, Daniel Bünzli <daniel.buenzli at erratique.ch> wrote:
> 
> 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`).

CONTRIBUTING is used by Github to add help to a pull request, so it's not quite the same as DEVEL.  I like the idea of a file that tells you how to build and hack on a repository -- for instance, which the recommended build system is, what autogenerated files will present (e.g. from ATDgen) and so forth.

I'll add DEVEL to the skeleton repository...

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

Unfortunately, not all projects can use OASIS for various reasons, usually because they are large repositories that use OMake and need the faster build speed, or have special compilation requirements (some of the Mirage ones).

I agree this all needs to converge, but it'll take some time...

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

Yeah, this is easily parseable too. Thomas, any objections to using something like this for OPAM and friends?  We'd need to call the file 'CHANGES.md' so that Github will render it as a Markdown file.


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

Heh, I once correlated the GPS traces from my phone to my Git commit times to figure out where I was most productive writing code (answer: Ray's Jazz Cafe at Foyles).

Anything after the version and header would ben fine to leave as user-defined metadata in our format then.  I agree that having a Markdown format is probably better than the Debian metadata.

-anil