Changes between Version 6 and Version 7 of org/teams/NetworkTeam/MergeProcess


Ignore:
Timestamp:
Dec 3, 2019, 12:27:37 AM (12 months ago)
Author:
teor
Comment:

Formatting fixes

Legend:

Unmodified
Added
Removed
Modified
  • org/teams/NetworkTeam/MergeProcess

    v6 v7  
    1717==== Master and Backport Merges ====
    1818
    19 1. Make sure you have the git hooks installed.
    20 
    21   You can find the hooks in `tor/scripts/git/`. They need to be copied into tor/.git/hooks, without the extension:
    22     * tor/scripts/git/post-merge.git-hook -> .git/hooks/post-merge
    23     * (repeat for the other hooks)
    24 
    25   Q: How do I keep the git hooks up to date?
    26 
    27   A: Install the post-merge (post pull) hook, so git logs a message when the hooks are updated in master. (See #29588.)
    28 
    29 2. Clone and configure your git repository
    30 
    31   You might find it easier to use a separate git repository for merges and regular coding.
     19===== 1. Make sure you have the git hooks installed =====
     20
     21You can find the hooks in `tor/scripts/git/`. They need to be copied into tor/.git/hooks, without the extension:
     22  * tor/scripts/git/post-merge.git-hook -> .git/hooks/post-merge
     23  * (repeat for the other hooks)
     24
     25Q: How do I keep the git hooks up to date?
     26A: Install the post-merge (post pull) hook, so git logs a message when the hooks are updated in master. (See #29588.)
     27
     28===== 2. Clone and configure your git repository =====
     29
     30You might find it easier to use a separate git repository for merges and regular coding.
    3231
    3332**Automatic Setup**
    3433
    35   Set TOR_FULL_GIT_PATH in your .profile, and run `git-setup-dirs.sh`.
    36   (This script sets up backport worktrees as well - you can just ignore them.)
     34Set TOR_FULL_GIT_PATH in your .profile, and run `git-setup-dirs.sh`.
     35(This script sets up backport worktrees as well - you can just ignore them.)
    3736
    3837**Manual Setup**
    3938
    40   Configure your repository with:
    41 
    42   * git-rw.torproject.org:tor.git as "origin" and
    43   * github.com/torproject/tor.git as "tor-github".
    44 
    45   {{{
    46   $ git remote add tor-github https://github.com/torproject/tor.git
    47   }}}
    48 
    49   Piece of advise here. Because git default behavior of "git push" is to use
    50   "origin", then mistake can happen where one of us can push a personal branch
    51   to our upstream tor.git.
    52 
    53   For that I nullify the "pushurl" of origin with:
    54 
    55   {{{
    56   [remote "origin"]
    57     fetch = +refs/heads/*:refs/remotes/origin/*
    58     url = https://git.torproject.org/tor.git
    59     pushurl = "Don't push personal branches to origin!"
    60   }}}
    61 
    62   To push now, I created an "upstream" remote so when I push commits upstream, I
    63   have to explicitly type in:
    64 
    65   {{{
    66   $ git push upstream <branch>
    67   }}}
    68 
    69   (The git-push-all.sh allows you to specific the name of the "upstream"
    70   branch).
    71 
    72   To add the upstream remote properly:
    73 
    74   {{{
    75   $ git remote add upstream https://git.torproject.org/tor.git
    76   $ git remote set-url --push upstream ssh://git@git-rw.torproject.org/tor.git
    77   }}}
    78 
    79   Make sure you have PRs from tor-github set up to be named
    80   tor-github/pr/NNN, where NNN is the number of the PR.
    81 
    82   In your gitconfig:
    83 
    84   {{{
    85   [remote "tor-github"]
    86      fetch = +refs/heads/*:refs/remotes/tor-github/*
    87      fetch = +refs/pull/*:refs/remotes/tor-github/pr/*
    88   }}}
    89 
    90   This sets up pull requests as:
    91     * tor-github/pr/NNNN/head - the branch you want to merge
    92     * tor-github/pr/NNNN/merge - the branch github made as a test merge for CI. Only exists if the merge is clean.
    93   Some git repositories default to head when you use tor-github/pr/NNNN.
    94 
    95 3. Make sure you have merge permissions
    96 
    97   Set up SSH keys using Tor's LDAP:
    98   https://db.torproject.org/doc-mail.html
    99 
    100   Check your access:
    101   {{{
    102   $ ssh git@git-rw.torproject.org | grep W
    103   }}}
     39Configure your repository with:
     40
     41* git-rw.torproject.org:tor.git as "origin" and
     42* github.com/torproject/tor.git as "tor-github".
     43
     44{{{
     45$ git remote add tor-github https://github.com/torproject/tor.git
     46}}}
     47
     48Piece of advice here. Because git default behavior of "git push" is to use
     49"origin", then mistake can happen where one of us can push a personal branch
     50to our upstream tor.git.
     51
     52For that I nullify the "pushurl" of origin with:
     53
     54{{{
     55[remote "origin"]
     56  fetch = +refs/heads/*:refs/remotes/origin/*
     57  url = https://git.torproject.org/tor.git
     58  pushurl = "Don't push personal branches to origin!"
     59}}}
     60
     61To push now, I created an "upstream" remote so when I push commits upstream, I
     62have to explicitly type in:
     63
     64{{{
     65$ git push upstream <branch>
     66}}}
     67
     68(The git-push-all.sh allows you to specific the name of the "upstream"
     69branch).
     70
     71To add the upstream remote properly:
     72
     73{{{
     74$ git remote add upstream https://git.torproject.org/tor.git
     75$ git remote set-url --push upstream ssh://git@git-rw.torproject.org/tor.git
     76}}}
     77
     78Make sure you have PRs from tor-github set up to be named
     79tor-github/pr/NNN, where NNN is the number of the PR.
     80
     81In your gitconfig:
     82
     83{{{
     84[remote "tor-github"]
     85  fetch = +refs/heads/*:refs/remotes/tor-github/*
     86  fetch = +refs/pull/*:refs/remotes/tor-github/pr/*
     87}}}
     88
     89This sets up pull requests as:
     90  * tor-github/pr/NNNN/head - the branch you want to merge
     91  * tor-github/pr/NNNN/merge - the branch github made as a test merge for CI. Only exists if the merge is clean.
     92Some git repositories default to head when you use tor-github/pr/NNNN.
     93
     94===== 3. Make sure you have merge permissions =====
     95
     96Set up SSH keys using Tor's LDAP:
     97  * https://db.torproject.org/doc-mail.html
     98
     99Check your access:
     100{{{
     101$ ssh git@git-rw.torproject.org | grep W
     102}}}
    104103
    105104For more details, see [wiki:org/operations/services/git.torproject.org].
     
    107106==== Backport Merges Only ====
    108107
    109 4. Make sure you have the git-pull-all.sh, git-merge-forward.sh and git-push-all.sh scripts installed.
    110 
    111   You can find the hooks in `tor/scripts/git/`. They need to be copied into your $PATH:
    112     * tor/scripts/git/git-pull-all.sh -> ~/bin/git-pull-all.sh
    113     * (repeat for the other scripts)
    114 
    115   You will need to customise these scripts to your own environment, using the environmental variables listed in the script's --help.
    116 
    117   These scripts require a recent bash that supports arrays.
    118 
    119 5. Make sure you are using worktrees
    120 
    121   You might find it easier to use a separate git repository for merges and regular coding.
     108===== 4. Make sure you have the git scripts installed =====
     109
     110You can find the scripts in `tor/scripts/git/`. They need to be copied into your $PATH:
     111  * tor/scripts/git/git-pull-all.sh -> ~/bin/git-pull-all.sh
     112  * (repeat for the other scripts)
     113
     114You will need to customise these scripts to your own environment, using the environmental variables listed in the script's --help.
     115
     116These scripts require a recent bash that supports arrays.
     117
     118===== 5. Make sure you are using worktrees =====
     119
     120You might find it easier to use a separate git repository for merges and regular coding.
    122121
    123122**Automatic Setup**
    124123
    125   Set TOR_FULL_GIT_PATH in your .profile, and run `git-setup-dirs.sh`.
     124Set TOR_FULL_GIT_PATH in your .profile, and run `git-setup-dirs.sh`.
    126125
    127126**Manual Setup**
    128127
    129   To use the git-* scripts, you need worktrees. Here is an
    130   example on how to do it properly for let say the "maint-0.3.5" branch and your
    131   worktrees are in "tor-wkt" (relative to tor.git/ you have):
    132 
    133   {{{
    134   $ git worktree add ../tor-wkt/maint-0.3.5 origin/maint-0.3.5
    135   $ cd ../tor-wkt/maint-0.3.5
    136   $ git checkout -b maint-0.3.5
    137   $ git branch --set-upstream-to=origin/maint-0.3.5 maint-0.3.5
    138   }}}
    139 
    140   So then now within the worktree, you can simply do "git pull" and it will
    141   always fetch the latest from origin/maint-0.3.5 which is important because the
    142   git-pull-all.sh script requires that. These worktrees need to follow upstream
    143   at all times.
    144 
    145   Basically, a maintainer should do the above for all maintained branches
    146   (including releases-*).
     128To use the git-* scripts, you need worktrees. Here is an
     129example on how to do it properly for let say the "maint-0.3.5" branch and your
     130worktrees are in "tor-wkt" (relative to tor.git/ you have):
     131
     132{{{
     133$ git worktree add ../tor-wkt/maint-0.3.5 origin/maint-0.3.5
     134$ cd ../tor-wkt/maint-0.3.5
     135$ git checkout -b maint-0.3.5
     136$ git branch --set-upstream-to=origin/maint-0.3.5 maint-0.3.5
     137}}}
     138
     139So then now within the worktree, you can simply do "git pull" and it will
     140always fetch the latest from origin/maint-0.3.5 which is important because the
     141git-pull-all.sh script requires that. These worktrees need to follow upstream
     142at all times.
     143
     144Basically, a maintainer should do the above for all maintained branches
     145(including releases-*).
    147146
    148147==== New Maint and Release Branches ====
    149148
    150   Make sure that your git scripts are up to date with the new branches!
     149Make sure that your git scripts are up to date with the new branches!
    151150
    152151**Automatic Setup**
    153152
    154   Set TOR_FULL_GIT_PATH in your .profile, and run `git-setup-dirs.sh -u`.
     153Set TOR_FULL_GIT_PATH in your .profile, and run `git-setup-dirs.sh -u`.
    155154
    156155**Manual Setup**
    157156
    158   Set up the new maint-* and release-* worktrees, using the instructions in step 5 above.
     157Set up the new maint-* and release-* worktrees, using the instructions in step 5 above.
    159158
    160159=== Merging a Branch ===
     
    162161==== Master Merges ====
    163162
    164 0. Make sure your environment is set up
    165 
    166   * git hooks
    167   * tor-github custom remote
    168 
    169 1. Make sure you have the latest version of master checked out in your git directory.
    170 
    171   {{{
    172   $ git fetch upstream
    173   }}}
    174 
    175 2. Make sure that you have the latest version of the branch you're merging.
    176 
    177   {{{
    178   $ git fetch tor-github
    179   }}}
    180 
    181 3. Check all the things you're supposed to check.
    182 
    183 4. Merge the branch
    184 
    185   {{{
    186   # If you have an older git version, you'll need to merge tor-github/pr/NNNNN/head
    187   $ git merge tor-github/pr/NNNNN
    188   }}}
    189 
    190 5. Push to master
    191 
    192   {{{
    193   $ git push upstream master
    194   }}}
    195 
    196 6. Update the ticket, and wait for CI
    197 
    198   See "Backport Merges" Steps 8 & 9 for details.
     163===== 0. Make sure your environment is set up =====
     164
     165* git hooks
     166* tor-github custom remote
     167
     168===== 1. Make sure you have the latest version of master checked out in your git directory =====
     169
     170{{{
     171$ git fetch upstream
     172}}}
     173
     174===== 2. Make sure that you have the latest version of the branch you're merging =====
     175
     176{{{
     177$ git fetch tor-github
     178}}}
     179
     180===== 3. Check all the things you're supposed to check =====
     181
     182===== 4. Merge the branch =====
     183
     184{{{
     185# Sometimes, tor-github/pr/NNNNN will also work
     186$ git merge tor-github/pr/NNNNN/head
     187}}}
     188
     189===== 5. Push to master =====
     190
     191{{{
     192$ git push upstream master
     193}}}
     194
     195===== 6. Update the ticket, and wait for CI =====
     196
     197See "Backport Merges" Steps 8 & 9 for details.
    199198
    200199==== Backport Merges ====
    201200
    202 0. Make sure your environment is set up
    203 
    204   * git hooks
    205   * tor-github custom remote
    206   * git scripts
    207   * worktrees
    208 
    209 1. Make sure you have the latest version of all supported branches checked out in your worktrees.
    210 
    211 2. Make sure that you have the latest version of the branch you're merging.
    212 
    213   You can get the supported branches and github PRs using:
    214   {{{
    215   $ git-pull-all.sh
    216   }}}
    217 
    218 3. Check all the things you're supposed to check.
    219 
    220 4. Go into the earliest target directory where you are merging today, and merge the branch.
    221 
    222 5. If the merge isn't clean, ask the patch author or a stable maintainer what to do.
    223 
    224 6. Run `git-merge-forward.sh` and verify that there are no conflicts.
    225 
    226   The merge-forward script will stop after any conflicts, so you'll have
    227   to go in the worktree and fix the conflict yourself. It *does* happen so not
    228   to worry :).
    229 
    230 7. Run `git-push-all.sh`
    231 
    232 8. Update the ticket
    233 
    234   If you are merging a patch into the earliest series to which it
    235   applies, close the ticket after you merge, and say where you merged
    236   it.  If you are merging a patch that is a candidate for backport, move
    237   the ticket into the earliest open milestone to which it applies.
    238 
    239 9. Wait for the CI to finish on master.
    240 
    241   If the CI fails due to practracker errors, update the practracker exceptions file, and push to master again.
    242   (practracker fixes don't need review.) Ask the person who wrote the code to fix the exception.
    243 
    244   Make a note on the trac ticket for the PR that caused the error.
     201===== 0. Make sure your environment is set up =====
     202
     203* git hooks
     204* tor-github custom remote
     205* git scripts
     206* worktrees
     207
     208===== 1. Make sure you have the latest version of all supported branches checked out in your worktrees =====
     209
     210{{{
     211$ git-pull-all.sh
     212}}}
     213
     214===== 2. Make sure that you have the latest version of the branch you're merging =====
     215
     216You can get the supported branches and github PRs using:
     217{{{
     218$ git-pull-all.sh
     219}}}
     220
     221===== 3. Check all the things you're supposed to check =====
     222
     223===== 4. Go into the earliest target directory where you are merging today, and merge the branch =====
     224
     225{{{
     226$ cd maint-0.3.5
     227# Sometimes, tor-github/pr/NNNNN will also work
     228$ git merge tor-github/pr/NNNNN/head
     229}}}
     230
     231===== 5. If the merge isn't clean, ask the patch author or a stable maintainer what to do =====
     232
     233===== 6. Run `git-merge-forward.sh` and verify that there are no conflicts =====
     234
     235The merge-forward script will stop after any conflicts.
     236
     237===== 7. If the merge isn't clean, ask the patch author or a stable maintainer what to do =====
     238
     239You can go in to the worktree and fix the conflict yourself, if you can work out how. Let the patch author know on the ticket, and ask them to check your merge.
     240
     241===== 8. Push all the branches =====
     242
     243{{{
     244$ git-push-all.sh
     245}}}
     246
     247===== 9. Update the ticket =====
     248
     249If you are merging a patch into the earliest series to which it
     250applies, close the ticket after you merge, and say where you merged
     251it.  If you are merging a patch that is a candidate for backport, move
     252the ticket into the earliest open milestone to which it applies.
     253
     254===== 9. Wait for the CI to finish on master =====
     255
     256If the CI fails due to practracker errors, update the practracker exceptions file, and push to master again.
     257(practracker fixes don't need review.) Ask the person who wrote the code to fix the exception.
     258
     259Make a note on the trac ticket for the PR that caused the error.
    245260
    246261=== Merging Different Branches into Different Releases ===