Open Stack

Hi,

As part of Zuul v3, we're adding support for GitHub (and later possibly
other systems).  We want these systems to have access to the full power
of cross-project-dependencies in the same way as Gerrit.  However, the
current syntax for the Depends-On footer is currently the
Gerrit-specific change-id.

We chose this in an attempt to be future-compatible with some proposed
changes to Gerrit itself to support cross-project dependencies.  Since
then, Gerrit has gone in a different direction on this subject, so I no
longer think we should weigh that very heavily.

While Gerrit change ids can be used to identify one or more changes
within a Gerrit installation, there is no comparable identifier on
GitHub, as pull request numbers are unique only within a project.

The natural way to identify a GitHub pull request is with its URL.

This can be used to identify Gerrit changes as well, and will likely be
well supported by other systems.  Therefore, I propose we support URLs
as the content of the Depends-On footers for all systems.  E.g.:

  Depends-On: https://review.openstack.org/12345
  Depends-On: https://github.com/ansible/ansible/pull/12345

Similarly to the Gerrit change IDs, these identifiers are easily
navigable within Gerrit (and Gertty), so that reviewers can traverse the
dependency chain easily.

One substantial aspect of this change is that it is more specific about
projects and branches.  A single Gerrit change ID can refer to more than
one branch, and even more than one project.  Zuul interprets this as
"this change depends on *all* of the changes that match".  Often times
that is convenient, but sometimes it is not.  Frequently users ask "how
can I make this depend only on a change to master, not the backport of
the change to stable?" and the answer is, "you can't".

URLs have the advantage of allowing users to be specific as to which
instances of a given change are actually required.  If, indeed, a change
depends on more than one, of course a user can still add multiple
Depends-On headers, one for each.

It is also easy for Zuul connections to determine whether a given URL is
referring to a change on that system without actually needing to query
it.  A Zuul connected to several code review systems can easy determine
which to ask for the change by examining the hostname.

URLs do have two disadvantages compared to Gerrit change IDs: they can
not be generated ahead of time, and they are not as easily found in
offline git history.

With Gerrit change IDs, we can write several local changes, and before
pushing them to Gerrit, add Depends-On headers since the change id is
generated locally.  URLs are not known until the changes are pushed to
Gerrit (or GitHub pull requests opened).  So in some cases, editing of
an already existing commit message may be required.  However, the most
common case of a simple dependency chain can still be easily created by
pushing one change up at a time.

Change IDs, by virtue of being in the commit message of the dependent as
well as depending change, become part of the permanent history of the
project, no longer tied to the code review system, once they merge.
This is an important thing to consider for long-running projects.  URLs
are less suitable for this, since they acquire their context from
contemporaneous servers.  However, Gerrit does record the review URL in
git notes, so while it's not as convenient, with some additional tooling
it should be possible to follow dependency paths with only the git
history.

Of course, this is not a change we can make instantaneously -- the
change IDs have a lot of inertia and developer muscle memory.  And we
don't want changes that have been in progress for a while to suddenly be
broken with the switch to v3.  So we will need to support both syntaxes
for some time.

We could, indeed, support both syntaxes indefinitely, but I believe it
would be better to plan on deprecating the Gerrit change ID syntax with
an eye to eventually removing it.  I think that ultimately, the URL
syntax for Depends-On is more intuitive to a new user, especially one
that may end up being exposed to a Zuul which connects to multiple
systems.  Having a Gerrit change depend on a GitHub pull request (and
vice versa) will be one of the most powerful features of Zuul v3, and
the syntax for that should be approachable.

In short, I think the value of consistency across multiple backends and
ease of use for new users outweighs the small loss of functionality for
Gerrit power users in this case.

I propose we adopt support for URLs in all source drivers in v3, and
declare Gerrit change IDs deprecated.  We will continue to support both
for a generous deprecation period (at least 6 months after the initial
Zuul 3.0 release), and then remove support for them.

How does that sound?

-Jim