From 9ea4daca28970b42471e41086d8586d35e78569b Mon Sep 17 00:00:00 2001 From: Matthieu Huin Date: Fri, 19 Jun 2020 17:13:11 +0200 Subject: [PATCH] CLI: add documentation on promote Change-Id: I78056efee7608f4d153c12ec90e9a11dc6d22c18 --- doc/source/reference/client.rst | 15 ++++++++++++++- 1 file changed, 14 insertions(+), 1 deletion(-) diff --git a/doc/source/reference/client.rst b/doc/source/reference/client.rst index 1fec75be52..4084c2c1a7 100644 --- a/doc/source/reference/client.rst +++ b/doc/source/reference/client.rst @@ -147,10 +147,23 @@ Promote Example:: - zuul promote --tenant openstack --pipeline check --changes 12345,1 13336,3 + zuul promote --tenant openstack --pipeline gate --changes 12345,1 13336,3 Note that the format of changes id is ,. +The promote action is used to reorder the change queue in a pipeline, by putting +the provided changes at the top of the queue; therefore this action makes the +most sense when performed against a dependent pipeline. + +The most common use case for the promote action is the need to merge an urgent +fix when the gate pipeline has already several patches queued ahead. This is +especially needed if there is concern that one or more changes ahead in the queue +may fail, thus increasing the time to land for the fix; or concern that the fix +may not pass validation if applied on top of the current patch queue in the gate. + +If the queue of a dependent pipeline is targeted by the promote, all the ongoing +jobs in that queue will be canceled and restarted on top of the promoted changes. + Show ^^^^