| ... | ... | @@ -2,18 +2,14 @@ |
|
|
|
|
|
|
|
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 [MergePolicy](./MergePolicy) document.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
This page explains how to merge patches into Tor. For the rules about
|
|
|
|
**when** to merge patches into Tor, see the [MergePolicy](./MergePolicy)
|
|
|
|
document.
|
|
|
|
|
|
|
|
## How do you do a Merge?
|
|
|
|
|
|
|
|
### Configuring your Environment
|
|
|
|
|
|
|
|
[draft]
|
|
|
|
|
|
|
|
#### Master and Backport Merges
|
|
|
|
|
|
|
|
##### 1. Make sure you have the git hooks installed
|
| ... | ... | @@ -38,11 +34,12 @@ Set TOR_FULL_GIT_PATH in your .profile, and run `git-setup-dirs.sh`. |
|
|
|
|
|
|
|
Configure your repository with:
|
|
|
|
|
|
|
|
* git-rw.torproject.org:tor.git as "origin" and
|
|
|
|
* github.com/torproject/tor.git as "tor-github".
|
|
|
|
* git-rw.torproject.org:tor.git as "origin"
|
|
|
|
|
|
|
|
and
|
|
|
|
|
|
|
|
```
|
|
|
|
$ git remote add tor-github https://github.com/torproject/tor.git
|
|
|
|
$ git remote add tor-gitlab https://gitlab.torproject.org/tpo/core/tor.git
|
|
|
|
```
|
|
|
|
|
|
|
|
Piece of advice here. Because git default behavior of "git push" is to use
|
| ... | ... | @@ -75,22 +72,15 @@ $ 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:
|
|
|
|
Make sure you have MRs from tor-gitlab, in your gitconfig:
|
|
|
|
|
|
|
|
```
|
|
|
|
[remote "tor-github"]
|
|
|
|
fetch = +refs/heads/*:refs/remotes/tor-github/*
|
|
|
|
fetch = +refs/pull/*:refs/remotes/tor-github/pr/*
|
|
|
|
[remote "tor-gitlab"]
|
|
|
|
fetch = +refs/merge-requests/*/head:refs/remotes/tor-gitlab/merge-requests/*
|
|
|
|
fetch = +refs/merge-requests/*/head:refs/remotes/tor-gitlab/mr/*
|
|
|
|
pushurl = No_Pushing_To_GitLab
|
|
|
|
```
|
|
|
|
|
|
|
|
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
|
|
|
|
|
|
|
|
Set up SSH keys using Tor's LDAP:
|
| ... | ... | @@ -163,7 +153,7 @@ Set up the new maint-* and release-* worktrees, using the instructions in step 5 |
|
|
|
##### 0. Make sure your environment is set up
|
|
|
|
|
|
|
|
* git hooks
|
|
|
|
* tor-github custom remote
|
|
|
|
* tor-gitlab custom remote
|
|
|
|
|
|
|
|
##### 1. Make sure you have the latest version of master checked out in your git directory
|
|
|
|
|
| ... | ... | @@ -174,22 +164,19 @@ $ git fetch upstream |
|
|
|
##### 2. Make sure that you have the latest version of the branch you're merging
|
|
|
|
|
|
|
|
```
|
|
|
|
$ git fetch tor-github
|
|
|
|
$ git fetch tor-gitlab
|
|
|
|
```
|
|
|
|
|
|
|
|
##### 3. Check all the things you're supposed to check
|
|
|
|
|
|
|
|
##### 4. Merge the branch
|
|
|
|
##### 3. Merge the branch
|
|
|
|
|
|
|
|
```
|
|
|
|
# Sometimes, tor-github/pr/NNNNN will also work
|
|
|
|
$ git merge tor-github/pr/NNNNN/head
|
|
|
|
$ git merge tor-gitlab/mr/<NUM>
|
|
|
|
```
|
|
|
|
|
|
|
|
##### 5. Push to master
|
|
|
|
##### 5. Push to main
|
|
|
|
|
|
|
|
```
|
|
|
|
$ git push upstream master
|
|
|
|
$ git push upstream main
|
|
|
|
```
|
|
|
|
|
|
|
|
##### 6. Update the ticket, and wait for CI
|
| ... | ... | @@ -201,7 +188,7 @@ See "Backport Merges" Steps 8 & 9 for details. |
|
|
|
##### 0. Make sure your environment is set up
|
|
|
|
|
|
|
|
* git hooks
|
|
|
|
* tor-github custom remote
|
|
|
|
* tor-gitlab custom remote
|
|
|
|
* git scripts
|
|
|
|
* worktrees
|
|
|
|
|
| ... | ... | @@ -213,7 +200,7 @@ $ git-pull-all.sh |
|
|
|
|
|
|
|
##### 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:
|
|
|
|
You can get the supported branches and gitlab MRs using:
|
|
|
|
```
|
|
|
|
$ git-pull-all.sh
|
|
|
|
```
|
| ... | ... | @@ -224,8 +211,7 @@ $ git-pull-all.sh |
|
|
|
|
|
|
|
```
|
|
|
|
$ cd maint-0.3.5
|
|
|
|
# Sometimes, tor-github/pr/NNNNN will also work
|
|
|
|
$ git merge tor-github/pr/NNNNN/head
|
|
|
|
$ git merge tor-gitlab/mr/<NUM>
|
|
|
|
```
|
|
|
|
|
|
|
|
##### 5. If the merge isn't clean, ask the patch author or a stable maintainer what to do
|
| ... | ... | @@ -292,6 +278,7 @@ To simplify this process, we usually: |
|
|
|
#### 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
|
|
|
|
2. Change to the directory for the maint branch
|
|
|
|
3. Merge the pull request in to the maint branch
|
| ... | ... | @@ -300,129 +287,6 @@ Here's how you do the merges: |
|
|
|
|
|
|
|
#### 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
|
|
|
|
|
|
|
|
Here is a worked example from https://trac.torproject.org/projects/tor/ticket/29806#comment:18
|
|
|
|
|
|
|
|
We want to do a mainline merge into:
|
|
|
|
* maint-0.4.0
|
|
|
|
* master
|
|
|
|
|
|
|
|
We have these pull requests:
|
|
|
|
* 0.3.4: https://github.com/torproject/tor/pull/820
|
|
|
|
* 0.3.5: https://github.com/torproject/tor/pull/821
|
|
|
|
* master: https://github.com/torproject/tor/pull/822
|
|
|
|
|
|
|
|
The earliest branch and pull request are:
|
|
|
|
* 0.3.5: https://github.com/torproject/tor/pull/821 into maint-0.4.0
|
|
|
|
* we use the 0.3.5 pull request, because there is no 0.4.0 pull request
|
|
|
|
|
|
|
|
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
|
|
|
|
Auto-merging src/feature/dirauth/bwauth.c
|
|
|
|
Merge made by the 'recursive' strategy.
|
|
|
|
changes/ticket29806 | 7 ++++++
|
|
|
|
src/feature/dirauth/bwauth.c | 8 ++++++-
|
|
|
|
src/test/test_dir.c | 57 ++++++++++++++++++++++++++++++++++++++++++++
|
|
|
|
3 files changed, 71 insertions(+), 1 deletion(-)
|
|
|
|
create mode 100644 changes/ticket29806
|
|
|
|
$ cd ../tor
|
|
|
|
# If you are using git ~2.20, you will need to merge tor-github/pr/822/head
|
|
|
|
$ git merge tor-github/pr/822
|
|
|
|
Merge made by the 'recursive' strategy.
|
|
|
|
changes/ticket29806 | 7 ++++++
|
|
|
|
src/feature/dirauth/bwauth.c | 8 +++++-
|
|
|
|
src/test/test_dir.c | 59 ++++++++++++++++++++++++++++++++++++++++++++
|
|
|
|
3 files changed, 73 insertions(+), 1 deletion(-)
|
|
|
|
create mode 100644 changes/ticket29806
|
|
|
|
$ git-merge-forward.sh
|
|
|
|
[+] Fetching origin...success
|
|
|
|
[+] Handling branch
|
|
|
|
release-0.2.9 Handling branch
|
|
|
|
[+] Switching branch to release-0.2.9...success
|
|
|
|
[+] Merging branch origin/release-0.2.9...success
|
|
|
|
[+] Merging branch maint-0.2.9 into release-0.2.9...success
|
|
|
|
[+] Handling branch
|
|
|
|
maint-0.3.4 Handling branch
|
|
|
|
[+] Switching branch to maint-0.3.4...success
|
|
|
|
[+] Merging branch origin/maint-0.3.4...success
|
|
|
|
[+] Merging branch maint-0.2.9 into maint-0.3.4...success
|
|
|
|
[+] Handling branch
|
|
|
|
release-0.3.4 Handling branch
|
|
|
|
[+] Switching branch to release-0.3.4...success
|
|
|
|
[+] Merging branch origin/release-0.3.4...success
|
|
|
|
[+] Merging branch maint-0.3.4 into release-0.3.4...success
|
|
|
|
[+] Handling branch
|
|
|
|
maint-0.3.5 Handling branch
|
|
|
|
[+] Switching branch to maint-0.3.5...success
|
|
|
|
[+] Merging branch origin/maint-0.3.5...success
|
|
|
|
[+] Merging branch maint-0.3.4 into maint-0.3.5...success
|
|
|
|
[+] Handling branch
|
|
|
|
release-0.3.5 Handling branch
|
|
|
|
[+] Switching branch to release-0.3.5...success
|
|
|
|
[+] Merging branch origin/release-0.3.5...success
|
|
|
|
[+] Merging branch maint-0.3.5 into release-0.3.5...success
|
|
|
|
[+] Handling branch
|
|
|
|
maint-0.4.0 Handling branch
|
|
|
|
[+] Switching branch to maint-0.4.0...success
|
|
|
|
[+] Merging branch origin/maint-0.4.0...success
|
|
|
|
[+] Merging branch maint-0.3.5 into maint-0.4.0...success
|
|
|
|
[+] Handling branch
|
|
|
|
release-0.4.0 Handling branch
|
|
|
|
[+] Switching branch to release-0.4.0...success
|
|
|
|
[+] Merging branch origin/release-0.4.0...success
|
|
|
|
[+] Merging branch maint-0.4.0 into release-0.4.0...success
|
|
|
|
[+] Handling branch
|
|
|
|
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?
|
|
|
|
|
|
|
|
Use `git-merge-forward.sh -t bugNNNNN` to automatically create merge forward branches from the current contents of your maint-* and master working directories.
|
|
|
|
|
|
|
|
To make the merges as simple as possible, here's what we usually do:
|
|
|
|
* when we know we want to backport, we find the earliest maint branch (N) that needs a backport
|
|
|
|
* if we're writing the bugfix, we write the fix on branch N
|
|
|
|
* if we have a bugfix on master, we cherry-pick or rebase to N
|
|
|
|
* once the backport branch is done, we merge the branch into N, and then merge N+branch forward
|
|
|
|
* if there are any significant conflicts, we find the earliest maint branch with a conflict (M)
|
|
|
|
* we make a separate branch based on M that resolves the conflict (How? We still need to write a merge policy.)
|
|
|
|
* then we continue to merge forward
|
|
|
|
|
|
|
|
Even if there are no conflicts, the patch may require changes to work on later versions. We deal with these changes in a similar way:
|
|
|
|
* merge forward the changes for previous versions,
|
|
|
|
* add a commit with the new required changes, on the earliest maint branch that needs the change.
|
|
|
|
|
|
|
|
Just merge lines in merge commits. Don't put semantic changes in merge commits. Instead, put them in a new commit after the merge commit.
|
|
|
|
|
|
|
|
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
|
|
|
|
|
|
|
|
We should integrate this document with the stable maintainer guide.
|
|
|
|
|
|
|
|
We should decide if we need more comprehensive instructions for unclean merge commits.
|
|
|
|
|
|
|
|
We should automate as much of this process as possible. |
|
|
\ No newline at end of file |
|
|
|
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. |
David Goulet <dgoulet@torproject.org>