added explanation for "missing Change-Id" error
Added a documentation page that explains the
"missing Change-Id in commit message" error in
details and what can be done to solve the problem.
Signed-off-by: Edwin Kempin <edwin.kempin@gmail.com>
Change-Id: I58a193f4ad86d0a81ff048e7841e322d8b200732
diff --git a/Documentation/error-messages.txt b/Documentation/error-messages.txt
index 607d46e..1e95f3a 100644
--- a/Documentation/error-messages.txt
+++ b/Documentation/error-messages.txt
@@ -9,11 +9,18 @@
Error Messages
--------------
+* link:error-missing-changeid.html[missing Change-Id in commit message]
* link:error-squash-commits-first.html[squash commits first]
* link:error-you-are-not-author.html[you are not author ...]
* link:error-you-are-not-committer.html[you are not committer ...]
+General Hints
+-------------
+
+* link:error-push-fails-due-to-commit-message.html[push fails due to commit message]
+
+
GERRIT
------
Part of link:index.html[Gerrit Code Review]
diff --git a/Documentation/error-missing-changeid.txt b/Documentation/error-missing-changeid.txt
new file mode 100644
index 0000000..5af5f7a
--- /dev/null
+++ b/Documentation/error-missing-changeid.txt
@@ -0,0 +1,56 @@
+missing Change-Id in commit message
+===================================
+
+With this error message Gerrit rejects to push a commit to a project
+which is configured to always require a Change-Id in the commit
+message if the commit message of the pushed commit does not contain
+a Change-Id.
+
+This error may happen for two reasons:
+1. missing Change-Id in the commit message
+2. Change-Id is contained in the commit message but not in the last
+ paragraph
+
+You can see the commit messages for existing commits in the history
+by doing a link:http://www.kernel.org/pub/software/scm/git/docs/git-log.html[git log].
+
+To avoid this error you should use the link:cmd-hook-commit-msg.html[commit hook] or EGit to
+automatically create and insert a unique Change-Id into the commit
+message on every commit.
+
+
+Missing Change-Id in the commit message
+---------------------------------------
+
+If the commit message of a commit that you want to push does not
+contain a Change-Id you have to update its commit message and insert
+a Change-Id.
+
+If you want to upload a new change to Gerrit make sure that you have
+configured your environment so that a unique Change-Id is
+automatically created and inserted on every commit as explained
+above. Now you can rewrite the commits for which the Change-Ids are
+missing and the Change-Ids will be automatically created and inserted
+into the commit messages. This is explained link:error-push-fails-due-to-commit-message.html#commit_hook[here].
+
+If you want to update an existing change in Gerrit by uploading a new
+patch set you should copy its Change-Id from the Gerrit WebUI and
+insert it into the commit message. How to update the commit message
+is explained link:error-push-fails-due-to-commit-message.html[here].
+
+
+Change-Id is contained in the commit message but not in the last paragraph
+--------------------------------------------------------------------------
+
+To be picked up by Gerrit, a Change-Id must be in the last paragraph
+of a commit message, for details, see link:user-changeid.html[Change-Id Lines].
+
+If the Change-Id is contained in the commit message but not in its
+last paragraph you have to update the commit message and move the
+Change-ID into the last paragraph. How to update the commit message
+is explained link:error-push-fails-due-to-commit-message.html[here].
+
+
+GERRIT
+------
+Part of link:error-messages.html[Gerrit Error Messages]
diff --git a/Documentation/error-push-fails-due-to-commit-message.txt b/Documentation/error-push-fails-due-to-commit-message.txt
new file mode 100644
index 0000000..01e0a8e
--- /dev/null
+++ b/Documentation/error-push-fails-due-to-commit-message.txt
@@ -0,0 +1,41 @@
+Push fails due to commit message
+================================
+
+If Gerrit rejects pushing a commit it is often the case that there is
+an issue with the commit message of the pushed commit. In this case
+often the problem can be resolved by fixing the commit message.
+
+If the commit message of the last commit needs to be fixed you can
+simply amend the last commit (please find a detailed description in
+the link:http://www.kernel.org/pub/software/scm/git/docs/git-commit.html[Git documentation]):
+
+----
+ $ git commit --amend
+----
+
+If you need to fix the commit messages of several commits or of any
+commit other than the last one you have to do an interactive git
+rebase for the affected commits. While doing the interactive rebase
+you can e.g. choose 'reword' for those commits for which you want to
+fix the commit messages. For a detailed description of git rebase
+please check the link:http://www.kernel.org/pub/software/scm/git/docs/git-rebase.html[Git documentation].
+
+Please use interactive git rebase with care as it rewrites existing
+commits. Generally you should never rewrite commits that have already
+been submitted in Gerrit.
+
+[[commit_hooks]]
+Sometimes commit hooks are used to automatically insert/update
+information in the commit message. If such information is missing in
+the commit message of existing commits (e.g. because the commit hook
+was only configured later) rewriting the commits will (re)execute the
+commit hook and so update the commit messages. If you do an
+interactive rebase to achieve this make sure that the affected
+commits are really rewritten, e.g. by choosing 'reword' for all these
+commits and then confirming all the commit messages. Just picking a
+commit may not rewrite it.
+
+
+GERRIT
+------
+Part of link:error-messages.html[Gerrit Error Messages]
