git: abff932fe8 - main - Merge in the migration from subversion / github
Warner Losh
imp at FreeBSD.org
Wed Mar 17 04:23:59 UTC 2021
The branch main has been updated by imp:
URL: https://cgit.FreeBSD.org/doc/commit/?id=abff932fe818c144380fd5ebfdcdf44f93de46de
commit abff932fe818c144380fd5ebfdcdf44f93de46de
Author: Warner Losh <imp at FreeBSD.org>
AuthorDate: 2021-03-17 03:55:44 +0000
Commit: Warner Losh <imp at FreeBSD.org>
CommitDate: 2021-03-17 04:23:19 +0000
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
---
.../en/articles/committers-guide/_index.adoc | 275 ++++++++++++++++++++-
1 file changed, 268 insertions(+), 7 deletions(-)
diff --git a/documentation/content/en/articles/committers-guide/_index.adoc b/documentation/content/en/articles/committers-guide/_index.adoc
index 3b93de2d72..9edbef3945 100644
--- a/documentation/content/en/articles/committers-guide/_index.adoc
+++ b/documentation/content/en/articles/committers-guide/_index.adoc
@@ -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 at 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 at 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 at 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
More information about the dev-commits-doc-all
mailing list