Merge changes Iee1d8835,Id1f4172d into stable-2.9

* changes:
  Add a section about the submit type to the project owner guide
  Document project options

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

@@ -44,13 +44,17 @@ Either restart the server, or flush the `project_list` cache:
   ssh -p 29418 localhost gerrit flush-caches --cache project_list
 ====
 
+[[project_options]]
+== Project Options
+
 [[submit_type]]
-== Submit Type
+=== Submit Type
 
 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
@@ -60,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.
@@ -69,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
@@ -76,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
@@ -105,9 +112,88 @@ 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.
 
+=== State
+
+This setting defines the state of the project. A project can have the
+following states:
+
+- `Active`:
++
+The project is active and users can see and modify the project according
+to their access rights on the project.
+
+- `Read Only`:
++
+The project is read only and all modifying operations on it are
+disabled. E.g. this means that pushing to this project fails for all
+users even if they have push permissions assigned on it.
++
+Setting a project to this state is an easy way to temporary close a
+project, as you can keep all write access rights in place and they will
+become active again as soon as the project state is set back to
+`Active`.
++
+This state also makes sense if a project was moved to another location.
+In this case all new development should happen in the new project and
+you want to prevent that somebody accidentally works on the old
+project, while keeping the old project around for old references.
+
+- `Hidden`:
++
+The project is hidden and only visible to project owners. Other users
+are not able to see the project even if they have read permissions
+granted on the project.
+
+=== Require Change-Id
+
+The `Require Change-Id in commit message` option defines whether a
+link:user-changeid.html[Change-Id] in the commit message is required
+for pushing a commit for review. If this option is set, trying to push
+a commit for review that doesn't contain a Change-Id in the commit
+message fails with link:error-missing-changeid.html[missing Change-Id
+in commit message footer].
+
+It is recommended to set this option and use a
+link:user-changeid.html#create[commit-msg hook] (or other client side
+tooling like EGit) to automatically generate Change-Id's for new
+commits. This way the Change-Id is automatically in place when changes
+are reworked or rebased and uploading new patch sets gets easy.
+
+If this option is not set, commits can be uploaded without a Change-Id,
+but then users have to remember to copy the assigned Change-Id from the
+change screen and insert it manually into the commit message when they
+want to upload a second patch set.
+
+=== Maximum Git Object Size Limit
+
+This option defines the maximum allowed Git object size that
+receive-pack will accept. If an object is larger than the given size
+the pack-parsing will abort and the push operation will fail.
+
+With this option users can be prevented from uploading commits that
+contain files which are too large.
+
+Normally the link:config-gerrit.html#receive.maxObjectSizeLimit[maximum
+Git object size limit] is configured globally for a Gerrit server. At
+the project level, the maximum Git object size limit can be further
+reduced, but not extended. The displayed effective limit shows the
+maximum Git object size limit that is actually used on the project.
+
+The defined maximum Git object size limit is inherited by any child
+project.
+
+=== Require Signed-off-by
+
+The `Require Signed-off-by in commit message` option defines whether a
+link:user-signedoffby.html[Signed-off-by] line in the commit message is
+required for pushing a commit. If this option is set, trying to push a
+commit that doesn't contain a Signed-off-by line in the commit message
+fails with link:error-not-signed-off-by.html[not Signed-off-by
+author/committer/uploader in commit message footer].
 
 == Registering Additional Branches