From 1781adb856b518c26c4a51fabc3f75c83ac73467 Mon Sep 17 00:00:00 2001 From: Edwin Kempin Date: Tue, 22 Apr 2014 10:02:40 +0200 Subject: [PATCH] Describe labels and submit rules in project owner guide Change-Id: I3f52692757811858c03b85820f8a718e0815ffce Signed-off-by: Edwin Kempin --- Documentation/intro-project-owner.txt | 72 +++++++++++++++++++++++++++ Documentation/prolog-cookbook.txt | 5 ++ 2 files changed, 77 insertions(+) diff --git a/Documentation/intro-project-owner.txt b/Documentation/intro-project-owner.txt index 14912bf295..bca27c3044 100644 --- a/Documentation/intro-project-owner.txt +++ b/Documentation/intro-project-owner.txt @@ -275,10 +275,82 @@ development branches. You likely want to start with more restrictive policy if you are facing issues with the build and test stability of the destination branches. +It is also possible to define the submit type dynamically via +link:#prolog-submit-type[Prolog]. This way you can use different submit +types for different branches. + Please note that there are other submit types available; they are described in the link:project-setup.html#submit_type[Submit Type] section. +[[labels]] +== Labels + +The code review process includes that reviewers formally express their +opinion about a change by voting on different link:config-labels.html[ +labels]. By default Gerrit comes with the +link:config-labels.html#label_Code-Review[Code-Review] label and many +Gerrit servers have the link:config-labels.html#label_Verified[Verified] +label configured globally. However projects can also define their own +link:config-labels.html#label_custom[custom labels] to formalize +project-specific workflows. For example if a project requires an IP +approval from a special IP-team, it can define an `IP-Review` label +and grant permissions to the IP-team to vote on this label. + +The behavior of a label can be controlled by its +link:config-labels.html#label_function[function], e.g. it can be +configured whether a max positive voting on the label is required for +submit or if the voting on the label is optional. + +By using a custom link:#submit-rules[submit rule] it can be controlled +per change whether a label is required for submit or not. + +A useful feature on labels is the possibility to automatically copy +scores forward to new patch sets if it was a +link:config-labels.html#label_copyAllScoresOnTrivialRebase[trivial +rebase] or if link:config-labels.html#label_copyAllScoresIfNoCodeChange[ +there was no code change] (e.g. only the commit message was edited). + +[[submit-rules]] +== Submit Rules + +A link:prolog-cookbook.html#SubmitRule[submit rule] in Gerrit is logic +that defines when a change is submittable. By default, a change is +submittable when it gets at least one highest vote on each label and +has no lowest vote (aka veto vote) on any label. + +The submit rules in Gerrit are implemented in link:prolog-cookbook.html[ +Prolog] and projects that need more flexibility can define their own +submit rules to decide when a change should be submittable. A good +link:prolog-cookbook.html#NonAuthorCodeReview[example] from the Prolog +cookbook shows how to allow submit only if a change has a +`Code-Review+2` vote from a person that is not the change author. This +way a four-eyes principle for the reviews can be enforced. + +A Prolog submit rule has access to link:prolog-change-facts.html[ +information] about the change for which it is testing the +submittability. Amongst others the list of the modified files can be +accessed, which allows special logic if certain files are touched. For +example, a common practice is to require a vote on an additional label, +like `Library-Compliance`, if the dependencies of the project are +changed. + +[[prolog-submit-type]] +It is also possible to control the link:prolog-cookbook.html#SubmitType[ +submit type] from Prolog. For example this can be used to define a more +restrictive submit type such as `Fast Forward Only` for stable branches +while using a more liberal submit type, e.g. `Merge If Necessary` with +content merge, for development branches. How this can be done can be +seen from an link:prolog-cookbook.html#SubmitTypePerBranch[example] in +the Prolog cookbook. + +Submit rules are maintained in the link:prolog-cookbook.html#RulesFile[ +rules.pl] file in the `refs/meta/config` branch of the project. How to +write submit rules is explained in the +link:prolog-cookbook.html#HowToWriteSubmitRules[Prolog cookbook]. There +is also good support for link:prolog-cookbook.html#TestingSubmitRules[ +testing submit rules] while developing them. + GERRIT ------ Part of link:index.html[Gerrit Code Review] diff --git a/Documentation/prolog-cookbook.txt b/Documentation/prolog-cookbook.txt index 91967b2b92..5bff6bfe03 100644 --- a/Documentation/prolog-cookbook.txt +++ b/Documentation/prolog-cookbook.txt @@ -1,5 +1,6 @@ = Gerrit Code Review - Prolog Submit Rules Cookbook +[[SubmitRule]] == Submit Rule A 'Submit Rule' in Gerrit is logic that defines when a change is submittable. By default, a change is submittable when it gets at least one @@ -26,6 +27,7 @@ project specific submit rules. link:http://gerrit-documentation.googlecode.com/svn/ReleaseNotes/ReleaseNotes-2.2.2.html[Gerrit 2.2.2 ReleaseNotes] introduces Prolog support in Gerrit. +[[SubmitType]] == Submit Type A 'Submit Type' is a strategy that is used on submit to integrate the change into the destination branch. Supported submit types are: @@ -71,6 +73,7 @@ Instead of using the link:pgm-prolog-shell.html[prolog-shell] program one can also use the link:http://www.swi-prolog.org/[SWI-Prolog] environment. It provides a better shell interface and a graphical source-level debugger. +[[RulesFile]] == The rules.pl file This section explains how to create and edit project specific submit rules. How to actually write the submit rules is explained in the next section. @@ -644,6 +647,7 @@ logic. The following pattern illustrates this technique: In the following examples both styles will be shown. +[[NonAuthorCodeReview]] === Example 8: Make change submittable only if `Code-Review+2` is given by a non author In this example we introduce a new label `Non-Author-Code-Review` and make it satisfied if there is at least one `Code-Review+2` from a non author. All other @@ -977,6 +981,7 @@ rules.pl ==== +[[SubmitTypePerBranch]] === Example 2: `Fast Forward Only` for all `refs/heads/stable*` branches For all `refs/heads/stable.*` branches we would like to enforce the `Fast Forward Only` submit type. A reason for this decision may be a need to never