<div dir="ltr"><p class="MsoNormal">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.</p>
<p class="MsoNormal"> </p>
<p class="MsoNormal">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.</p>
<p class="MsoNormal"> </p>
<p class="MsoNormal"><b>With regard to Items
1 and 4,</b> 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.</p>
<p class="MsoNormal"> </p>
<p class="MsoNormal">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.</p>
<p class="MsoNormal"> </p>
<p class="MsoNormal">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.</p>
<p class="MsoNormal"> </p>
<p class="MsoNormal"><b>With regard to Items
2 and 3,</b> 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 <a href="http://laurent.bachelier.name/2012/05/github-kinda-sucks/">subverts or otherwise “breaks”</a> 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.</p>
<p class="MsoNormal"> </p>
<p class="MsoNormal">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.</p>
<p class="MsoNormal"> </p>
<p class="MsoNormal">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.</p>
<p class="MsoNormal"> </p>
<p class="MsoNormal">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.</p>
<p class="MsoNormal"> </p>
<p class="MsoNormal"><b>With regard to Item
5,</b> 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.</p>
<p class="MsoNormal"> </p>
<p class="MsoNormal"><b>I would also like to
add Item 6:</b> 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.</p><p class="MsoNormal"></p>
<p class="MsoNormal"> </p>
<p class="MsoNormal">A recent example is <a href="https://github.com/eggert/tz/commit/f1ddf32f059c17fa5a1ec24f549d70db36dc5fa9">commit f1ddf32f059c17fa5a1ec24f549d70db36dc5fa9</a> 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.)</p>
<p class="MsoNormal"> </p>
<p class="MsoNormal">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.</p></div><div class="gmail_extra"><br clear="all"><div>--<br>Tim Parenti<br></div>
<br><br><div class="gmail_quote">On 26 July 2014 14:38, Matt Johnson <span dir="ltr"><<a href="mailto:mj1856@hotmail.com" target="_blank">mj1856@hotmail.com</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
I think it's great that we're using Git and Github as the experimental /<br>
unofficial repository at <a href="https://github.com/eggert/tz" target="_blank">https://github.com/eggert/tz</a>. It's much easier to<br>
track change history looking through the commit log and see the changes than<br>
by reading through emails with patch attachments. However, we're not<br>
currently taking advantage of all that this environment has to offer.<br>
<br>
-- Item 1 --<br>
We should be making better use of branches. We currently have a single<br>
"master" branch that everything gets committed to. This is problematic,<br>
because it doesn't separate things that are certain to be released from<br>
things that are proposed changes. For example, the recent time.tab file,<br>
and the other large-scale proposed changes that are currently being debated,<br>
could have been created on feature branches. This would have given the tz<br>
list members a place to look at the proposed changes and make additional<br>
suggestions (via pull requests) before things are finalized.<br>
<br>
As it sits today, since everything is in master, if the proposal is<br>
ultimately defeated then new commits will have to be made to master to<br>
revert these changes. The danger comes if, say we needed to issue an<br>
emergency release sometime in between. Since master isn't in a state of<br>
positive agreement, then one would have to branch from an earlier point in<br>
history to build a hotfix release, then merge that hotfix back to master<br>
later. It's much easier if we can just trust that master always consists<br>
of things that are certain to be released.<br>
<br>
See also:<br>
<a href="https://www.atlassian.com/git/workflows#!workflow-feature-branch" target="_blank">https://www.atlassian.com/git/workflows#!workflow-feature-branch</a><br>
<a href="http://www.git-scm.com/book/en/Git-Branching-Basic-Branching-and-Merging" target="_blank">http://www.git-scm.com/book/en/Git-Branching-Basic-Branching-and-Merging</a><br>
<br>
-- Item 2 --<br>
I think that we should all make better use of forking and pull-requests for<br>
submitting proposed changes. Instead of submitting a patch file to the<br>
mailing list, one should fork the GitHub repo, make their changes, then<br>
create a pull request. This allows for place for discussion on proposals<br>
where the code can be referenced much easier. It also ensures that the<br>
author of each and every change is tracked in the commit log. And finally,<br>
it makes it much clearer which proposals were adopted and which were not.<br>
Presently, looking through the mailing list archives, it's quite difficult<br>
to tell if any given patch was actually applied or not.<br>
<br>
-- Item 3 --<br>
We should decide how the GitHub issue tracker fits in to the ecosystem. I<br>
see that there have been a few issues reported to via the issue tracker in<br>
the past, but most things have come through the mailing list. If we adopt<br>
the conventions used by other modern projects, then we should be reporting<br>
bugs through the issue tracker so their history can be more easily found.<br>
Another benefit is that you can reference issue numbers in commits, and you<br>
can reference commits in the comments of an issue. This linking makes it<br>
quite easy to find the code or data that was changed in response to an<br>
issue. The mailing list should probably be used for extended discussion,<br>
rather than as a place to report issues. Though, there may be some blend of<br>
both, I personally think that an issue tracker is much more palatable than a<br>
mailing list for many of these kinds of things. There should probably be<br>
some guidance document on the iana tz page about what goes where.<br>
<br>
-- Item 4 --<br>
While Paul Eggert is the tz maintainer, and I appreciate his efforts<br>
greatly, I personally don't feel that it's appropriate for the github repo<br>
to be in his personal "eggert" account. There should instead be a common<br>
"organizational account" for the project, such as <a href="http://github.com/tzdb" target="_blank">github.com/tzdb</a> or<br>
similar. ("iana" is taken, but appears to be unused or abandonded. Someone<br>
may want to inquire about obtaining it, as "<a href="http://github.com/iana/tz" target="_blank">github.com/iana/tz</a>" would be<br>
quite appropriate IMHO). Though Paul would be the administrator of this<br>
account, his own personal account would no longer be authoritative.<br>
<br>
That also ties back to the idea of pull-requests. Since Paul makes the<br>
majority of changes, he would first make them in his own account, and then<br>
send a pull-request to the main account. Then a link could be sent to the<br>
mailing list for discussion on the pull request before it was merged in.<br>
<br>
As a side note - I've found that several third-party projects are linking to<br>
the unofficial sources using git submodules. While this isn't officially<br>
sanctioned, it would be much better if they could link to iana/tz instead of<br>
eggert/tz.<br>
<br>
-- Item 5 --<br>
While code and data often go hand-in-hand, there are quite a lot of projects<br>
these days that only rely on the tz data. There are also a lot of releases<br>
of code changes that don't require data changes. Having both code and data<br>
in a single project seems rather inefficient. I propose that they be split<br>
back to separate projects, and maintained in separate github repos (tzdata<br>
/ tzcode).<br>
<br>
Also, consider also that perhaps there are too many merged projects just<br>
within the code. For example, tzselect, zic, zdump, etc. might be broken<br>
out for better visibility of changes and for clarity of dependent files.<br>
<br>
<br>
I look forward to feedback on these items. I'm sure not all will be in<br>
agreement, but I think it's important that we look forward to new and better<br>
ways to manage this project - rather than just sticking with the ways of the<br>
past.<br>
<span class="HOEnZb"><font color="#888888"><br>
-Matt<br>
</font></span></blockquote></div><br></div>