gerrit/Documentation/intro-project-owner.txt

= Project Owner Guide

This is a Gerrit guide that is dedicated to project owners. It
explains the many possibilities that Gerrit provides to customize the
workflows for a project.

[[project-owner]]
== What is a project owner?

Being project owner means that you own a project in Gerrit.
Technically this is expressed by having the
link:access-control.html#category_owner[Owner] access right on
`refs/*` on that project. As project owner you have the permission to
edit the access control list and the project settings of the project.
It also means that you should get familiar with these settings so that
you can adapt them to the needs of your project.

Being project owner means being responsible for the administration of
a project. This requires having a deeper knowledge of Gerrit than the
average user. Normally per team there should be 2 to 3 persons, who
have a certain level of Git/Gerrit knowledge, assigned as project
owners. It normally doesn't make sense that everyone in a team is
project owner. For normal team members it is sufficient to be committer
or contributor.

[[access-rights]]
== Access Rights

As a project owner you can edit the access control list of your
project. This allows you to grant permissions on the project to
different groups.

Gerrit comes with a rich set of permissions which allow a very
fine-grained control over who can do what on a project. Access
control is one of the most powerful Gerrit features but it is also a
rather complex topic. This guide will only highlight the most
important aspects of access control, but the link:access-control.html[
Access Control] chapter explains all the details.

[[edit-access-rights]]
=== Editing Access Rights

To see the access rights of your project

- go to the Gerrit WebUI
- click on the `Projects` > `List` menu entry
- find your project in the project list and click on it
- click on the `Access` menu entry

By clicking on the `Edit` button the access rights become editable and
you may save any changes by clicking on the `Save Changes` button.
Optionally you can provide a `Commit Message` to explain the reasons
for changing the access rights.

The access rights are stored in the project's Git repository in a
special branch called `refs/meta/config`. On this branch there is a
`project.config` file which contains the access rights. More
information about this storage format can be found in the
link:config-project-config.html[Project Configuration File Format]
chapter. What is important to know is that by looking at the history
of the `project.config` file on the `refs/meta/config` branch you can
always see how the access rights were changed and by whom. If a good
commit message is provided you can also see from the history why the
access rights were modified.

If a Git browser such as GitWeb is configured for the Gerrit server you
can find a link to the history of the `project.config` file in the
WebUI. Otherwise you may inspect the history locally. If you have
cloned the repository you can do this by executing the following
commands:

====
  $ git fetch origin refs/meta/config:config
  $ git checkout config
  $ git log project.config
====

Non project owners may still edit the access rights and propose the
modifications to the project owners by clicking on the `Save for
Review` button. This creates a new change with the access rights
modifications that can be approved by a project owner. The project
owners are automatically added as reviewer on this change so that they
get informed about it by email.

[[inheritance]]
=== Inheritance

Normally when a new project is created in Gerrit it already has some
access rights which are inherited from the parent projects.
Projects in Gerrit are organized hierarchically as a tree with the
`All-Projects' project as root from which all projects inherit. Each
project can have only a single parent project, multi-inheritance is
not supported.

Looking at the access rights of your project in the Gerrit WebUI, you
only see the access rights which are defined on that project. To see
the inherited access rights you must follow the link to the parent
project under `Rights Inherit From`.

Inherited access rights can be overwritten unless they are defined as
link:access-control.html#block[BLOCK rule]. BLOCK rules are used to
limit the possibilities of the project owners on the inheriting
projects. With this, global policies can be enforced on all projects.
Please note that Gerrit doesn't prevent you from assigning access
rights that contradict an inherited BLOCK rule, but these access rights
will simply have no effect.

If you are responsible for several projects which require the same
permissions, it makes sense to have a common parent for them and to
maintain the access rights on that common parent. Changing the parent
of a project is only allowed for Gerrit administrators. This means you
need to contact the administrator of your Gerrit server if you want to
reparent your project. One way to do this is to change the parent
project in the WebUI, save the modifications for review and get the
change approved and merged by a Gerrit administrator.

[[refs]]
=== References

Access rights in Gerrit are assigned on references (aka refs). Refs in
Git exist in different namespaces, e.g. all branches normally exist
under `refs/heads/` and all tags under `refs/tags/`. In addition there
are a number of link:access-control.html#references_special[special refs]
and link:access-control.html#references_magic[magic refs].

Access rights can be assigned on a concrete ref, e.g.
`refs/heads/master` but also on ref patterns and regular expressions
for ref names.

A ref pattern ends with `/*` and describes a complete ref name
namespace, e.g. access rights assigned on `refs/heads/*` apply to all
branches.

Regular expressions must start with `^`, e.g. access rights assigned
on `^refs/heads/rel-.*` would apply to all `rel-*` branches.

[[groups]]
=== Groups

Access rights are granted to groups. It is useful to know that Gerrit
maintains its own groups internally but also supports different external
group backends.

The Gerrit internal groups can be seen in the Gerrit WebUI by clicking
on the `Groups` > `List` menu entry. By clicking on a group you can
edit the group members (`Members` tab) and the group options
(`General` tab).

Gerrit internal groups contain users as members, but can also include
other groups, even external groups.

Every group is owned by an owner group. Only members of the owner
group can administrate the owned group (assign members, edit the group
options). A group can own itself; in this case members of the group
can, for example, add further members to the group. When you create new
groups for your project to assign access rights to committer or other
roles, make sure that they are owned by the project owner group.

An important setting on a group is the option
`Make group visible to all registered users.`, which defines whether
non-members can see who is member of the group.

New internal Gerrit groups can be created under `Groups` >
`Create New Group`. This menu is only available if you have the global
capability link:access-control.html#capability_createGroup[Create Group]
assigned.

Gerrit also has a set of special
link:access-control.html#system_groups[system groups] that you might
find useful.

External groups need to be prefixed when assigning access rights to
them, e.g. link:access-control.html#ldap_groups[LDAP group names] need
to be prefixed with `ldap/`.

If the link:https://gerrit-review.googlesource.com/#/admin/projects/plugins/singleusergroup[
singleusergroup] plugin is installed you can also directly assign
access rights to users, by prefixing the username with `user/` or the
user's account ID by `userid/`.

[[common-access-rights]]
=== Common Access Rights

Different roles in a project, such as developer (committer) or
contributor, need different access rights. Examples for which access
rights are typically assigned for which role are described in the
link:access-control.html#example_roles[Access Control] chapter.

[[code-review]]
=== Code Review

Gerrit's main functionality is code review, however using code review
is optional and you may decide to only use Gerrit as a Git server with
access control. Whether you allow only pushes for review or also
direct pushes depends on the project's access rights.

To push a commit for review it must be pushed to
link:access-control.html#refs_for[refs/for/<branch-name>]. This means
the link:access-control.html#category_push_review[Push] access right
must be assigned on `refs/for/<branch-name>`.

To allow direct pushes and bypass code review, the
link:access-control.html#category_push_direct[Push] access right is
required on `refs/heads/<branch-name>`.

By pushing for review you are not only enabling the review workflow,
but you can also get automatic verifications from a build server
before changes are merged. In addition you can benefit from Gerrit's
merge strategies that can automatically merge/rebase commits on server
side if necessary. You can control the merge strategy by configuring
the link:project-setup.html#submit_type[submit type] on the project.
If you bypass code review you always need to merge/rebase manually if
the tip of the destination branch has moved. Please keep this in mind
if you choose to not work with code review because you think it's
easier to avoid the additional complexity of the review workflow; it
might actually not be easier.

You may also enable link:user-upload.html#auto_merge[auto-merge on
push] to benefit from the automatic merge/rebase on server side while
pushing directly into the repository.

[[project-options]]
== Project Options

As project owner you can control several options on your project.
The different options are described in the
link:project-setup.html#project_options[Project Options] section.

To see the options of your project

- go to the Gerrit WebUI
- click on the `Projects` > `List` menu entry
- find your project in the project list and click on it
- click on the `General` menu entry

[[submit-type]]
=== Submit Type

An important decision for a project is the choice of the submit type
and the content merge setting (aka `Automatically resolve conflicts`).
The link:project-setup.html#submit_type[submit type] is the method
Gerrit uses to submit a change to the project. The submit type defines
what Gerrit should do on submit of a change if the destination branch
has moved while the change was in review. The
link:project-setup.html#content_merge[content merge] setting applies
if the same files have been modified concurrently and tells Gerrit
whether it should attempt a content merge for these files.

When choosing the submit type and the content merge setting one must
weigh development comfort against the safety of not breaking the
destination branch.

The most restrictive submit type is
link:project-setup.html#fast_forward_only[Fast Forward Only]. Using
this submit type means that after submitting one change all other open
changes for the same destination branch must be rebased manually. This
is quite burdensome and in practice only feasible for branches with
very few changes. On the other hand, if changes are verified before
submit, e.g. automatically by a CI integration, with this submit type,
you can be sure that the destination branch never gets broken.

Choosing link:project-setup.html#merge_if_necessary[Merge If Necessary]
as submit type makes the life for developers more comfortable,
especially if content merge is enabled. If this submit strategy is used
developers only need to rebase manually if the same files have been
modified concurrently or if the content merge on such a file fails. The
drawback with this submit type is that there is a risk of breaking
the destination branch, e.g. if one change moves a class into another
package and another change imports this class from the old location.
Experience shows that in practice `Merge If Necessary` with content
merge enabled works pretty well and breaking the destination branch
happens rarely. This is why this setting is recommended at least for
development branches. You likely want to start with
`Merge If Necessary` with content merge enabled and only switch to a
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.

[[notifications]]
== Email Notifications

With Gerrit individual users control their own email subscriptions. By
editing the link:user-notify.html#user[watched projects] in the WebUI
under `Settings` > `Watched Projects` users can decide which events to
be informed about by email. The change notifications can be filtered by
link:user-search.html[change search expressions].

This means as a project owner you normally don't need to do anything
about email notifications, except maybe telling your project team where
to configure the watches.

Gerrit also supports link:user-notify.html#project[notifications on
project level] that allow project owners to set up email notifications
for team mailing lists or groups of users. This configuration is done
in the `project.config` file in the `refs/meta/config` branch as
explained in the section about link:user-notify.html#project[project
level notifications].

GERRIT
------
Part of link:index.html[Gerrit Code Review]

SEARCHBOX
---------