[PATCH] D15801: Improve the documentation on committing code reviewed on Phabricator to trunk.

[Dan Liew via llvm-commits]

delcypher created this revision.
delcypher added reviewers: klimek, chandlerc.
delcypher added subscribers: llvm-commits, reames, nwilson.

[docs] Improve the documentation on committing code reviewed on
Phabricator to trunk.

The previous documentation had a few issues:

* It did not make it explicit that code could be
committed without using the Arcanist tool and how this should be done.

* There was also an implicit assumption on using Subversion
rather than git-svn in the example using Arcanist. The documentation now
explicitly mentions both cases and details how to commit to trunk in
each case.


http://reviews.llvm.org/D15801

Files:
  docs/GettingStarted.rst
  docs/Phabricator.rst

Index: docs/Phabricator.rst
===================================================================
--- docs/Phabricator.rst
+++ docs/Phabricator.rst
@@ -127,31 +127,70 @@
 Committing a change
 -------------------
 
+Once a patch has been reviewed and approved on Phabricator it can then be
+committed to trunk.  There are multiple workflows to achieve this. Which
+ever method you follow you must ensure that your commit message ends with
+the line:
+
+::
+
+  Differential Revision: <URL>
+
+where ``<URL>`` is the URL for the code review, starting with
+``http://reviews.llvm.org/``.
+
+This allows people reading the version history to see the review for
+context. This also allows Phabricator to detect the commit, close the
+review, and add a link from the review to the commit.
+
+Note that if you use the Arcanist tool this line will be added this
+automatically. If you don't want to use Arcanist just commit as
+normal making sure the commit message is formatted as mentioned above.
+
 Arcanist can manage the commit transparently. It will retrieve the description,
 reviewers, the ``Differential Revision``, etc from the review and commit it to the repository.
 
+Subversion and Arcanist
+^^^^^^^^^^^^^^^^^^^^^^^
+
+On a clean Subversion working copy run the following (where ``<Revision>`` is
+the Phabricator review number):
+
 ::
 
   arc patch D<Revision>
   arc commit --revision D<Revision>
 
+The first command will take the latest version of the reviewed patch and apply it to the working
+copy. The second command will commit this revision to trunk.
+
+git-svn and Arcanist
+^^^^^^^^^^^^^^^^^^^^
 
-When committing an LLVM change that has been reviewed using
-Phabricator, the convention is for the commit message to end with the
-line:
+This presumes that the git repository has been configured as described in :ref:`developers-work-with-git-svn`.
+
+On a clean Git repository on an up to date ``master`` branch run the
+following (where ``<Revision>`` is the Phabricator review number):
 
 ::
 
-  Differential Revision: <URL>
+  arc patch D<Revision>
 
-where ``<URL>`` is the URL for the code review, starting with
-``http://reviews.llvm.org/``.
 
-Note that Arcanist will add this automatically.
+This will create a new branch called ``arcpatch-D<Revision>`` based on the
+current ``master`` and will create a commit corresponding to ``D<Revision>`` with a
+commit message derived from information in the Phabricator review.
+
+Check you are happy with the commit message and amend it if necessary. Now switch to
+the ``master`` branch and add the new commit to it and commit it to trunk. This
+can be done by running the following:
+
+::
+
+  git checkout master
+  git merge --ff-only arcpatch-D<Revision>
+  git svn dcommit
 
-This allows people reading the version history to see the review for
-context.  This also allows Phabricator to detect the commit, close the
-review, and add a link from the review to the commit.
 
 Abandoning a change
 -------------------
Index: docs/GettingStarted.rst
===================================================================
--- docs/GettingStarted.rst
+++ docs/GettingStarted.rst
@@ -626,6 +626,8 @@
   ; example for Traditional Chinese
         folder = "[Gmail]/&g0l6Pw-"
 
+.. _developers-work-with-git-svn:
+
 For developers to work with git-svn
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 


-------------- next part --------------
A non-text attachment was scrubbed...
Name: D15801.43714.patch
Type: text/x-patch
Size: 3355 bytes
Desc: not available
URL: <http://lists.llvm.org/pipermail/llvm-commits/attachments/20151229/95237bce/attachment.bin>