First, to my knowledge the existing 1.6 and 1.7 are in Markdown already. I thought that was settled? And the standard names are in XML, and that is settled.
Then, I wasn't sure if Rich's proposal was with respect to the 1.x/2.x division? Or is it only about the documents inside CF currently? We can deal with the latter point first, but overall we should consider the advantages going forward as well.
Rich, before answering Jonathan's question, I want to test one of your strategies. You say
> Since we have two different version tracked documents (the CF Standard Name list and the CF Conventions document), we should have two different repositories. Then for each repository, instead of multiple entire documents tracked separately, we should have just evolving document that can be tagged with release numbers when specific versions are approved.
I'm not a git guru, but it is often the case that Git repositories contain multiple tracked documents in a single repository. Their changes are still managed independently, on separate branches, unless the changes are tightly coupled. (Note there are more tracked documents than just those two, CF has several vocabularies that also should be tracked as part of the standard.)
So I want to refine your proposal to say yes, let's use branches, but not to split out the pieces of the standard into separate repositories. The overhead in maintaining repositories will be high and the benefit low.
But I think the original idea to use Git branches has merit, and may be what the other responders were agreeing with. To refine that argument:
Imagine that any trac ticket discussion could be accompanied by a version of the standard that showed the proposal under discussion (or, if there were multiple proposals under discussion, there could be 3 versions). These versions can be modified to reflect updates in the proposals -- and can also be updated to stay aligned with changes in the baseline 1.x document. Changes between any two versions (the original and a proposed version, two proposed versions, or the last and current revision of a proposed version) can be easily identified with the diff utilities in git.
As new variants get spawned or old ones deposed, the github branches are created or removed accordingly. Anyone using git can have their own fork on their own computer, which then constantly follows the current state of play of the proposed versions.
For complex changes involving multiple parts of the standard, it will be really handy to be able to see all the proposed changes 'live' in one document. Even more so when the baseline 1.x document is changing, and those changes can be trivially incorporated (where appropriate) into the 2.x versions.
John
On Sep 22, 2014, at 10:11, Jonathan Gregory <j.m.gregory at reading.ac.uk> wrote:
> Dear Rich
>
>> One of the reasons for moving the CF Conventions and Standard Names to
>> Github was so that the community could help support CF development.
>>
>> The github fork/branch/pull-request process allows contributors to
>> submit changes that can be discussed, modified, discussed some more
>> and then eventually approved with the click of a button, taking the
>> burden off of one or two people to make all the changes while leaving
>> the current approval process intact.
>
> I'd like to understand better how these processes will interact. We have trac
> tickets to propose changes and to correct mistakes. By the time the trac
> ticket is concluded, it should state exactly what textual changes are going
> to be made. All that then remains is to make these changes in the document.
> That is, there is no need for discussion, modification or approval in the
> github process, as far as I can see, because there is nothing left to be
> discussed or approved once the "current approval process" on trac has been
> finished, except for proof-reading the changes to make sure they were made
> exactly according to the trac ticket. Is that what you mean?
>
> It might be suggested that we don't need defect tickets if corrections can
> be proposed through github. However, I think we do still need them, because
> it is not always obvious whether something is actually a mistake. One person
> might think they are proposing a correction, whereas another might regard it
> as a material change. Such discussions have occurred on trac defect tickets,
> so I think we still need that process.
>
> Best wishes
>
> Jonathan
> _______________________________________________
> CF-metadata mailing list
> CF-metadata at cgd.ucar.edu
> http://mailman.cgd.ucar.edu/mailman/listinfo/cf-metadata
Received on Mon Sep 22 2014 - 12:29:20 BST
