Document (and warn about) tag job role checkouts

The behavior difference in checking out a role from a branched
project in a job that runs on a tag versus a branch was not documented.

It should be, and since it can lead to unexpected behavior, we should
add a warning.

Change-Id: Ide93210a1df6f724dbaf3c2ac119ac112f97cdd1

1 files changed, 19 insertions, 0 deletions

diff --git a/doc/source/reference/job_def.rst b/doc/source/reference/job_def.rst
index 4d36e098c..1743f59af 100644
--- a/doc/source/reference/job_def.rst
+++ b/doc/source/reference/job_def.rst
@@ -561,6 +561,25 @@ Here is an example of two job definitions:
       In other words, a playbook may not use a role from a different
       branch of the same project.
 
+      If the job is run on a ref (for example, a branch tip or a tag)
+      then a different form of the branch selection process is used.
+      There is no single branch context available for selecting an
+      appropriate branch of the role's repo to check out, so only the
+      following are considered: First the ref specified by
+      :attr:`job.required-projects.override-checkout`, or
+      :attr:`job.override-checkout`.  Then if the role repo is the
+      playbook repo, that branch is used; otherwise the project's
+      default branch is selected.
+
+      .. warning::
+
+         Keep this behavior difference in mind when designing jobs
+         that run on both branches and tags.  If the same job must be
+         used in both circumstances, ensure that any roles from other
+         repos used by playbooks in the job originate only in
+         un-branched repositories.  Otherwise different branches of
+         the role repo may be checked out.
+
       A project which supplies a role may be structured in one of two
       configurations: a bare role (in which the role exists at the
       root of the project), or a contained role (in which the role