Thanks, Matt, for getting the ball rolling on this.  I had been wrestling for a few days over how to write something similar, but you seem to have touched on most of the major points.

 

No matter how much we say it is merely “experimental,” simply having a public repository available to act as a central and timely source for changes has apparently caused many to see it as “blessed.”  This is not inherently a bad thing, but we need to adapt our behavior accordingly.

 

With regard to Items 1 and 4, we absolutely should be making use of branches, for all the reasons you mentioned.  Currently, most patches are submitted to the list, reviewed, and then applied to master; however, patches authored by Paul are applied directly to master, and those changes are reviewed and defended afterwards.  Clearly, this disparity has been an issue recently, and I sense that it is the source of much of the shock some are experiencing over the proposed major changes.  Though I personally believe Paul has made his edits in good faith, I can also easily see how the idea that the repository is simply “Paul’s playground” may have developed amongst others.

 

I would add that if the master branch is always in a state of “positive agreement,” as it should be, then it is also always “ready for release.”  Every push to master should effectively be a release candidate.  For us, this may still mean that obvious and urgent hotfixes to data go straight to master, but this should not be the norm, especially for maintenance tasks.  In particular, it means that the proposed zone-linking and introduction of time.tab should be done on separate branches to allow for debate and further refinement of those ideas before this project commits itself to their use.

 

To this effect, I agree that it would be better that the repository not be associated with Paul’s personal account; however, as long as the master branch is given due deference, this concern becomes somewhat less pressing.

 

With regard to Items 2 and 3, while I’m all for using what Git has to offer, I’m extremely wary of locking ourselves into Github or any other similar service.  Others have written, far better than I could, about how the Github pull request system subverts or otherwise “breaks” the core functionality of Git.  If it were up to me, I’d disable pull requests entirely and exclusively use the mailing list, which keeps more complete (albeit messier) archives.  Alas, Github does not allow pull requests to be disabled.  This may mean that Github is not the right place for our repository.

 

Further, Github’s communication tools on pull requests and issues are simply far less flexible than email.  I’d also rather keep our barrier of entry low, so that even someone who knows nothing about Git can still submit well-thought changes to the list.  For the simplest patches we see, a pull request is simply too much overhead.

 

Even without using pull requests, though, forks can be very useful for sharing branches.  For all but the simplest patches, we can each alert the list when we have a branch ready for consideration, copying the proposed patches to the list for archival, while also providing a link to the branch for easy review.  For large changes, one can use this method in conjunction with the flexibility of email to get input from a few more people before presenting a more refined set of changes to the full list.  We generally have a low enough throughput that it may still be okay to copy commits over into master once this process is complete, to avoid messy merges.

 

In any case, given how central this system has recently become to our project, we should definitely add clear guidance to both our own documentation and the IANA pages, conveying how we collectively choose to use (or not use) the features of Github or any similar service.  Right now, no such guidance exists.  Hopefully this discussion acts as a starting point for that.

 

With regard to Item 5, I would point out that, often, code changes are necessitated by corresponding changes in data.  Breaking apart into separate projects would make these connections far less obvious, and so I would prefer that our work remain unified under a single repository.

 

I would also like to add Item 6: Proper use of commits as individual units for review.  For us, commits don’t necessarily need to be absolutely minimal; my personal goal is merely that each contains only highly-related changes and is understandable on its own.  I tried to obey this principle while developing my recent contributions regarding Russia’s changes.  (Believe me, I didn’t write them as four neat little patches from the start!)  It is inappropriate to batch together several unrelated changes and push them as a single commit, as this makes reviewing more difficult.

 

A recent example is commit f1ddf32f059c17fa5a1ec24f549d70db36dc5fa9 of 2014-07-15, in which Paul partially reverts his earlier zone-to-link changes, but also adds several fixes and bits of commentary which he discovered while researching the changes.  In the case that further reversions become necessary, this makes it very difficult to tease out the “good” from the “bad.”  (This is only exacerbated by our non-use of branches.)

 

I will try to model these best practices — especially with regard to Items 2, 3, and 6 — in a separate email I will send shortly, proposing reversions to the current state of the repository so that we can hopefully adopt these (or similar) best practices from there.