Bug 1682547 - Write a simple quick reference guide for managing patches stack r=julienw,sheehan DONTBUILD

Differential Revision: https://phabricator.services.mozilla.com/D99791

docs/contributing/contribution_quickref.rst

@@ -16,7 +16,7 @@ You can use either mercurial or git. `Mercurial <https://www.mercurial-scm.org/d
 
 For git, see the `git cinnabar documentation <https://github.com/glandium/git-cinnabar/wiki/Mozilla:-A-git-workflow-for-Gecko-development>`__
 
-The clone can take from 40 minutes to two hours,(depending on your connection) and
+The clone can take from 40 minutes to two hours (depending on your connection) and
 the repository should be less than 5GB (~ 20GB after the build).
 
 If you have any network connection issues and cannot clone with command, try :ref:`Mercurial bundles <Mercurial bundles>`.
@@ -128,6 +128,7 @@ To visualize your patch in the repository, run:
     # Git
     $ git show
 
+:ref:`More information on how to work with stack of patches <Working with stack of patches Quick Reference>`
 
 :ref:`More information <Mercurial Overview>`
 
@@ -247,6 +248,8 @@ command:
 
 The submission step is the same as for the initial patch.
 
+:ref:`More information on how to work with stack of patches <Working with stack of patches Quick Reference>`
+
 Retrieve new changes from the repository
 ----------------------------------------
 

docs/contributing/stack_quickref.rst

@@ -0,0 +1,103 @@
+Working with stack of patches Quick Reference
+=============================================
+
+Working on Firefox, we strongly recommend working with stack of patches.
+Patches should be small and could be landed in the order used to push them.
+This also helps to breakdown the work for different reviewers.
+
+As it can be complex for new comers, this documentation explains the
+various commands.
+
+For the overall quick reference guide, see the :ref:`Firefox Contributors Quick Reference <Firefox Contributors' Quick Reference>`
+
+Visualize the stack
+-------------------
+
+.. code-block:: shell
+
+    # Mercurial
+    $ hg wip
+
+    # Git
+    $ git log
+
+Reorder the stack
+-----------------
+
+Sometimes, we want to change the order the patches in the stack.
+Fortunately, VCS support this easily.
+
+.. code-block:: shell
+
+    # Mercurial
+    # Just change the order the patch. The tool should highlight
+    # potential risks of conflicts.
+    # Note that ctrl+c works well if used
+    $ hg histedit
+
+    # Git
+    # In the editor, just move the line below/above
+    # Remove everything if you want to cancel the operation
+    $ git rebase -i
+
+
+Make a change on a patch at the beginning of the stack
+------------------------------------------------------
+
+In some cases, the reviewer is asking for a change at the bottom of the stack (ie not at the top).
+So, a simple `hg/git commit --amend` would not work.
+
+In such case, the following approach can be used:
+
+.. code-block:: shell
+
+    # Mercurial
+    # hg will try to guess in which an unambiguous prior commit
+    $ hg absorb
+
+    # if this doesn't work, create a temporary commit
+    # and merge it using "fold" or "roll"
+    $ hg histedit
+
+    # Git
+    $ git commit --fixup <hash of the commit>
+
+
+Removing patches in the stack
+-----------------------------
+
+To remove a patch in the stack:
+
+.. code-block:: shell
+
+    # Mercurial
+    # select "drop" (letter "d")
+    $ hg histedit
+
+    # Git
+    # Replace "pick" by "drop"
+    # Or simply remove the line for this commit
+    $ git rebase -i
+
+
+Rebasing the stack
+------------------
+
+As the codebase moves fast, it can be necessary to pull changes from
+mozilla-central before landing the changes.
+
+.. code-block:: shell
+
+    # Mercurial
+    # First, see where your patches are in the stack
+    $ hg wip
+    # Then, rebase it:
+    # If you are a beginner, don't hesitate to add "--dry-run"
+    $ hg pull
+    $ hg rebase -b . -d central
+
+
+    # Git
+    $ git remote update
+    $ git rebase mozilla/central
+