Merge in the migration from subversion / github
Add in the migrating from the old subversion / git docs. This section should be removed in a few months maybe. Contributions by: lwshu@, Alexander Richardson, kib@, Ceri Davies
This commit is contained in:
Warner Losh
parent
aa0d0c1422
commit
abff932fe8
1 changed files with 268 additions and 7 deletions
|
|
@ -241,6 +241,21 @@ Committers are encouraged to seek review for their work as part of the normal de
|
|||
this section is a work in progress...
|
||||
====
|
||||
|
||||
[[git-basics]]
|
||||
=== Git basics
|
||||
|
||||
There are many primers on how to use Git on the web. There's a lot of
|
||||
them (google "Git primer"). This one comes up first, and is generally
|
||||
good. https://danielmiessler.com/study/git/ and
|
||||
https://gist.github.com/williewillus/068e9a8543de3a7ef80adb2938657b6b
|
||||
are good overviews. The Git book is also complete, but much longer
|
||||
https://git-scm.com/book/en/v2. There is also this website
|
||||
https://ohshitgit.com/ for common traps and pitfalls of Git, in case
|
||||
you need guidance to fix things up.
|
||||
|
||||
This document will assume that you've read through it and will try not
|
||||
to belabor the basics (though it will cover them briefly).
|
||||
|
||||
[[mfc-with-git]]
|
||||
=== MFC (Merge From Current) Procedures
|
||||
==== Summary
|
||||
|
|
@ -490,7 +505,7 @@ Author: John Baldwin <jhb@FreeBSD.org>
|
|||
Date: Wed Dec 16 00:11:30 2020 +0000
|
||||
|
||||
Use the 't' modifier to print a ptrdiff_t.
|
||||
|
||||
|
||||
Reviewed by: imp
|
||||
Obtained from: CheriBSD
|
||||
Sponsored by: DARPA
|
||||
|
|
@ -530,10 +545,10 @@ Author: John Baldwin <jhb@FreeBSD.org>
|
|||
Date: Wed Dec 16 00:11:30 2020 +0000
|
||||
|
||||
Use the 't' modifier to print a ptrdiff_t.
|
||||
|
||||
|
||||
Obtained from: CheriBSD
|
||||
Sponsored by: DARPA
|
||||
|
||||
|
||||
(cherry picked from commit ce8395ecfda2c8e332a2adf9a9432c2e7f35ea81)
|
||||
|
||||
diff --git a/sys/compat/linuxkpi/common/include/linux/printk.h b/sys/compat/linuxkpi/common/include/linux/printk.h
|
||||
|
|
@ -583,10 +598,10 @@ Author: John Baldwin <jhb@FreeBSD.org>
|
|||
Date: Thu Dec 3 22:01:13 2020 +0000
|
||||
|
||||
Don't transmit mbufs that aren't yet ready on TOE sockets.
|
||||
|
||||
|
||||
This includes mbufs waiting for data from sendfile() I/O requests, or
|
||||
mbufs awaiting encryption for KTLS.
|
||||
|
||||
|
||||
Reviewed by: np
|
||||
MFC after: 2 weeks
|
||||
Sponsored by: Chelsio Communications
|
||||
|
|
@ -679,9 +694,9 @@ Date: Thu Dec 3 22:01:13 2020 +0000
|
|||
|
||||
This includes mbufs waiting for data from sendfile() I/O requests, or
|
||||
mbufs awaiting encryption for KTLS.
|
||||
|
||||
|
||||
Sponsored by: Chelsio Communications
|
||||
|
||||
|
||||
(cherry picked from commit 99963f5343a017e934e4d8ea2371a86789a46ff9)
|
||||
|
||||
diff --git a/sys/dev/cxgbe/tom/t4_cpl_io.c b/sys/dev/cxgbe/tom/t4_cpl_io.c
|
||||
|
|
@ -953,6 +968,252 @@ Here 'good' means:
|
|||
This hasn't connected `glorbnitz` to the build yet. How so do that is specific to the software being imported.
|
||||
====
|
||||
|
||||
=== FreeBSD Src Committer Transition Guide
|
||||
|
||||
This section is designed to walk people through the conversion
|
||||
process from Subversion to Git, written from the source committer's point
|
||||
of view.
|
||||
|
||||
==== Migrating from a Subversion tree
|
||||
|
||||
This section will cover a couple of common scenarios for migrating
|
||||
from using the FreeBSD Subversion repo to the FreeBSD source git repo. The
|
||||
FreeBSD Git conversion is still in beta status, so some minor things
|
||||
may change between this and going into production.
|
||||
|
||||
Before you git started, you'll need a copy of Git. Any Git will do,
|
||||
though the latest ones are always recommended. Either build it from
|
||||
ports, or install it using pkg (though some folks might use `su` or
|
||||
`doas` instead of `sudo`):
|
||||
|
||||
|
||||
[source,shell]
|
||||
....
|
||||
% sudo pkg install git
|
||||
....
|
||||
|
||||
===== No staged changes migration
|
||||
|
||||
If you have no changes pending, the migration is straight forward. In
|
||||
this, you abandon the Subversion tree and clone the Git repo. It's
|
||||
likely best to retain your subversion tree, in case there's something
|
||||
you've forgotten about there. First, let's clone a repo:
|
||||
[source,shell]
|
||||
....
|
||||
% git clone -o freebsd --config remote.freebsd.fetch='+refs/notes/*:refs/notes/*' https://git.freebsd.org/src.git freebsd-src
|
||||
....
|
||||
will create a clone of the FreeBSD src repo into a subdirectory called
|
||||
`freebsd-src` and include the 'notes' about the revisions.
|
||||
The current plan for GitHub mirroring is to mirror to
|
||||
https://github.com/freebsd/freebsd.git as well. When the transition
|
||||
starts, the github `master` branch will be frozen. We will be using the name `main` instead
|
||||
of `master` that was used in the beta version of the github.com mirror.
|
||||
The exact logistics of this are still being finalized, as there are over 2k forks and 5k stars.
|
||||
We will also mirror the repo to gitlab at https://gitlab.com/FreeBSD/src.git .
|
||||
Its transition plan is also being finalized.
|
||||
|
||||
It's useful to have the old Subversion revisions available. This data is stored
|
||||
using Git notes, but Git doesn't fetch those by default. The --config
|
||||
and the argument above changed the default to fetch the notes. If
|
||||
you've cloned the repo without this, or wish to add notes to an
|
||||
previously clone repository, use the following commands:
|
||||
[source,shell]
|
||||
....
|
||||
% git config --add remote.freebsd.fetch "+refs/notes/*:refs/notes/*"
|
||||
% git fetch
|
||||
....
|
||||
At this point you have the src checked out into a Git tree, ready to
|
||||
do other things.
|
||||
|
||||
===== But I have changes that I've not committed
|
||||
|
||||
If you are migrating from a tree that has changes you've not yet
|
||||
committed to FreeBSD, you'll need to follow the steps from the
|
||||
previous section first, and then follow these.
|
||||
[source,shell]
|
||||
....
|
||||
% cd path-to-svn-checkout-tree
|
||||
% svn diff > /tmp/src.diff
|
||||
% cd mumble/freebsd-src
|
||||
% git checkout -b working
|
||||
....
|
||||
This will create a diff of your current changes. The last command
|
||||
creates a branch called `working` though you can call it whatever you
|
||||
want.
|
||||
|
||||
[source,shell]
|
||||
....
|
||||
% git apply /tmp/src.diff
|
||||
....
|
||||
this will apply all your pending changes to the working tree. This
|
||||
doesn't commit the change, so you'll need to make this permanent:
|
||||
|
||||
[source,shell]
|
||||
....
|
||||
% git commit
|
||||
....
|
||||
|
||||
The last command will commit these changes to the branch. The editor
|
||||
will prompt you for a commit message. Enter one as if you were
|
||||
committing to FreeBSD.
|
||||
|
||||
At this point, your work is preserved, and in the Git repo.
|
||||
|
||||
===== Keeping current
|
||||
|
||||
So, time passes. It's time now to update the tree for the latest
|
||||
changes upstream. When you checkout `main` make sure that you have no
|
||||
diffs. It's a lot easier to commit those to a branch (or use `git
|
||||
stash`) before doing the following.
|
||||
|
||||
If you are used to `git pull`, I would strongly recommend using the
|
||||
`--ff-only` option, and further setting it as the default option.
|
||||
Alternatively, `git pull --rebase` is useful if you have changes staged
|
||||
in the main directory.
|
||||
|
||||
[source,shell]
|
||||
....
|
||||
% git config --global pull.ff only
|
||||
....
|
||||
|
||||
[source,shell]
|
||||
....
|
||||
% cd freebsd-src
|
||||
% git checkout main
|
||||
% git pull (--ff-only|--rebase)
|
||||
....
|
||||
|
||||
There is a common trap, that the combination command `git pull` will
|
||||
try to perform a merge, which would sometimes creates a merge commit
|
||||
sha that didn't exist before. This can be harder to recover from.
|
||||
|
||||
The longer form is also recommended.
|
||||
|
||||
[source,shell]
|
||||
....
|
||||
% cd freebsd-src
|
||||
% git checkout main
|
||||
% git fetch freebsd
|
||||
% git merge --ff-only freebsd/main
|
||||
....
|
||||
|
||||
These commands reset your tree to the main branch, and then update it
|
||||
from where you pulled the tree from originally. It's important to
|
||||
switch to `main` before doing this so it moves forward. Now, it's time
|
||||
to move the changes forward:
|
||||
|
||||
[source,shell]
|
||||
....
|
||||
% git rebase -i main working
|
||||
....
|
||||
|
||||
This will bring up an interactive screen to change the defaults.
|
||||
For now, just exit the editor.
|
||||
Everything should just apply.
|
||||
If not, then you'll need to resolve the diffs.
|
||||
https://docs.github.com/en/free-pro-team@latest/github/using-git/resolving-merge-conflicts-after-a-git-rebase[This github document] can help you navigate this process.
|
||||
|
||||
===== Time to push changes upstream
|
||||
|
||||
First, ensure that the push URL is properly configured for the upstream
|
||||
repository.
|
||||
[source,shell]
|
||||
....
|
||||
% git remote set-url --push freebsd ssh://git@gitrepo.freebsd.org/src.git
|
||||
....
|
||||
|
||||
Then, verify that user name and email are configured right. We require
|
||||
that they exactly match the passwd entry in FreeBSD cluster. Use
|
||||
[source,shell]
|
||||
....
|
||||
freefall% gen-gitconfig.sh
|
||||
....
|
||||
on freefall.freebsd.org to get recipe that you can use directly, assuming
|
||||
/usr/local/bin is in the PATH.
|
||||
|
||||
The below command merges the 'working' branch into the upstream main line.
|
||||
It's important that you curate your changes to be just
|
||||
like you want them in the FreeBSD source repo before doing this.
|
||||
[source,shell]
|
||||
....
|
||||
% git push freebsd working:main
|
||||
....
|
||||
|
||||
If your push is rejected due to losing a commit race, rebase your branch
|
||||
before trying again:
|
||||
[source,shell]
|
||||
....
|
||||
% git checkout working
|
||||
% git fetch freebsd
|
||||
% git rebase freebsd/main
|
||||
% git push freebsd working:main
|
||||
....
|
||||
|
||||
===== Finding the Subversion Revision
|
||||
|
||||
You'll need to make sure that you've fetched the notes (see the `No
|
||||
staged changes migration` section above for details. Once you have
|
||||
these, notes will show up in the git log command like so:
|
||||
[source,shell]
|
||||
....
|
||||
% git log
|
||||
....
|
||||
|
||||
If you have a specific version in mind, you can use this construct:
|
||||
[source,shell]
|
||||
....
|
||||
% git log --grep revision=XXXX
|
||||
....
|
||||
|
||||
to find the specific revision. The hex number after 'commit' is the
|
||||
hash you can use to refer to this commit.
|
||||
|
||||
==== Migrating from GitHub fork
|
||||
|
||||
Note: as of this writing, the https://github.com/freebsd/freebsd-src
|
||||
is mirroring all official branches, along with a `master` branch which
|
||||
is the leagcy svn2git result. The `master` branch will not be updated anymore,
|
||||
and the [last commit](https://github.com/freebsd/freebsd-src/commit/de1aa3dab23c06fec962a14da3e7b4755c5880cf)
|
||||
contains the instructions of migrating to new `main` branch.
|
||||
We'll likely retain the `master` branch for a certain time, but in the future
|
||||
it will only be kept in the
|
||||
[freebsd-legacy](https://github.com/freebsd/freebsd-legacy) repository.
|
||||
|
||||
When migrating branches from a github fork from the old github mirror
|
||||
to the official repo, the process is straight forward. This assumes that
|
||||
you have a `freebsd` upstream pointing to github, adjust if necessary.
|
||||
This also assumes a clean tree before starting...
|
||||
|
||||
===== Add the new `freebsd` upstream repository:
|
||||
[source,shell]
|
||||
....
|
||||
% git remote add freebsd https://git.freebsd.org/src.git
|
||||
% git fetch freebsd
|
||||
% git checkout --track freebsd/main
|
||||
....
|
||||
|
||||
===== Rebase all your WIP branches.
|
||||
For each branch FOO, do the following after fetching the `freebsd` sources and creating a local `main` reference with the above checkout:
|
||||
[source,shell]
|
||||
....
|
||||
% git rebase -i freebsd/master FOO --onto main
|
||||
....
|
||||
And you'll now be tracking the official source of truth.
|
||||
You can then follow the `Keeping Current` section above to stay up to date.
|
||||
|
||||
If you need to then commit work to FreeBSD, you can do so following the `Time to push changes upstream` instructions.
|
||||
You'll need to do the following once to update the push URL if you are a FreeBSD committer:
|
||||
[source,shell]
|
||||
....
|
||||
% git remote set-url --push freebsd ssh://git@gitrepo.freebsd.org/src.git
|
||||
....
|
||||
(note that gitrepo.freebsd.org will be change to repo.freebsd.org in the future.)
|
||||
|
||||
You will also need to add `freebsd` as the location to push to. The
|
||||
author recommends that your upstream github repo remain the default
|
||||
push location so that you only push things into FreeBSD you intend to
|
||||
by making it explicit.
|
||||
|
||||
[[subversion-primer]]
|
||||
== Subversion Primer
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue