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 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 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 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