Opened 3 weeks ago

Last modified 8 days ago

#160 new task

Proposal to use GitHub instead of trac

Reported by: jonathan Owned by: cf-conventions@…
Priority: medium Milestone:
Component: cf-conventions Version:
Keywords: Cc:

Description

Dear CF committee and all

I'm pleased to say that Tanya Reshel at PCMDI is making good progress with working through the tickets which had been accepted by the end of Jan, which we agreed would define CF1.7, and implementing them in the new AsciiDoc source of the CF document on GitHub, with some advice from Jeff Painter, David Hassell and me. Thank you, Tanya.

It's been suggested several times, and most recently by Rich Signell on the email list, that we should consider moving CF conventions discussions to GitHub. We agreed as a committee (recorded in cf-trac.llnl.gov/trac/ticket/146) to revisit this issue when we had more experience of managing the CF document on GitHub, so perhaps this is now the time to discuss it. The suggestion is to replace trac tickets, for discussions of changes to the convention, with GitHub issues; the email list, for more general discussion, not directed to agreeing a particular proposal, could continue as it is.

At the moment we have a system, maintained by Jeff, to synchronise the CF email list, maintained at NCAR, with an email distribution list for trac ticket updates, so that everyone receives both after subscribing to the email list. The present system in principle allows people to be on one but not the other, but in practice there is no-one who's chosen to do that, so it does not seem to be a requirement. I think it's important that everyone should be notified of conventions discussions, because otherwise not enough people will engage with them, since they won't know.

Jeff thinks it would be simple to forward all GitHub notifications from CF conventions discussions to the CF email list. People who don't want them can filter them out. Subscribers who are mentioned by GitHub name in an issue would receive two copies; that's a minor inconvenience, but if everyone is getting them anyway there's probably no need to mention anyone by name. Clearly this would be an easier system to maintain. There would probably be no need to have a list of subscribers to CF on GitHub; anyone with a GitHub account could open an issue.

trac is quite familiar to us now and has served our purpose well. GitHub is a bit more complicated because it can do more. GitHub is probably more popular now. Would GitHub be suitable for us, do you think?

It would have the advantage that, when there is text to discuss, the proposer could make a branch of the CF conventions document and edit it, to show exactly what is proposed. I do not think that it should be required to do it that way, though, because (a) it's not always the clearest way to see things, when they're scattered through several parts of the document, (b) it could be an obstacle to some proposers, who would prefer to write out their proposed changes in their postings to the issue. An editor would then still be needed to implement the changes, once agreed, in the document source.

If we decide to migrate, I think we should do it once CF1.7 is finalised, so that there are no agreed tickets to be migrated. We could then leave the trac system in place for reference, but not permit new tickets. Any existing active tickets could be allowed to come to a conclusion on trac.

Standard name proposals could also be done as GitHub issues, I suppose. They come from a much wider range of contributors than conventions proposals. Would GitHub be a barrier for proposers?

Best wishes

Jonathan

Change History (7)

comment:1 Changed 3 weeks ago by balaji

Dear Jonathan and others: I have been following the exchanges and I am in favour of moving to Github. The branching alone, as outlined, would be a significant step forward toward a way of working on provisional standards within small groups.

The danger is of branches becoming long-lived enough to become more of a fork than a branch. Developers of software that is dependent on a particular version of the conventions have to be aware of the risks of committing themselves to a version not on the trunk; but beyond that I can very easily see a lot more flexibility builtin into a github-based approach.

comment:2 Changed 3 weeks ago by ngalbraith

I agree that github is a good option, although I'd like to keep the email list available for standard name proposals. For some people, having to use github might be enough of a challenge that they'd simply bypass the process altogether.

Last edited 3 weeks ago by ngalbraith (previous) (diff)

comment:3 Changed 3 weeks ago by david.arctur

On using github for the discussion of standard names, one part of me prefers the current approach of using the mail list without even trac; keeps the cognitive barrier as low as possible to encourage the broadest discussion. The other part of me feels that a reference like standard names needs stronger guidance and would perhaps benefit from a more rule-based approach like used for CSDMS names. How are CSDMS names proposed, discussed & decided?

comment:4 Changed 2 weeks ago by lowry

GitHub? seems very popular in the technical fora that I follow whereas Trac is virtually unknown outside CF. I would therefore support the migration and the clear, thought through migration strategy proposed by Jonathan. I would also strongly support Nan and David's view that GitHub? isn't the place for CF-Standard Name discussions. As they both point out, participation in those discussions should be made as easy as possible. I would also recommend that we decouple any discussions on the Standard Name process and possible alternatives from this ticket.

comment:5 Changed 2 weeks ago by mggrant

Moving to GitHub is a good idea. It will be more accessible to more people - getting a trac account here is a bit more manual, which inevitably imposes barriers to participation. It'll reduce maintenance burdens for LLNL too.

While I think issues might be good way to organise standard name requests, there might be some problems ensuring that everyone relevant hears about them and is able to easily respond - the mailing list is certainly simplest. Perhaps trial github with the tickets/issues/as a trac-replacement first, and consider a process for standard names later if the community seems to like the github workflow.

comment:6 Changed 2 weeks ago by cameronsmith1

I am using github on a different project. I think the setup and learning curve barriers for basic commenting should be small, especially if/when github gets integrated with email list. Making basic changes to documents should also be fairly straightforward. Managing branches is powerful, with a bigger learning curve, but that may only be needed by a few people. The process will certainly be smoother if decisions get made on branches quickly.

Overall, I think that a shift to github is a reasonable step.

comment:7 Changed 8 days ago by davidhassell

Thank you, Tanya, for the work you are putting in to CF-1.7.

I'm in favour of moving the trac discussions of changes/defects/etc. to git hub issues, especially in the light of the forthcoming move of the definitive conventions document to github. I would have thought that the current CF-metadata email list should carry on as is, unchanged - many readers and participants do not want or need to contribute to changes, and so would not then need a github account.

To contribute to an issue, would you need your github account to be registered, in some way, with the cf-conventions repository? There would need to be some access restrictions to protect the master repository which, I think (?), might preclude the creation of banches by anyone. Anyone can always fork the repository, though. (Do correct me if my git know-how is wrong!)

I think that keeping the iterations to changes within the issue is important as there they can be wrapped up with explanations and examples more easily than as edits directly to a fork. Perhaps a guideline could be that new changes are described in the issue's intial statement and accompanied by a fork of the document which contains the proposed changes. The changes would then be iterated in the issue discussion with updates to the fork only happening by agreement, and certainly at the discussion's successful conclusion. Just a thought.

Thanks, David

Note: See TracTickets for help on using tickets.