Open Stack

Hi,

We recently introduced a new URL-based syntax for Depends-On: footers
in commit messages:

  Depends-On: https://review.openstack.org/535851

The old syntax will continue to work for a while, but please begin using
the new syntax on new changes.

Why are we changing this?  Zuul has grown the ability to interact with
multiple backend systems (Gerrit, GitHub, and plain Git so far), and we
have extended the cross-repo-dependency feature to support multiple
systems.  But Gerrit is the only one that uses the change-id syntax.
URLs, on the other hand, are universal.

That means you can write, as in https://review.openstack.org/535541, a
commit message such as:

  Depends-On: https://github.com/ikalnytskyi/sphinxcontrib-openapi/pull/17

Or in a Github pull request like
https://github.com/ansible/ansible/pull/20974, you can write:

  Depends-On: https://review.openstack.org/536159

But we're getting a bit ahead of ourselves here -- we're just getting
started with Gerrit <-> GitHub dependencies and we haven't worked
everything out yet.  While you can Depends-On any GitHub URL, you can't
add any project to required-projects yet, and we need to establish a
process to actually report on GitHub projects.  But cool things are
coming.

We will continue to support the Gerrit-specific syntax for a while,
probably for several months at least, so you don't need to update the
commit messages of changes that have accumulated precious +2s.  But do
please start using the new syntax now, so that we can age the old syntax
out.

There are a few differences in using the new syntax:

* Rather than copying the change-id from a commit message, you'll need
  to get the URL from Gerrit.  That means the dependent change already
  needs to be uploaded.  In some complex situations, this may mean that
  you need to amend an existing commit message to add in the URL later.

  If you're uploading both changes, Gerrit will output the URL when you
  run git-review, and you can copy it from there.  If you are looking at
  an existing change in Gerrit, you can copy the URL from the permalink
  at the top left of the page.  Where it says "Change 535855 - Needs
  ..." the change number itself is the permalink of the change.

* The new syntax points to a specific change on a specific branch.  This
  means if you depend on a change to multiple branches, or changes to
  multiple projects, you need to list each URL.  The old syntax looks
  for all changes with that ID, and depends on all of them.  This may
  mean some changes need multiple Depends-On footers, however, it also
  means that we can express dependencies is a more fine-grained manner.

Please start using the new syntax, and let us know in #openstack-infra
if you have any problems.  As new features related to GitHub support
become available, we'll announce them here.

Thanks,

Jim