Re: [CF Metadata] #160: Proposal to use GitHub instead of trac

[CF Metadata]

#160: Proposal to use GitHub instead of trac
-+--
  Reporter:  jonathan|  Owner:  cf-conventions@…
  Type:  task| Status:  new
  Priority:  medium  |  Milestone:
 Component:  cf-conventions  |Version:
Resolution:  |   Keywords:
-+--

Comment (by jonathan):

 Dear David

 I agree. I think that we should first agree the procedure for using
 !GitHub as an alternative to Trac for proposing and agreeing changes to
 the convention. Each proposal should start either with a new !GitHub issue
 (or maybe a pull request if it is a typo) or a new Trac ticket, and should
 stay in that issue or ticket until it is concluded (unless the proposal
 itself splits up into several things).

 Since this began as a ticket, maybe the changes in the rules (using Dave's
 text) should be finally agreed in this ticket?

 Best wishes

 Jonathan

--
Ticket URL: 
CF Metadata 
CF Metadata

Re: [CF Metadata] #160: Proposal to use GitHub instead of trac

[CF Metadata]

#160: Proposal to use GitHub instead of trac
-+--
  Reporter:  jonathan|  Owner:  cf-conventions@…
  Type:  task| Status:  new
  Priority:  medium  |  Milestone:
 Component:  cf-conventions  |Version:
Resolution:  |   Keywords:
-+--

Comment (by davidhassell):

 Hello,

 At this weeks CF meeting, I think it fair to say that everyone was in
 favour of moving change proposals to github, but there was no agreed
 concensus to on how to implement this. This is all good, and a step
 forward - various usage patterns were proposed which we need to consider
 for our official guidelines.

 However, I am concerned that Trac is being sidelined before we have
 decided on how to we want use github:

 * Github issues that are being created that have the same numbers as
 existing track issues.

 * The discussion of one Trac ticket (#155) has been copied, mid-way, to
 github issue 132 [https://github.com/cf-convention/cf-
 conventions/issues/132]

 * Pull requests exist for which there are no Trac tickets nor github
 issues.

 I would like to '''suggest that we continue to use Trac''' until we know
 how we are going to use and manage the proposals process on github.

 Comments welcome, as ever,

 David

--
Ticket URL: 
CF Metadata 
CF Metadata

Re: [CF Metadata] #160: Proposal to use GitHub instead of trac

[CF Metadata]

#160: Proposal to use GitHub instead of trac
-+--
  Reporter:  jonathan|  Owner:  cf-conventions@…
  Type:  task| Status:  new
  Priority:  medium  |  Milestone:
 Component:  cf-conventions  |Version:
Resolution:  |   Keywords:
-+--

Comment (by jonathan):

 Dear all

 Dave Blodgett has posted his proposed simple geometries convention as a
 !GitHub issue at  https://github.com/cf-convention/cf-
 conventions/pull/109. This is a good example for us. I would like to make
 detailed suggestions on his text, as we do on trac tickets, but I'm not
 sure how to go about it. This is what I have commented on !GitHub.

   Thanks for doing this. I think it's in pretty good shape but I have
 quite a few detailed comments and suggestions to make, nearly all on the
 proposed text rather than the convention itself. I'm not sure how to do
 that in !GitHub, so it's a useful exercise to see how this would work. If
 your proposal was in trac, I would reply to your posting on the ticket,
 edit the wiki-markup text to show my changes and suggestions for the parts
 affected, and repost it to the trac ticket. If it was on a wiki, I would
 make a copy of it on the wiki page, and edit it similarly.

   The way !GitHub is set up, I suppose the natural way to do it is to make
 a new branch and edit that, but (a) I don't know how to do that, (b) it's
 not obvious to me that the changes I suggested would be clear to you. In
 fact I find the proposal in this form not as easy to follow as it would be
 in trac. I can view it as deltas of the files, but these have little
 context and are hard to read as text because the markup isn't translated,
 or I can read the properly rendered modified files, but these don't show
 what's been changed, and of course they show much more that isn't
 affected, and it's several different complete files.

   So I'm inclined to think that it would be easier to use !GitHub issues
 in the same way as we use trac. That is, you would post your entire text
 to the "issue". Then I presume I could copy your posting and edit it, as
 in trac. Unfortunately, the markup isn't the same, is it - the issues use
 markdown, I believe, whereas the convention text uses !AsciiDoc. This is a
 technical obstacle. Is there an automatic translator? If not, once the
 text is agreed, it would have to be manually transposed into the
 conventions document, as we have been doing from trac.

 I wonder if people could comment on these issues about how to use !GitHub,
 in view of its relevance to this ticket. (If you want to comment on Dave's
 proposal, that would belong on the !GitHub issue.)

 Best wishes

 Jonathan

--
Ticket URL: 
CF Metadata 
CF Metadata

Re: [CF Metadata] #160: Proposal to use GitHub instead of trac

[CF Metadata]

#160: Proposal to use GitHub instead of trac
-+--
  Reporter:  jonathan|  Owner:  cf-conventions@…
  Type:  task| Status:  new
  Priority:  medium  |  Milestone:
 Component:  cf-conventions  |Version:
Resolution:  |   Keywords:
-+--

Comment (by apamment):

 I've been following the discussion in this ticket with interest.

 I support the move to Github as a forum to manage proposals for changes to
 the conventions document. Since the document now resides on Github, along
 with the pages that form the CF website, there seems little reason to
 retain trac as an additional technology for discussing issues. Signing up
 for a Github account is a very simple process and one does not need to be
 an expert in git/Github to open issues or comment on them. Considering
 that the discussions tend to involve a relatively small number of
 contributors I think it is reasonable to ask them to obtain a Github
 account for this purpose.

 I use git/Github in a simple way to keep the standard name table up to
 date, but have no real experience of using branches. I'm not sure whether
 using branches would make managing the document easier or more difficult
 in the long run. Would we end up with a lot of overlapping changes that
 require manual merging thus making the process of editing the document
 more complicated that it need be?

 I'm opposed to the suggestion that we move standard name discussions to
 Github. There are a number of reasons for this:[[BR]]
 1) Anyone can search for a public Github repository and see associated
 issues. However, if one tries to open a new issue or comment on an
 existing one Github asks the user to log in or create an account. It is
 not uncommon for someone who is very new to CF to propose just one or two
 new names. Asking them to create a Github account in order to do this is
 overkill and will frighten some people away. Similarly, someone who wants
 to contribute a single comment to a discussion (and this does happen on
 the mailing list) should not be expected to create a Github account.[[BR]]
 2) Many of the people who propose names are primarily scientists, not
 developers. I know that Github is currently the version control tool of
 choice for many software developers, but many scientists have never heard
 of it. For example, I recently helped to teach a course to environmental
 science PhD students in which git version control was one of the topics.
 At the start of the week only five or six people out of a group of thirty-
 seven had even heard of Github, let alone used it.[[BR]]
 3) Often something that starts on the mailing list as a general discussion
 along the lines of “how do I do X in CF?” then leads to proposals for a
 few standard names. Recent mailing list discussions on “day of year” and
 “tripolar grids” are examples of this. I don't think it's sensible to make
 people switch from the mailing list to Github issues half way through a
 discussion as that just spreads the information across multiple sources
 making it harder to follow, not easier.[[BR]]
 4) Discussing standard names as Github issues offers no practical
 advantage compared to discussing them on the CF mailing list. My primary
 tool for preparing updates to the standard name table is not in fact
 git/Github but the CEDA vocabulary editor. This is software written in
 Python, using Django to create web pages, and sitting on top of a database
 containing the standard name proposals and the “standard phrases” that are
 used to form the definition text. This software produces the standard
 names status pages linked from the CF website on the Discussion and
 Standard Names pages, e.g.
 
[http://cfeditor.ceda.ac.uk/proposals/1?status=active===+and+display=filter].
 I use the editor to keep track of all proposals and report their status,
 to generate the xml file that gets uploaded to the CF website and also to
 generate files in a format suitable for uploading the standard names to
 the NERC vocabulary server. When I  generate a new version of the xml
 standard name table I commit to my local git repository (containing a copy
 of the CF website) and then push to Github, but this is only the final
 step in a more complex process.

 I remember having a conversation very similar to this one when we started
 using trac and some people thought standard names ought to be proposed in
 trac tickets. My arguments then were pretty much the same as above. Now we
 are talking about dropping trac so I'm glad we kept standard names on the
 mailing list and I think we should continue to do so.

--
Ticket URL: 
CF Metadata 
CF Metadata

Re: [CF Metadata] #160: Proposal to use GitHub instead of trac

[CF Metadata]

#160: Proposal to use GitHub instead of trac
-+--
  Reporter:  jonathan|  Owner:  cf-conventions@…
  Type:  task| Status:  new
  Priority:  medium  |  Milestone:
 Component:  cf-conventions  |Version:
Resolution:  |   Keywords:
-+--

Comment (by jonathan):

 Dear Ethan

 To clarify this point: I think the situation would be much like now, in
 which all subscribers to the CF email list receive updates to trac tickets
 by email, but they cannot post updates to trac by email. It seems that
 this hasn't caused confusion; people have very rarely replied to the email
 list about trac tickets.

 Cheers

 Jonathan

--
Ticket URL: 
CF Metadata 
CF Metadata

Re: [CF Metadata] #160: Proposal to use GitHub instead of trac

[CF Metadata]

#160: Proposal to use GitHub instead of trac
-+--
  Reporter:  jonathan|  Owner:  cf-conventions@…
  Type:  task| Status:  new
  Priority:  medium  |  Milestone:
 Component:  cf-conventions  |Version:
Resolution:  |   Keywords:
-+--

Comment (by jonathan):

 Dear all

 I too think it's important to forward the !GitHub notifications to the
 email list. Otherwise there are many people who would never be made aware
 that a conventions change was under discussion. It's important that these
 should be brought to everyone's attention. Jeff suggested that people who
 really did not want to see contributions to conventions discussions could
 suppress them by using email filters, but at the moment CF mailing list
 subscribers receive them and no-one has asked to opt out.

 I think we should retain the mailing list for unstructured discussions,
 and for standard name proposals, at least for the moment.

 More views are welcome on this ticket.

 Best wishes

 Jonathan

--
Ticket URL: 
CF Metadata 
CF Metadata

Re: [CF Metadata] #160: Proposal to use GitHub instead of trac

[CF Metadata]

#160: Proposal to use GitHub instead of trac
-+--
  Reporter:  jonathan|  Owner:  cf-conventions@…
  Type:  task| Status:  new
  Priority:  medium  |  Milestone:
 Component:  cf-conventions  |Version:
Resolution:  |   Keywords:
-+--

Comment (by rsignell):

 I would argue for standard_names to have their own repo, and that we raise
 requests for new standard names (and discuss) as github issues also.

 I would vote for not forwarding all Github issue discussion to email, but
 letting people watch or unwatch as they desire.  (watch sends email
 notification, unwatch does not)

 https://help.github.com/articles/unwatching-repositories/

--
Ticket URL: 
CF Metadata 
CF Metadata

Re: [CF Metadata] #160: Proposal to use GitHub instead of trac

[CF Metadata]

#160: Proposal to use GitHub instead of trac
-+--
  Reporter:  jonathan|  Owner:  cf-conventions@…
  Type:  task| Status:  new
  Priority:  medium  |  Milestone:
 Component:  cf-conventions  |Version:
Resolution:  |   Keywords:
-+--

Comment (by davidhassell):

 Just a recap:

 There appears to general support for moving the current Trac tickets to
 github issues, but there are currently conflicting opinions in whether to
 move the CF-metadata mailing list to github.

 To my mind, the current CF-metadata mailing list comprises general queries
 (how do I do this?), reconnaissance (would this be a good idea?) and
 standard name proposals (which do not impact on the conventions document).
 Coments on trac tickets are not posted there, but are forwarded to this
 list so that as wide an audiance as possible has the potential to comment
 on convention changes.

 All the best,

 David

--
Ticket URL: 
CF Metadata 
CF Metadata