Revamp the documentation of the submit strategies
* Merge the 'Submit Type' section into the section that describes the
'submit.action' configuration parameter.
* Make it clear that 'submit action', 'submit type' and also
'submit strategy' are all synonymous terms.
* Add a hint explaining that the values to be set for submit.action in
project.config indeed contain spaces (e.g. it's 'merge if necessary'
and not 'merge_if_necessary').
* Keep existing anchors so that they continue working.
* Fix name of the 'Merge Always' submit action, which was wrongly
documented as 'Always Merge'.
* Explicitly mention that 'cherry pick' is the only action that ignores
dependencies.
* Order the submit actions by importance, starting with the most used
submit action 'merge if necessary' and ending with the least
recommended submit actions 'fast-forward-only' and 'cherry-pick'.
* Fix various formatting issues.
* Consistently wrap lines after 80 characters.
This revamp is just a first step to rework this documentation and
further improvements by follow-up changes are necessary. E.g. the
descriptions of the different submit actions have not been updated yet
and are still suboptimal and inconsistent.
Signed-off-by: Edwin Kempin <ekempin@google.com>
Release-Notes: skip
Change-Id: I0dd66d71f3989308cba32330412e4f90052f7a86
diff --git a/Documentation/config-project-config.txt b/Documentation/config-project-config.txt
index 9fd5b1b..dfb9425 100644
--- a/Documentation/config-project-config.txt
+++ b/Documentation/config-project-config.txt
@@ -326,9 +326,104 @@
[[submit.action]]submit.action::
+
-Defines the link:#submit-type[submit type]. Valid
-values are 'fast forward only', 'merge if necessary', 'rebase if necessary',
-'rebase always', 'merge always' and 'cherry pick'. The default is 'merge if necessary'.
+Defines the submit action aka submit type aka submit strategy that Gerrit
+should use to integrate changes into the target branch when they are submitted.
++
+In general, submitting a change only merges the change if all its dependencies
+are also submitted. The only exception is the `cherry pick` submit action which
+ignores dependencies (see link:#cherry_pick[below]).
++
+[[submit-type]]
+--
+The following submit actions are supported:
+
+[[merge_if_necessary]]
+* 'merge if necessary':
++
+If the change being submitted is a strict superset of the destination 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]]
+[[merge_always]]
+* 'merge always':
++
+Always produce a merge commit, even if the change is a strict 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`.
+
+[[rebase_if_necessary]]
+* 'rebase if necessary':
++
+If the change being submitted is a strict superset of the destination branch,
+then the branch is fast-forwarded to the change. If not, then the change is
+automatically rebased and then the branch is fast-forwarded to the change.
++
+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.
+
+[[rebase_always]]
+* 'rebase always':
++
+Basically, the same as `rebase if necessary`, but it creates a new patchset
+even if fast forward is possible and like `cherry pick` it ensures footers such
+as `Change-Id`, `Reviewed-On`, and others are present in resulting commit that
+is merged.
++
+Thus, `rebase always` can be considered similar to `cherry pick`, but with the
+important distinction that `rebase always` does not ignore dependencies.
+
+[[fast_forward_only]]
+* 'fast forward only':
++
+With this action Gerrit does not create merge commits on submitting a change.
+Merge commits may still be submitted, but they must be created on the client
+prior to uploading to Gerrit for review.
++
+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.
+
+[[cherry_pick]]
+* 'cherry pick':
++
+Always cherry pick the patch set, ignoring the parent lineage and instead
+creating a brand new commit on top of the current branch head.
++
+When cherry picking a change, Gerrit automatically appends onto the end of the
+commit message a short summary of the change's approvals, and a URL link back
+to the change on the web. The committer header is also set to the submitter,
+while the author header retains the original patch set author.
++
+Note that Gerrit ignores dependencies between changes when using this submit
+action unless
+link:config-gerrit.html#change.submitWholeTopic[`change.submitWholeTopic`]
+is enabled and depending changes share the same topic. So generally submitters
+must remember to submit changes in the right order when using this submit action.
+If all you want is extra information in the commit message, consider using the
+`rebase always` submit strategy.
+
+--
++
+[[submit_type_inherit]]
+In addition the submit action can be set to `Inherit`, which means that the
+value that is configured in the parent project applies. For new projects
+`Inherit` is the default, unless the default is overridden by the global
+link:config-gerrit.html#repository.name.defaultSubmitType[defaultSubmitType]
+configuration. Configuring `Inherit` for the `All-Projects` root project is
+equivalent to configuring link:#merge_if_necessary[merge if necessary].
++
+If `submit.action` is not set, the default is 'merge if necessary'.
++
+NOTE: For the value of `submit.action` in `project.config` use the exact
+spelling as given above, e.g. 'merge if necessary' (without the single quotes,
+but with the spaces).
++
+NOTE: Project owners can also set the submit action in the Gerrit UI:
+`Browse` > `Repositories` > my/repository > `Submit type`
[[submit.matchAuthorToCommitterDate]]submit.matchAuthorToCommitterDate::
+
@@ -346,98 +441,6 @@
is set to 'true' the merge would fail in such a case. An empty commit is still allowed as the
initial commit on a branch.
-[[submit-type]]
-==== Submit Type
-
-'submit.action': The method Gerrit uses to submit a change to a project.
-
-The submit type can also be modified by any project owner through the
-project console, `Browse` > `Repositories` > my/project > 'Submit type'.
-In general, a submitting a change only merges the change if all its
-dependencies are also submitted, with exceptions documented below.
-
-The following submit types are supported:
-
-[[submit_type_inherit]]
-* Inherit
-+
-This is the default for new projects, unless overridden by a global
-link:config-gerrit.html#repository.name.defaultSubmitType[`defaultSubmitType` option].
-+
-Inherit the submit type from the parent project. In `All-Projects`, this
-is equivalent to link:#merge_if_necessary[Merge If Necessary].
-
-[[fast_forward_only]]
-* Fast Forward Only
-+
-With this method Gerrit does not create merge commits on submitting a
-change. Merge commits may still be submitted, but they must be created
-on the client prior to uploading to Gerrit for review.
-+
-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
-+
-If the change being submitted is a strict superset of the destination
-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
-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
-and instead creating a brand new commit on top of the current
-branch head.
-+
-When cherry picking a change, Gerrit automatically appends onto the
-end of the commit message a short summary of the change's approvals,
-and a URL link back to the change on the web. The committer header
-is also set to the submitter, while the author header retains the
-original patch set author.
-+
-Note that Gerrit ignores dependencies between changes when using this
-submit type unless
-link:config-gerrit.html#change.submitWholeTopic[`change.submitWholeTopic`]
-is enabled and depending changes share the same topic. So generally
-submitters must remember to submit changes in the right order when using this
-submit type. If all you want is extra information in the commit message,
-consider using the Rebase Always submit strategy.
-
-[[rebase_if_necessary]]
-* Rebase If Necessary
-+
-If the change being submitted is a strict superset of the destination
-branch, then the branch is fast-forwarded to the change. If not,
-then the change is automatically rebased and then the branch is
-fast-forwarded to the change.
-+
-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.
-
-[[rebase_always]]
-* Rebase Always
-+
-Basically, the same as Rebase If Necessary, but it creates a new patchset even
-if fast forward is possible AND like Cherry Pick it ensures footers such as
-Change-Id, Reviewed-On, and others are present in resulting commit that is
-merged.
-+
-Thus, Rebase Always can be considered similar to Cherry Pick, but with
-the important distinction that Rebase Always does not ignore dependencies.
-
[[access-section]]
=== Access section
