<div dir="ltr"><br><div class="gmail_extra"><br><div class="gmail_quote">On 25 May 2017 at 09:04, James E. Blair <span dir="ltr"><<a href="mailto:corvus@inaugust.com" target="_blank">corvus@inaugust.com</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">Hi,<br>
<br>
As part of Zuul v3, we're adding support for GitHub (and later possibly<br>
other systems).  We want these systems to have access to the full power<br>
of cross-project-dependencies in the same way as Gerrit.  However, the<br>
current syntax for the Depends-On footer is currently the<br>
Gerrit-specific change-id.<br>
<br>
We chose this in an attempt to be future-compatible with some proposed<br>
changes to Gerrit itself to support cross-project dependencies.  Since<br>
then, Gerrit has gone in a different direction on this subject, so I no<br>
longer think we should weigh that very heavily.<br>
<br>
While Gerrit change ids can be used to identify one or more changes<br>
within a Gerrit installation, there is no comparable identifier on<br>
GitHub, as pull request numbers are unique only within a project.<br>
<br>
The natural way to identify a GitHub pull request is with its URL.<br>
<br>
This can be used to identify Gerrit changes as well, and will likely be<br>
well supported by other systems.  Therefore, I propose we support URLs<br>
as the content of the Depends-On footers for all systems.  E.g.:<br>
<br>
  Depends-On: <a href="https://review.openstack.org/12345" rel="noreferrer" target="_blank">https://review.openstack.org/<wbr>12345</a><br>
  Depends-On: <a href="https://github.com/ansible/ansible/pull/12345" rel="noreferrer" target="_blank">https://github.com/ansible/<wbr>ansible/pull/12345</a><br>
<br>
Similarly to the Gerrit change IDs, these identifiers are easily<br>
navigable within Gerrit (and Gertty), so that reviewers can traverse the<br>
dependency chain easily.<br>
<br>
One substantial aspect of this change is that it is more specific about<br>
projects and branches.  A single Gerrit change ID can refer to more than<br>
one branch, and even more than one project.  Zuul interprets this as<br>
"this change depends on *all* of the changes that match".  Often times<br>
that is convenient, but sometimes it is not.  Frequently users ask "how<br>
can I make this depend only on a change to master, not the backport of<br>
the change to stable?" and the answer is, "you can't".<br>
<br>
URLs have the advantage of allowing users to be specific as to which<br>
instances of a given change are actually required.  If, indeed, a change<br>
depends on more than one, of course a user can still add multiple<br>
Depends-On headers, one for each.<br>
<br>
It is also easy for Zuul connections to determine whether a given URL is<br>
referring to a change on that system without actually needing to query<br>
it.  A Zuul connected to several code review systems can easy determine<br>
which to ask for the change by examining the hostname.<br>
<br>
URLs do have two disadvantages compared to Gerrit change IDs: they can<br>
not be generated ahead of time, and they are not as easily found in<br>
offline git history.<br>
<br>
With Gerrit change IDs, we can write several local changes, and before<br>
pushing them to Gerrit, add Depends-On headers since the change id is<br>
generated locally.  URLs are not known until the changes are pushed to<br>
Gerrit (or GitHub pull requests opened).  So in some cases, editing of<br>
an already existing commit message may be required.  However, the most<br>
common case of a simple dependency chain can still be easily created by<br>
pushing one change up at a time.<br>
<br>
Change IDs, by virtue of being in the commit message of the dependent as<br>
well as depending change, become part of the permanent history of the<br>
project, no longer tied to the code review system, once they merge.<br>
This is an important thing to consider for long-running projects.  URLs<br>
are less suitable for this, since they acquire their context from<br>
contemporaneous servers.  However, Gerrit does record the review URL in<br>
git notes, so while it's not as convenient, with some additional tooling<br>
it should be possible to follow dependency paths with only the git<br>
history.<br>
<br>
Of course, this is not a change we can make instantaneously -- the<br>
change IDs have a lot of inertia and developer muscle memory.  And we<br>
don't want changes that have been in progress for a while to suddenly be<br>
broken with the switch to v3.  So we will need to support both syntaxes<br>
for some time.<br>
<br>
We could, indeed, support both syntaxes indefinitely, but I believe it<br>
would be better to plan on deprecating the Gerrit change ID syntax with<br>
an eye to eventually removing it.  I think that ultimately, the URL<br>
syntax for Depends-On is more intuitive to a new user, especially one<br>
that may end up being exposed to a Zuul which connects to multiple<br>
systems.  Having a Gerrit change depend on a GitHub pull request (and<br>
vice versa) will be one of the most powerful features of Zuul v3, and<br>
the syntax for that should be approachable.<br>
<br>
In short, I think the value of consistency across multiple backends and<br>
ease of use for new users outweighs the small loss of functionality for<br>
Gerrit power users in this case.<br>
<br>
I propose we adopt support for URLs in all source drivers in v3, and<br>
declare Gerrit change IDs deprecated.  We will continue to support both<br>
for a generous deprecation period (at least 6 months after the initial<br>
Zuul 3.0 release), and then remove support for them.<br>
<br>
How does that sound?<br>
<br>
-Jim<br>
<br>
______________________________<wbr>_________________<br>
OpenStack-Infra mailing list<br>
<a href="mailto:OpenStack-Infra@lists.openstack.org">OpenStack-Infra@lists.<wbr>openstack.org</a><br>
<a href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-infra" rel="noreferrer" target="_blank">http://lists.openstack.org/<wbr>cgi-bin/mailman/listinfo/<wbr>openstack-infra</a></blockquote></div><br></div><div class="gmail_extra">I'm late to this party. In general I like the idea that we use fully qualified urls as the Depends-on default, however i question whether that means we need to remove the change-id based format. Note, i understand it's way easier to add things back than remove them later so i'm on board with remove it and see what happens in future. <br><br></div><div class="gmail_extra">For changes that are not cross source I would think that a non fully qualified URL makes sense to be resolved within the same source for example: <br><br></div><div class="gmail_extra">Depends-on: I1234.....<br><br></div><div class="gmail_extra">in a gerrit change obviously means look up that change id within the same location as you found this change. <br><br></div><div class="gmail_extra">Similarly on github<br><br></div><div class="gmail_extra">Depends-On: ansible/ansible#64<br><br></div><div class="gmail_extra">Is fairly common github syntax for referencing PR 64 in ansible/ansible and can be resolved relative to the current patch's source. <br><br></div><div class="gmail_extra">Again, happy to see this in a 3.x down the line but particularly the github syntax will be much more familar to those users.<br></div></div>