Open Stack

On 25 May 2017 at 09:04, James E. Blair <corvus at inaugust.com> wrote:

> 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
>
> _______________________________________________
> OpenStack-Infra mailing list
> OpenStack-Infra at lists.openstack.org
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-infra


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.

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:

Depends-on: I1234.....

in a gerrit change obviously means look up that change id within the same
location as you found this change.

Similarly on github

Depends-On: ansible/ansible#64

Is fairly common github syntax for referencing PR 64 in ansible/ansible and
can be resolved relative to the current patch's source.

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.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-infra/attachments/20170607/5f67673b/attachment.html>