Make over-arching owners plugin docs more generic There is no need to explain the details of either owners or owners-autoassign at the repository level, a brief introduction is more than enough. Each plugin section can then be much more specific with examples and extensive config options. Change-Id: Id7b7db57d328962d9819402ea2befc06c83d7406
diff --git a/README.md b/README.md index 9c1decb..2b3c50e 100644 --- a/README.md +++ b/README.md
@@ -1,43 +1,42 @@ # Gerrit OWNERS Plugin -This plugin provides some Prolog predicates that can be used to add customized -validation checks based on the approval of ‘path owners’ of a particular folder -in the project. +This repository comprosises of effectively two separate plugins, `owners` and +`owners-autoassign`. -That allows creating a single big project including multiple components and -users have different roles depending on the particular path where changes are -being proposed. A user can be “owner” in a specific directory, and thus -influencing the approvals of changes there, but cannot do the same in others -paths, so assuring a kind of dynamic subproject access rights. +They share the ability to parse the same OWNERS file format, which facilitates +the maintenance of ACLs, as there is only one source of truth. -## How it works +For details on how to configure either plugin, please refer to the docs in the +specific plugin's folder. -There are currently two main prolog public verbs: +Here's an introduction to both plugins: -`add_owner_approval/3` (UserList, InList, OutList) -appends `label('Owner-Approval', need(_))` to InList building OutList if -UserList has no users contained in the defined owners of this path change. +## owners -In other words, the predicate just copies InList to OutList if at least one of -the elements in UserList is an owner. +This plugin exposes the `has:approval_owners` predicate that can be used with +Gerrit's own +[submit-requirements](/Documentation/config-submit-requirements.html) to ensure +that a change has been approved by +the relevant users defined in the OWNERS file for the target branch of the +change. -`add_owner_approval/2` (InList, OutList) -appends `label('Owner-Approval', need(_))` to InList building OutList if -no owners has given a Code-Review +2 to this path change. +This allows the creation of a single repository with multiple nested projects, each +potentially, used by different users/teams with different roles depending on the +particular path where changes are being proposed. A user can be “owner” in a +specific directory, thus influencing the approvals of changes there, but not +in others, enabling great flexibility when working on repositories shared by +multiple teams. -This predicate is similar to the first one but generates a UserList with an -hardcoded policy. +## owners-autoassign -Since add_owner_approval/3 is not using hard coded policies, it can be suitable -for complex customizations. +This plugin parses the same OWNERS file format as the owners plugin. It will +automatically assign all of the owners as reviewers to newly created or updated +changes. It also allows for completely custom management of the attention set, +i.e. allows, via custom integrations, to not add people on holiday to the +attention set, or that the same user is not added to too many changes at the +same time, etc... -## Auto assigner - -There is a second plugin, gerrit-owners-autoassign which depends on -gerrit-owners. It will automatically assign all of the owners to review a -change when it's created or updated. - -## How to build +## Building the plugins This plugin is built with Bazel and two build modes are supported:
diff --git a/config.md b/config.md deleted file mode 100644 index 6cba6eb..0000000 --- a/config.md +++ /dev/null
@@ -1,283 +0,0 @@ -## Configuration - -Owner approval is determined based on OWNERS files located in the same -repository on the target branch of the changes uploaded for review. - -The `OWNERS` file has the following YAML structure: - -```yaml -inherited: true -owners: -- some.email@example.com -- User Name -- group/Group of Users -matchers: -- suffix: .java - owners: - [...] -- regex: .*/README.* - owners: - [...] -- partial_regex: example - owners: - [...] -- exact: path/to/file.txt - [...] -``` - -_NOTE: Be aware to double check that emails and full user names correspond to -valid registered Gerrit users. When owner user full name or e-mail cannot be -resolved, a corresponding WARN message is logged on Gerrit error_log and the -user entry dropped._ - -That translates to inheriting owner email address from any parent OWNER files -and to define 'some.email@example.com' or 'User Name' users as the mandatory -reviewers for all changes that include modification to those files. - -To specify a group of people instead of naming individual owners, prefix the -group name or UUID with 'group/'. - -Additional owners can be specified for files selected by other matching -conditions (matchers section). Matching can be done by file suffix, regex -(partial or full) and exact string comparison. For exact match, path is -relative to the root of the repo. - -The plugin analyzes the latest patch set by looking at each file directory and -building an OWNERS hierarchy. It stops once it finds an OWNERS file that has -“inherited” set to false (by default it’s true.) - -For example, imagine the following tree: - -``` -/OWNERS -/example/src/main/OWNERS -/example/src/main/java/com/example/foo/Foo.java -/example/src/main/resources/config.properties -/example/src/test/OWNERS -/example/src/test/java/com/example/foo/FooTest.java -``` - -If you submit a patch set that changes /example/src/main/java/com/example/foo/Foo.java -then the plugin will first open /example/src/main/OWNERS and if inherited is set -to true combine it with the owners listed in /OWNERS. - -If for each patch there is a reviewer who gave a Code-Review +2 then the plugin -will not add any labels, otherwise, it will add ```label('Code-Review from owners', need(_)).``` - -## Global project OWNERS - -Set a OWNERS file into the project refs/meta/config to define a global set of -rules applied to every change pushed, regardless of the folder or target branch. - -Example of assigning every configuration files to a specific owner group: - -```yaml -matchers: -- suffix: .config - owners: - - Configuration Managers -``` - -Global refs/meta/config OWNERS configuration is inherited only when the OWNERS file -contain the 'inherited: true' condition at the top of the file or if they are absent. - -That means that in the absence of any OWNERS file in the target branch, the refs/meta/config -OWNERS is used as global default. - - -## Example 1 - OWNERS file without matchers and default Gerrit submit rules - -Given an OWNERS configuration of: - -```yaml -inherited: true -owners: -- John Doe -- Doug Smith -``` - -And sample rules.pl that uses this predicate to enable the submit rule if -one of the owners has given a Code Review +2 - -```prolog -submit_rule(S) :- - gerrit:default_submit(D), - D =.. [submit | Ds], - findall(U, gerrit:commit_label(label('Code-Review', 2), U), Approvers), - gerrit_owners:add_owner_approval(Approvers, Ds, A), - S =.. [submit | A]. -``` - -Then Gerrit would evaluate the Prolog rule as follows: - -It first gets the current default on rule which gives ok() if no Code-Review -2 -and at least a Code-Review +2 is being provided. - -Then it accumulates in Approvers the list of users who had given Code-Review +2 -and then checks if this list contains either 'John Doe' or 'Doug Smith'. - -If Approvers list does not include one of the owners, then Owner-Approval need() -is added thus making the change not submittable. - -## Example 2 - OWNERS file without matchers and no default Gerrit rules - -Given an OWNERS configuration of: - -```yaml -inherited: true -owners: -- John Doe -- Doug Smith -``` - -And a rule which makes submittable a change if at least one of the owners has -given a +1 without taking into consideration any other label: - -```prolog -submit_rule(S) :- - Ds = [ label(‘owners_plugin_default’,ok(user(100000))) ], - findall(U, gerrit:commit_label(label('Code-Review', 1), U), Approvers), - gerrit_owners:add_owner_approval(Approvers, Ds, A), - S =.. [submit | A]. -``` - -Then Gerrit would make the change Submittable only if 'John Doe' or 'Doug Smith' -have provided at least a Code-Review +1. - -## Example 3 - OWNERS file without matchers and custom _Owner-Approves_ label - -Sometimes to differentiate the _owners approval_ on a change from the code -review on the entire project. The scenario could be for instance the sign-off of -the project's build dependencies based on the Company roles-and-responsibilities -matrix and governance process. - -In this case, we need to grant specific people with the _Owner-Approved_ label -without necessarily having to give Code-Review +2 rights on the entire project. - -Amend the project.config as shown in (1) and add a new label; then give -permissions to any registered user. Finally, define a small variant of the -Prolog rules as shown in (2). - -(1) Example fo the project config changes with the new label with values -(label name and values are arbitrary) - -``` -[label "Owner-Approved"] - function = NoOp - defaultValue = 0 - copyMinScore = true - copyAllScoresOnTrivialRebase = true - value = -1 I don't want this to be merged - value = 0 No score - value = +1 Approved -[access "refs/heads/*"] - label-Owner-Approved = -1..+1 group Registered Users -``` - -(2) Define the project's rules.pl with an amended version of Example 1: - -```prolog -submit_rule(S) :- - gerrit:default_submit(D), - D =.. [submit | Ds], - findall(U, gerrit:commit_label(label('Owner-Approved', 1), U), Approvers), - gerrit_owners:add_owner_approval(Approvers, Ds, A), - S =.. [submit | A]. -``` - -Given now an OWNERS configuration of: - -```yaml -inherited: true -owners: -- John Doe -- Doug Smith -``` - -A change cannot be submitted until John Doe or Doug Smith add a label -"Owner-Approved", independently from being able to provide any Code-Review. - -## Example 4 - Owners based on matchers - -Often the ownership comes from the developer's skills and competencies and -cannot be defined solely by the project's directory structure. -For instance, all the files ending with .sql should be owned and signed-off by -the DBA while all the ones ending with .css by approved by the UX Team. - -Given an OWNERS configuration of: - -```yaml -inherited: true -matchers: -- suffix: .sql - owners: - - Mister Dba -- suffix: .css - owners: - - John Creative - - Matt Designer -``` - -And a rules.pl of: - -```prolog -submit_rule(S) :- - gerrit:default_submit(L), - L =.. [submit | Sr ], - gerrit_owners:add_match_owner_approval(Sr,A), - S =.. [submit | A ]. -``` - -Then for any change that contains files with .sql or .css extensions, besides -to the default Gerrit submit rules, the extra constraints on the additional -owners of the modified files will be added. The final submit is enabled if both -Gerrit default rules are satisfied and all the owners of the .sql files -(Mister Dba) and the .css files (either John Creative or Matt Designer) have -provided their Code-Review +2 feedback. - -The `add_match_owner_approval` predicate would also honour the OWNERS file -without matchers, giving, therefore, the possibility of having different ownership -criteria for different subdirectories. Example: /foo-dir/OWNERS can define a -directory-based ownership while /bar-dir/OWNERS can rely on matching rules. - -__PERFORMANCE NOTE: The predicate `add_match_owner_approval` looks, -at first sight, more powerful and versatile. However, it may generate a significant -number of reductions and therefore, impact the Gerrit server performance. -When used with changes with a high number of files involved, it may even crash -the Gerrit default `rules.reductionLimit`. -When not using any matcher in the OWNERS file, prefer the `add_owner_approval`, -which generates a minimal number of reductions.__ - -## Example 5 - Owners details on a per-file basis - -When using the owners with a series of matchers associated to different set of -owners, it may not be trivial to understand exactly *why* change is not approved -yet. - -We need to define one extra submit rule to scan the entire list of files in the -change and their associated owners and cross-check with the existing Code-Review -feedback received. - -Given the same OWNERS and rules.pl configuration of Example 4 with the following -extra rule: - -```prolog -submit_rule(submit(W)) :- - gerrit_owners:findall_match_file_user(W). -``` - -For every change that would include any .sql or .css file (e.g. my-update.sql -and styles.css) Gerrit will display as additional description on the "need" code -review labels section of the change screen: - -``` -Code-Review from owners -Mister Dba owns my-update.sql -John Creative, Matt Designer own styles.css -``` - -As soon as the owners reviews are provided, the corresponding entry will be -removed from the "need" section of the change. - -In this way, it is always clear which owner needs to provide their feedback on -which file of the change.