doc/dev: add proper Merge PR format

This commit adds an example of proper Merge PR format
to the Developer Guide. Though this might not be of
great use to most people, Zac Dover will find it most
helpful.

Fixes: https://tracker.ceph.com/issues/46843
Signed-off-by: Zac Dover <zac.dover@gmail.com>

diff --git a/doc/dev/developer_guide/basic-workflow.rst b/doc/dev/developer_guide/basic-workflow.rst
index 193e372f8c465824de56644feb9d073b26c6db65..6a302c2a036ae030bcbb825605b61f2ea853e9bb 100644 (file)
--- a/doc/dev/developer_guide/basic-workflow.rst
+++ b/doc/dev/developer_guide/basic-workflow.rst
@@ -295,6 +295,54 @@ to change the `Issue tracker`_ status to "Resolved". Some issues may be
 flagged for backporting, in which case the status should be changed to
 "Pending Backport" (see the `Backporting`_ chapter for details).
 
+See also :ref:`merging` for more information on merging.
+
+Proper Merge Commit Format
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This is the most basic form of a merge commit::
+
+       doc/component: title of the commit 
+
+       Reviewed-by: Reviewer Name <rname@example.com>
+
+This consists of two parts:
+
+#. The title of the commit of the pull request to be merged.
+#. The name and email address of the reviewer. Enclose the reviewer's email 
+   address in angle brackets.
+
+Using .githubmap to Find a Reviewer's Email Address
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+If you cannot find the email address of the reviewer on his or her github
+page, you can look it up in the **.githubmap** file, which can be found in
+the repository at **/ceph/.githubmap**.
+
+Using "git log" to find a Reviewer's Email Address
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+If you cannot find a reviewer's email address by using the above methods,
+you can search the git log for their email address. Reviewers are likely
+to have committed something before, and as long as they have committed
+something, the git log will probably contain their email address.
+
+Use the following command::
+
+   [branch under review]$ git log
+
+Using ptl-tool to Generate Merge Commits
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Another method of generating merge commits involves using Patrick Donnelly's
+**ptl-tool** pull commits. This tool can be found at
+**/ceph/src/script/ptl-tool.py**.  Merge commits that have been generated by
+the **ptl-tool** have the following form::
+
+     Merge PR #36257 into master
+     * refs/pull/36257/head:
+             client: move client_lock to _unmount()
+             client: add timer_lock support
+     Reviewed-by: Patrick Donnelly <pdonnell@redhat.com>
+
 
 .. _make check:
 .. _Backporting: ../essentials/#backporting

diff --git a/doc/dev/developer_guide/merging.rst b/doc/dev/developer_guide/merging.rst
index 88f44ddf766ff718065c584cd3446f206efda081..6a8507bbc42f2d2c8368259e4f973e982b652fef 100644 (file)
--- a/doc/dev/developer_guide/merging.rst
+++ b/doc/dev/developer_guide/merging.rst
@@ -1,3 +1,5 @@
+.. _merging:
+
 What is Merged Where and When?
 ===============================