Merge changes Iee1d8835,Id1f4172d into stable-2.9
* changes: Add a section about the submit type to the project owner guide Document project options
This commit is contained in:
Martin Fick
@@ -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]
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
Reference in New Issue
Block a user