Re: [opam-devel] Repository format tools

[Anil Madhavapeddy <anil@xxxxxxxxxx>]

On 30 Mar 2013, at 15:08, Daniel Bünzli <daniel.buenzli@xxxxxxxxxxxx> 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