From 7036391b780871cf25ad6ce7770daa94e31da8b5 Mon Sep 17 00:00:00 2001 From: Edwin Kempin Date: Thu, 17 Apr 2014 16:53:38 +0200 Subject: [PATCH 1/2] Document project options Change-Id: Id1f4172d8e6f7182c4eb5f0e90913553e6ca1dce Signed-off-by: Edwin Kempin --- Documentation/project-setup.txt | 83 ++++++++++++++++++++++++++++++++- 1 file changed, 82 insertions(+), 1 deletion(-) diff --git a/Documentation/project-setup.txt b/Documentation/project-setup.txt index 82bc1eaee7..1e4c829d9f 100644 --- a/Documentation/project-setup.txt +++ b/Documentation/project-setup.txt @@ -44,8 +44,11 @@ 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` > @@ -108,6 +111,84 @@ the same file has also been changed on the other side of the 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 From eaff6c1d45caf86f7721e8443f974424b6371ac3 Mon Sep 17 00:00:00 2001 From: Edwin Kempin Date: Thu, 17 Apr 2014 15:23:42 +0200 Subject: [PATCH 2/2] 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 --- Documentation/intro-project-owner.txt | 60 +++++++++++++++++++++++++++ Documentation/project-setup.txt | 5 +++ 2 files changed, 65 insertions(+) diff --git a/Documentation/intro-project-owner.txt b/Documentation/intro-project-owner.txt index 63d8d6c703..14912bf295 100644 --- a/Documentation/intro-project-owner.txt +++ b/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] diff --git a/Documentation/project-setup.txt b/Documentation/project-setup.txt index 1e4c829d9f..b83d46f4fd 100644 --- a/Documentation/project-setup.txt +++ b/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.