Changes

Page history
Big cleanup authored by David Goulet's avatar David Goulet 


I moved things that could be useful for historical purposes into
Archive/ and the rest that was badly out of date, not used or border
line crazy, has been removed. We can always get them back with git
history.

Signed-off-by: David Goulet's avatarDavid Goulet <dgoulet@torproject.org>
Show whitespace changes
Inline Side-by-side
NetworkTeam/MergeProcess.md
View page @ 2b1d9dbe
......@@ -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.