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...
|
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-with-git]]
|
||||||
=== MFC (Merge From Current) Procedures
|
=== MFC (Merge From Current) Procedures
|
||||||
==== Summary
|
==== Summary
|
||||||
|
|
@ -490,7 +505,7 @@ Author: John Baldwin <jhb@FreeBSD.org>
|
||||||
Date: Wed Dec 16 00:11:30 2020 +0000
|
Date: Wed Dec 16 00:11:30 2020 +0000
|
||||||
|
|
||||||
Use the 't' modifier to print a ptrdiff_t.
|
Use the 't' modifier to print a ptrdiff_t.
|
||||||
|
|
||||||
Reviewed by: imp
|
Reviewed by: imp
|
||||||
Obtained from: CheriBSD
|
Obtained from: CheriBSD
|
||||||
Sponsored by: DARPA
|
Sponsored by: DARPA
|
||||||
|
|
@ -530,10 +545,10 @@ Author: John Baldwin <jhb@FreeBSD.org>
|
||||||
Date: Wed Dec 16 00:11:30 2020 +0000
|
Date: Wed Dec 16 00:11:30 2020 +0000
|
||||||
|
|
||||||
Use the 't' modifier to print a ptrdiff_t.
|
Use the 't' modifier to print a ptrdiff_t.
|
||||||
|
|
||||||
Obtained from: CheriBSD
|
Obtained from: CheriBSD
|
||||||
Sponsored by: DARPA
|
Sponsored by: DARPA
|
||||||
|
|
||||||
(cherry picked from commit ce8395ecfda2c8e332a2adf9a9432c2e7f35ea81)
|
(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
|
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
|
Date: Thu Dec 3 22:01:13 2020 +0000
|
||||||
|
|
||||||
Don't transmit mbufs that aren't yet ready on TOE sockets.
|
Don't transmit mbufs that aren't yet ready on TOE sockets.
|
||||||
|
|
||||||
This includes mbufs waiting for data from sendfile() I/O requests, or
|
This includes mbufs waiting for data from sendfile() I/O requests, or
|
||||||
mbufs awaiting encryption for KTLS.
|
mbufs awaiting encryption for KTLS.
|
||||||
|
|
||||||
Reviewed by: np
|
Reviewed by: np
|
||||||
MFC after: 2 weeks
|
MFC after: 2 weeks
|
||||||
Sponsored by: Chelsio Communications
|
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
|
This includes mbufs waiting for data from sendfile() I/O requests, or
|
||||||
mbufs awaiting encryption for KTLS.
|
mbufs awaiting encryption for KTLS.
|
||||||
|
|
||||||
Sponsored by: Chelsio Communications
|
Sponsored by: Chelsio Communications
|
||||||
|
|
||||||
(cherry picked from commit 99963f5343a017e934e4d8ea2371a86789a46ff9)
|
(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
|
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.
|
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]]
|
||||||
== Subversion Primer
|
== Subversion Primer
|
||||||
|
|
||||||
|
|
|
||||||
Loading…
Reference in a new issue