|
|
= Merge Process =
|
|
|
# Merge Process
|
|
|
|
|
|
Network team merge process, setup instructions, and notes.
|
|
|
|
|
|
This page explains how to merge patches into Tor. For the rules about '''when''' to merge patches into Tor, see the [[org/teams/NetworkTeam/MergePolicy|MergePolicy]] document.
|
|
|
This page explains how to merge patches into Tor. For the rules about **when** to merge patches into Tor, see the [[org/teams/NetworkTeam/MergePolicy|MergePolicy]] document.
|
|
|
|
|
|
[[TOC]]
|
|
|
|
|
|
|
|
|
|
|
|
== How do you do a Merge? ==
|
|
|
|
|
|
=== Configuring your Environment ===
|
|
|
## How do you do a Merge?
|
|
|
|
|
|
### Configuring your Environment
|
|
|
|
|
|
[draft]
|
|
|
|
|
|
==== Master and Backport Merges ====
|
|
|
#### Master and Backport Merges
|
|
|
|
|
|
===== 1. Make sure you have the git hooks installed =====
|
|
|
##### 1. Make sure you have the git hooks installed
|
|
|
|
|
|
You can find the hooks in `tor/scripts/git/`. They need to be copied into tor/.git/hooks, without the extension:
|
|
|
* tor/scripts/git/post-merge.git-hook -> .git/hooks/post-merge
|
... | ... | @@ -25,7 +25,7 @@ You can find the hooks in `tor/scripts/git/`. They need to be copied into tor/.g |
|
|
Q: How do I keep the git hooks up to date?
|
|
|
A: Install the post-merge (post pull) hook, so git logs a message when the hooks are updated in master. (See #29588.)
|
|
|
|
|
|
===== 2. Clone and configure your git repository =====
|
|
|
##### 2. Clone and configure your git repository
|
|
|
|
|
|
You might find it easier to use a separate git repository for merges and regular coding.
|
|
|
|
... | ... | @@ -41,9 +41,9 @@ Configure your repository with: |
|
|
* git-rw.torproject.org:tor.git as "origin" and
|
|
|
* github.com/torproject/tor.git as "tor-github".
|
|
|
|
|
|
{{{
|
|
|
```
|
|
|
$ git remote add tor-github https://github.com/torproject/tor.git
|
|
|
}}}
|
|
|
```
|
|
|
|
|
|
Piece of advice here. Because git default behavior of "git push" is to use
|
|
|
"origin", then mistake can happen where one of us can push a personal branch
|
... | ... | @@ -51,61 +51,61 @@ to our upstream tor.git. |
|
|
|
|
|
For that I nullify the "pushurl" of origin with:
|
|
|
|
|
|
{{{
|
|
|
```
|
|
|
[remote "origin"]
|
|
|
fetch = +refs/heads/*:refs/remotes/origin/*
|
|
|
url = https://git.torproject.org/tor.git
|
|
|
pushurl = "Don't push personal branches to origin!"
|
|
|
}}}
|
|
|
```
|
|
|
|
|
|
To push now, I created an "upstream" remote so when I push commits upstream, I
|
|
|
have to explicitly type in:
|
|
|
|
|
|
{{{
|
|
|
```
|
|
|
$ git push upstream <branch>
|
|
|
}}}
|
|
|
```
|
|
|
|
|
|
(The git-push-all.sh allows you to specific the name of the "upstream"
|
|
|
branch).
|
|
|
|
|
|
To add the upstream remote properly:
|
|
|
|
|
|
{{{
|
|
|
```
|
|
|
$ git remote add upstream https://git.torproject.org/tor.git
|
|
|
$ git remote set-url --push upstream ssh://git@git-rw.torproject.org/tor.git
|
|
|
}}}
|
|
|
```
|
|
|
|
|
|
Make sure you have PRs from tor-github set up to be named
|
|
|
tor-github/pr/NNN, where NNN is the number of the PR.
|
|
|
|
|
|
In your gitconfig:
|
|
|
|
|
|
{{{
|
|
|
```
|
|
|
[remote "tor-github"]
|
|
|
fetch = +refs/heads/*:refs/remotes/tor-github/*
|
|
|
fetch = +refs/pull/*:refs/remotes/tor-github/pr/*
|
|
|
}}}
|
|
|
```
|
|
|
|
|
|
This sets up pull requests as:
|
|
|
* tor-github/pr/NNNN/head - the branch you want to merge
|
|
|
* tor-github/pr/NNNN/merge - the branch github made as a test merge for CI. Only exists if the merge is clean.
|
|
|
Some git repositories default to head when you use tor-github/pr/NNNN.
|
|
|
|
|
|
===== 3. Make sure you have merge permissions =====
|
|
|
##### 3. Make sure you have merge permissions
|
|
|
|
|
|
Set up SSH keys using Tor's LDAP:
|
|
|
* https://db.torproject.org/doc-mail.html
|
|
|
|
|
|
Check your access:
|
|
|
{{{
|
|
|
```
|
|
|
$ ssh git@git-rw.torproject.org | grep W
|
|
|
}}}
|
|
|
```
|
|
|
|
|
|
For more details, see [wiki:org/operations/services/git.torproject.org].
|
|
|
For more details, see [org/operations/services/git.torproject.org](org/operations/services/git.torproject.org).
|
|
|
|
|
|
==== Backport Merges Only ====
|
|
|
#### Backport Merges Only
|
|
|
|
|
|
===== 4. Make sure you have the git scripts installed =====
|
|
|
##### 4. Make sure you have the git scripts installed
|
|
|
|
|
|
You can find the scripts in `tor/scripts/git/`. They need to be copied into your $PATH:
|
|
|
* tor/scripts/git/git-pull-all.sh -> ~/bin/git-pull-all.sh
|
... | ... | @@ -115,7 +115,7 @@ You will need to customise these scripts to your own environment, using the envi |
|
|
|
|
|
These scripts require a recent bash that supports arrays.
|
|
|
|
|
|
===== 5. Make sure you are using worktrees =====
|
|
|
##### 5. Make sure you are using worktrees
|
|
|
|
|
|
You might find it easier to use a separate git repository for merges and regular coding.
|
|
|
|
... | ... | @@ -129,12 +129,12 @@ To use the git-* scripts, you need worktrees. Here is an |
|
|
example on how to do it properly for let say the "maint-0.3.5" branch and your
|
|
|
worktrees are in "tor-wkt" (relative to tor.git/ you have):
|
|
|
|
|
|
{{{
|
|
|
```
|
|
|
$ git worktree add ../tor-wkt/maint-0.3.5 origin/maint-0.3.5
|
|
|
$ cd ../tor-wkt/maint-0.3.5
|
|
|
$ git checkout -b maint-0.3.5
|
|
|
$ git branch --set-upstream-to=origin/maint-0.3.5 maint-0.3.5
|
|
|
}}}
|
|
|
```
|
|
|
|
|
|
So then now within the worktree, you can simply do "git pull" and it will
|
|
|
always fetch the latest from origin/maint-0.3.5 which is important because the
|
... | ... | @@ -144,7 +144,7 @@ at all times. |
|
|
Basically, a maintainer should do the above for all maintained branches
|
|
|
(including releases-*).
|
|
|
|
|
|
==== New Maint and Release Branches ====
|
|
|
#### New Maint and Release Branches
|
|
|
|
|
|
Make sure that your git scripts are up to date with the new branches!
|
|
|
|
... | ... | @@ -156,113 +156,113 @@ Set TOR_FULL_GIT_PATH in your .profile, and run `git-setup-dirs.sh -u`. |
|
|
|
|
|
Set up the new maint-* and release-* worktrees, using the instructions in step 5 above.
|
|
|
|
|
|
=== Merging a Branch ===
|
|
|
### Merging a Branch
|
|
|
|
|
|
==== Master Merges ====
|
|
|
#### Master Merges
|
|
|
|
|
|
===== 0. Make sure your environment is set up =====
|
|
|
##### 0. Make sure your environment is set up
|
|
|
|
|
|
* git hooks
|
|
|
* tor-github custom remote
|
|
|
|
|
|
===== 1. Make sure you have the latest version of master checked out in your git directory =====
|
|
|
##### 1. Make sure you have the latest version of master checked out in your git directory
|
|
|
|
|
|
{{{
|
|
|
```
|
|
|
$ git fetch upstream
|
|
|
}}}
|
|
|
```
|
|
|
|
|
|
===== 2. Make sure that you have the latest version of the branch you're merging =====
|
|
|
##### 2. Make sure that you have the latest version of the branch you're merging
|
|
|
|
|
|
{{{
|
|
|
```
|
|
|
$ git fetch tor-github
|
|
|
}}}
|
|
|
```
|
|
|
|
|
|
===== 3. Check all the things you're supposed to check =====
|
|
|
##### 3. Check all the things you're supposed to check
|
|
|
|
|
|
===== 4. Merge the branch =====
|
|
|
##### 4. Merge the branch
|
|
|
|
|
|
{{{
|
|
|
```
|
|
|
# Sometimes, tor-github/pr/NNNNN will also work
|
|
|
$ git merge tor-github/pr/NNNNN/head
|
|
|
}}}
|
|
|
```
|
|
|
|
|
|
===== 5. Push to master =====
|
|
|
##### 5. Push to master
|
|
|
|
|
|
{{{
|
|
|
```
|
|
|
$ git push upstream master
|
|
|
}}}
|
|
|
```
|
|
|
|
|
|
===== 6. Update the ticket, and wait for CI =====
|
|
|
##### 6. Update the ticket, and wait for CI
|
|
|
|
|
|
See "Backport Merges" Steps 8 & 9 for details.
|
|
|
|
|
|
==== Backport Merges ====
|
|
|
#### Backport Merges
|
|
|
|
|
|
===== 0. Make sure your environment is set up =====
|
|
|
##### 0. Make sure your environment is set up
|
|
|
|
|
|
* git hooks
|
|
|
* tor-github custom remote
|
|
|
* git scripts
|
|
|
* worktrees
|
|
|
|
|
|
===== 1. Make sure you have the latest version of all supported branches checked out in your worktrees =====
|
|
|
##### 1. Make sure you have the latest version of all supported branches checked out in your worktrees
|
|
|
|
|
|
{{{
|
|
|
```
|
|
|
$ git-pull-all.sh
|
|
|
}}}
|
|
|
```
|
|
|
|
|
|
===== 2. Make sure that you have the latest version of the branch you're merging =====
|
|
|
##### 2. Make sure that you have the latest version of the branch you're merging
|
|
|
|
|
|
You can get the supported branches and github PRs using:
|
|
|
{{{
|
|
|
```
|
|
|
$ git-pull-all.sh
|
|
|
}}}
|
|
|
```
|
|
|
|
|
|
===== 3. Check all the things you're supposed to check =====
|
|
|
##### 3. Check all the things you're supposed to check
|
|
|
|
|
|
===== 4. Go into the earliest target directory where you are merging today, and merge the branch =====
|
|
|
##### 4. Go into the earliest target directory where you are merging today, and merge the branch
|
|
|
|
|
|
{{{
|
|
|
```
|
|
|
$ cd maint-0.3.5
|
|
|
# Sometimes, tor-github/pr/NNNNN will also work
|
|
|
$ git merge tor-github/pr/NNNNN/head
|
|
|
}}}
|
|
|
```
|
|
|
|
|
|
===== 5. If the merge isn't clean, ask the patch author or a stable maintainer what to do =====
|
|
|
##### 5. If the merge isn't clean, ask the patch author or a stable maintainer what to do
|
|
|
|
|
|
===== 6. Run `git-merge-forward.sh` and verify that there are no conflicts =====
|
|
|
##### 6. Run `git-merge-forward.sh` and verify that there are no conflicts
|
|
|
|
|
|
The merge-forward script will stop after any conflicts.
|
|
|
|
|
|
===== 7. If the merge isn't clean, ask the patch author or a stable maintainer what to do =====
|
|
|
##### 7. If the merge isn't clean, ask the patch author or a stable maintainer what to do
|
|
|
|
|
|
You 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.
|
|
|
|
|
|
===== 8. Push all the branches =====
|
|
|
##### 8. Push all the branches
|
|
|
|
|
|
{{{
|
|
|
```
|
|
|
$ git-push-all.sh
|
|
|
}}}
|
|
|
```
|
|
|
|
|
|
===== 9. Update the ticket =====
|
|
|
##### 9. Update the ticket
|
|
|
|
|
|
If you are merging a patch into the earliest series to which it
|
|
|
applies, close the ticket after you merge, and say where you merged
|
|
|
it. If you are merging a patch that is a candidate for backport, move
|
|
|
the ticket into the earliest open milestone to which it applies.
|
|
|
|
|
|
===== 9. Wait for the CI to finish on master =====
|
|
|
##### 9. Wait for the CI to finish on master
|
|
|
|
|
|
If the CI fails due to practracker errors, update the practracker exceptions file, and push to master again.
|
|
|
(practracker fixes don't need review.) Ask the person who wrote the code to fix the exception.
|
|
|
|
|
|
Make a note on the trac ticket for the PR that caused the error.
|
|
|
|
|
|
=== Merging Different Branches into Different Releases ===
|
|
|
### Merging Different Branches into Different Releases
|
|
|
|
|
|
Follow the "Backport Merges" steps 3-5 for each branch you need to merge.
|
|
|
|
|
|
==== Finding Branches to Merge ====
|
|
|
#### Finding Branches to Merge
|
|
|
|
|
|
1. Work out all the maint branches you are merging pull requests into today:
|
|
|
* if you're doing a mainline merge, the maint branches might be:
|
... | ... | @@ -289,7 +289,7 @@ To simplify this process, we usually: |
|
|
* Wait for testing in an alpha release
|
|
|
* Merge the change to all other versions
|
|
|
|
|
|
==== Doing the Merges ====
|
|
|
#### Doing the Merges
|
|
|
|
|
|
Here's how you do the merges:
|
|
|
1. Find the earliest maint branch you want to merge into today, and the pull request for that maint branch
|
... | ... | @@ -298,13 +298,13 @@ Here's how you do the merges: |
|
|
4. Repeat from 2 for the next pull request and its maint branch
|
|
|
5. Once all the pull requests are merged, merge all branches forward
|
|
|
|
|
|
==== Dealing with Merge Conflicts ====
|
|
|
#### Dealing with Merge Conflicts
|
|
|
|
|
|
If there are any merge conflicts, stop! Don't push anything!
|
|
|
Reset your merge directories to the current branches on torproject.org.
|
|
|
Ask for help on the ticket. Include details of the merge conflict.
|
|
|
|
|
|
==== Worked Example ====
|
|
|
#### Worked Example
|
|
|
|
|
|
Here is a worked example from https://trac.torproject.org/projects/tor/ticket/29806#comment:18
|
|
|
|
... | ... | @@ -325,7 +325,7 @@ The other pull requests are: |
|
|
* master: https://github.com/torproject/tor/pull/822 into master
|
|
|
|
|
|
Here are the exact steps on the command-line:
|
|
|
{{{
|
|
|
```
|
|
|
$ cd ../maint-0.4.0
|
|
|
$ git merge tor-github/pr/821
|
|
|
Auto-merging src/test/test_dir.c
|
... | ... | @@ -387,18 +387,18 @@ master Handling branch |
|
|
[+] Switching branch to master...success
|
|
|
[+] Merging branch origin/master...success
|
|
|
[+] Merging branch maint-0.4.0 into master...success
|
|
|
}}}
|
|
|
```
|
|
|
|
|
|
|
|
|
These forward merges were clean merges:
|
|
|
{{{
|
|
|
```
|
|
|
[+] Merging branch maint-0.4.0 into release-0.4.0...success
|
|
|
[+] Merging branch maint-0.4.0 into master...success
|
|
|
}}}
|
|
|
```
|
|
|
|
|
|
The rest of the merges did not add a merge commit, because there were no changes.
|
|
|
|
|
|
== How do we Create Backport Branches? ==
|
|
|
## How do we Create Backport Branches?
|
|
|
|
|
|
Use `git-merge-forward.sh -t bugNNNNN` to automatically create merge forward branches from the current contents of your maint-* and master working directories.
|
|
|
|
... | ... | @@ -419,7 +419,7 @@ Just merge lines in merge commits. Don't put semantic changes in merge commits. |
|
|
|
|
|
If we create merge branches this way, we should be able to merge all these branches in the right places, then merge forward without conflicts.
|
|
|
|
|
|
== TODO ==
|
|
|
## TODO
|
|
|
|
|
|
We should integrate this document with the stable maintainer guide.
|
|
|
|
... | ... | |