docs/contributing/stack_quickref.rst

   1 Working with stack of patches Quick Reference
   2 =============================================
   3
   4 Working on Firefox, we strongly recommend working with stack of patches.
   5 Patches should be small and could be landed in the order used to push them.
   6 This also helps to breakdown the work for different reviewers.
   7
   8 As it can be complex for newcomers, this documentation explains the
   9 various commands.
  10
  11 In Phabricator, the stack can be seen in the `Revision Contents` section.
  12 The top of the stack (most recent change) is first in the list.
  13
  14 This is also sometimes called "stack of revisions", "stack of commits" or "series of commits".
  15
  16 **Example:**
  17
  18 .. image:: img/example-stack.png
  19
  20
  21 For the overall quick reference guide, see the :ref:`Firefox Contributors Quick Reference <Firefox Contributors' Quick Reference>`
  22
  23 Visualize the stack
  24 -------------------
  25
  26 .. code-block:: shell
  27
  28     # Mercurial
  29     $ hg wip
  30
  31     # Git
  32     $ git log
  33
  34
  35 Merge two patches
  36 -----------------
  37
  38 It can happen that, instead of updating a patch, a new revision is
  39 created on Phabricator. For this, merge the patches locally:
  40
  41 .. code-block:: shell
  42
  43     # Mercurial
  44     # Mark the patch to be merged with "roll" (key: "r")
  45     # or "fold" (key: "f")
  46     $ hg histedit
  47
  48     # Git
  49     # Replace "pick" by "squash" or "fixup"
  50     $ git rebase -i
  51
  52 Then, push to Phabricator and abandon the old change.
  53
  54
  55 Submitting the first patch on the stack
  56 ---------------------------------------
  57
  58 There are times when you are working on multiple patches and
  59 just want to submit the first one. For this, you can use:
  60
  61 .. code-block:: shell
  62
  63     $ moz-phab submit .
  64
  65
  66 Reorder the stack
  67 -----------------
  68
  69 Sometimes, we want to change the order the patches in the stack.
  70 Fortunately, VCS support this easily.
  71
  72 .. code-block:: shell
  73
  74     # Mercurial
  75     # Just change the order of the patches. The tool should highlight
  76     # potential risks of conflicts.
  77     # Note that ctrl+c works well if used.
  78     $ hg histedit
  79
  80     # Git
  81     # In the editor, just move the patches to the line below/above to
  82     # reorder commits.
  83     # Remove everything if you want to cancel the operation.
  84     $ git rebase -i
  85
  86
  87 Make a change on a patch at the beginning of the stack
  88 ------------------------------------------------------
  89
  90 In some cases, the reviewer is asking for a change at the bottom of the stack (ie not at the top).
  91 So, a simple `hg/git commit --amend` would not work.
  92
  93 In such case, the following approach can be used:
  94
  95 .. code-block:: shell
  96
  97     # Mercurial
  98     # hg will try to guess in which an unambiguous prior commit
  99     $ hg absorb
 100
 101     # if this doesn't work, create a temporary commit
 102     # and merge it using "fold" or "roll"
 103     $ hg histedit
 104
 105     # Git
 106     $ git commit --fixup <hash of the commit>
 107
 108
 109 Removing patches in the stack
 110 -----------------------------
 111
 112 To remove a patch in the stack:
 113
 114 .. code-block:: shell
 115
 116     # Mercurial
 117     # select "drop" (letter "d")
 118     $ hg histedit
 119
 120     # Git
 121     # Replace "pick" by "drop"
 122     # Or simply remove the line for this commit
 123     $ git rebase -i
 124
 125
 126 Rebasing the stack
 127 ------------------
 128
 129 As the codebase moves fast, it can be necessary to pull changes from
 130 mozilla-central before landing the changes.
 131
 132 .. code-block:: shell
 133
 134     # Mercurial
 135     # First, see where your patches are in the stack
 136     $ hg wip
 137     # Then, rebase it:
 138     # If you are a beginner, don't hesitate to add "--dry-run"
 139     $ hg pull
 140     $ hg rebase -b . -d central
 141
 142
 143     # Git
 144     $ git remote update
 145     $ git rebase mozilla/central
 146
 147
 148 Reorganizing the stack in Phabricator
 149 -------------------------------------
 150
 151 .. code-block:: shell
 152
 153     $ moz-phab reorg [start_rev] [end_rev]
 154
 155 allows you to reorganize the stack in Phabricator.
 156
 157 If you've changed the local stack by adding, removing or moving the commits around, you need to change the parent/child relation of the revisions in Phabricator.
 158
 159 .. code-block:: shell
 160
 161     $ moz-phab reorg
 162
 163 command will compare the stack, display what will be changed and ask for permission before taking any action.
 164
 165 .. note::
 166
 167     Note that reviewbot will not restart the analysis.