Add support for override-checkout, deprecate override-branch

We want to support jobs specifying that they check out a tag
rather than merely a branch.  This accidentally worked in Zuul v2
with zuul-cloner, and some jobs have come to rely on the behavior.
There's no reason not to support it, so let's do so.

However, for clarity, change the name of the option to
"override-checkout".  This is intended to be intuitive (anything
you can tell git to 'checkout' you can put here), while avoiding
the suggestion that only branches or tags may be checked out.

The old form, "override-branch" is deprecated and will be removed.

Change-Id: Icc2907e72596626e96d2dc9f6ab1c3026f4085ab
diff --git a/tests/fixtures/layouts/repo-checkout-no-timer-override.yaml b/tests/fixtures/layouts/repo-checkout-no-timer-override.yaml
index ca49292..89d2b93 100644
--- a/tests/fixtures/layouts/repo-checkout-no-timer-override.yaml
+++ b/tests/fixtures/layouts/repo-checkout-no-timer-override.yaml
@@ -15,7 +15,7 @@
 - job:
     name: integration
     branches: master
-    override-branch: stable/havana
+    override-checkout: stable/havana
     required-projects:
       - org/project1
     run: playbooks/integration.yaml
diff --git a/tests/fixtures/layouts/repo-checkout-no-timer.yaml b/tests/fixtures/layouts/repo-checkout-no-timer.yaml
index 6b88801..0374897 100644
--- a/tests/fixtures/layouts/repo-checkout-no-timer.yaml
+++ b/tests/fixtures/layouts/repo-checkout-no-timer.yaml
@@ -14,7 +14,7 @@
 
 - job:
     name: integration
-    override-branch: stable/havana
+    override-checkout: stable/havana
     required-projects:
       - org/project1
     run: playbooks/integration.yaml
diff --git a/tests/fixtures/layouts/repo-checkout-six-project.yaml b/tests/fixtures/layouts/repo-checkout-six-project.yaml
index 6079612..4878665 100644
--- a/tests/fixtures/layouts/repo-checkout-six-project.yaml
+++ b/tests/fixtures/layouts/repo-checkout-six-project.yaml
@@ -44,7 +44,7 @@
       - org/project2
       - org/project3
       - name: org/project4
-        override-branch: master
+        override-checkout: master
       - org/project5
       - org/project6
     run: playbooks/integration.yaml
diff --git a/tests/fixtures/layouts/repo-checkout-tag.yaml b/tests/fixtures/layouts/repo-checkout-tag.yaml
new file mode 100644
index 0000000..3f1af1c
--- /dev/null
+++ b/tests/fixtures/layouts/repo-checkout-tag.yaml
@@ -0,0 +1,36 @@
+- pipeline:
+    name: check
+    manager: independent
+    trigger:
+      gerrit:
+        - event: patchset-created
+    success:
+      gerrit:
+        Verified: 1
+    failure:
+      gerrit:
+        Verified: -1
+
+- job:
+    name: base
+    parent: null
+
+- job:
+    name: integration
+    required-projects:
+      - org/project1
+      - name: org/project2
+        override-checkout: test-tag
+    run: playbooks/integration.yaml
+
+- project:
+    name: org/project1
+    check:
+      jobs:
+        - integration
+
+- project:
+    name: org/project2
+    check:
+      jobs:
+        - integration
diff --git a/tests/fixtures/layouts/repo-checkout-timer-override.yaml b/tests/fixtures/layouts/repo-checkout-timer-override.yaml
index af5bd3c..4aacfee 100644
--- a/tests/fixtures/layouts/repo-checkout-timer-override.yaml
+++ b/tests/fixtures/layouts/repo-checkout-timer-override.yaml
@@ -13,7 +13,7 @@
 - job:
     name: integration
     branches: master
-    override-branch: stable/havana
+    override-checkout: stable/havana
     required-projects:
       - org/project1
     run: playbooks/integration.yaml
diff --git a/tests/unit/test_executor.py b/tests/unit/test_executor.py
index f051ec4..5d27663 100755
--- a/tests/unit/test_executor.py
+++ b/tests/unit/test_executor.py
@@ -378,6 +378,32 @@
 
         self.assertBuildStates(states, projects)
 
+    @simple_layout('layouts/repo-checkout-tag.yaml')
+    def test_tag_checkout(self):
+        self.executor_server.hold_jobs_in_build = True
+        p1 = "review.example.com/org/project1"
+        p2 = "review.example.com/org/project2"
+        projects = [p1, p2]
+        upstream = self.getUpstreamRepos(projects)
+
+        self.create_branch('org/project2', 'stable/havana')
+        files = {'README': 'tagged readme'}
+        self.addCommitToRepo('org/project2', 'tagged commit',
+                             files, branch='stable/havana', tag='test-tag')
+
+        A = self.fake_gerrit.addFakeChange('org/project1', 'master', 'A')
+        self.fake_gerrit.addEvent(A.getPatchsetCreatedEvent(1))
+        self.waitUntilSettled()
+
+        states = [
+            {p1: dict(present=[A], branch='master'),
+             p2: dict(commit=str(upstream[p2].commit('test-tag')),
+                      absent=[A]),
+             },
+        ]
+
+        self.assertBuildStates(states, projects)
+
 
 class TestAnsibleJob(ZuulTestCase):
     tenant_config_file = 'config/ansible/main.yaml'