Add a section about the submit type to the project owner guide

This section provides some help to choose the right submit type.

Change-Id: Iee1d883563fa91f2c1a4de3b00da5c53b847f008
Signed-off-by: Edwin Kempin <edwin.kempin@sap.com>

Documentation/intro-project-owner.txt

@@ -219,6 +219,66 @@ 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.
+
+Please note that there are other submit types available; they are
+described in the link:project-setup.html#submit_type[Submit Type]
+section.
+
 GERRIT
 ------
 Part of link:index.html[Gerrit Code Review]

Documentation/project-setup.txt

@@ -54,6 +54,7 @@ The method Gerrit uses to submit a change to a project can be
 modified by any project owner through the project console, `Projects` >
 `List` > my/project.  The following methods are supported:
 
+[[fast_forward_only]]
 * Fast Forward Only
 +
 This method produces a strictly linear history.  All merges must
@@ -63,6 +64,7 @@ To submit a change, the change must be a strict superset of the
 destination branch.  That is, the change must already contain the
 tip of the destination branch at submit time.
 
+[[merge_if_necessary]]
 * Merge If Necessary
 +
 This is the default for a new project.
@@ -72,6 +74,7 @@ branch, then the branch is fast-forwarded to the change.  If not,
 then a merge commit is automatically created.  This is identical
 to the classical `git merge` behavior, or `git merge --ff`.
 
+[[always_merge]]
 * Always Merge
 +
 Always produce a merge commit, even if the change is a strict
@@ -79,6 +82,7 @@ superset of the destination branch.  This is identical to the
 behavior of `git merge --no-ff`, and may be useful if the
 project needs to follow submits with `git log --first-parent`.
 
+[[cherry_pick]]
 * Cherry Pick
 +
 Always cherry pick the patch set, ignoring the parent lineage
@@ -108,6 +112,7 @@ When Gerrit tries to do a merge, by default the merge will only
 succeed if there is no path conflict.  A path conflict occurs when
 the same file has also been changed on the other side of the merge.
 
+[[content_merge]]
 If `Automatically resolve conflicts` is enabled, Gerrit will try
 to do a content merge when a path conflict occurs.