[CF-metadata] Proposals for Versioning CF Conventions and Standard Names on Github

From: Jonathan Gregory <j.m.gregory>
Date: Wed, 24 Sep 2014 13:23:37 +0100

Dear Chris, Stephen, et al.

Thanks for your helpful explanations. That helps me to understand.

> 3) We move discussion to gitHub issues, rather than TRAC tickets.
If git has a way to carry out a discussion in public like trac, in which
everyone's contributions are recorded and public and submitted in plain
text, but offers other useful features too, that's worth considering.

> 4) We use somethign other than DocBook XML for the document - XML does not
> lend itself to an SCM, and non-experts editing the doc.

If a different format would be better for generating the final documents
in various forms, and is easy to work with, it is worth considering, but ...

> 1) We manage the development of the CF-2.x.x document in a source code
> management system, much like a software project
> 2) ... the whole fork-pull-request thing for updating the document.

I don't think this is appropriate, and I don't think contributors in general
need to edit the document. The convention is a document, not a collection of
source code files. The trac tickets are mostly about how and why to modify it,
illustrated by the proposed change. That is different from software, in which
the modified code speaks for itself (to some extent), and is accompanied by
much shorter descriptions of how and why it is has been modified. Also the CF
doc is a *single* document, so there isn't the need to keep lots of files
consistent when making updates. It *could* be broken into lots of documents,
but I don't see an advantage in that.

I think that the difficulty in updating the document is not that we have
inconvenient software for doing and facilitating it. It is the intellectual
difficulty of working out what the changes should be that makes the process
slow. When we have agreed a ticket, enacting it in the doc should be simple.
That is happpening slowly now, I presume, because of lack of person-time to
do it, rather than that the software is awkward. It could be helped perhaps
if volunteers could do it (as Mark Hedley suggested quite a while ago) but
there would still be the need for quality-control - someone would have to
take responsibility for checking that the change was as agreed.

Best wishes

Jonathan
Received on Wed Sep 24 2014 - 06:23:37 BST