diff --git a/documentation/content/en/articles/committers-guide/_index.adoc b/documentation/content/en/articles/committers-guide/_index.adoc index b25a555367..d0b66e1a52 100644 --- a/documentation/content/en/articles/committers-guide/_index.adoc +++ b/documentation/content/en/articles/committers-guide/_index.adoc @@ -1393,22 +1393,15 @@ How so do that is specific to the software being imported and is beyond the scop === 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. +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`): +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. +The fist thing to do is install git. Any version of Git will do, though the latest one in ports / packages generally will be good. +Either build it from ports, or install it using pkg (though some folks might use `su` or `doas` instead of `sudo`): [source,shell] .... @@ -1417,87 +1410,79 @@ ports, or install it using pkg (though some folks might use `su` or ===== 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: +If you have no changes pending, the migration is straightforward. +In this, you abandon the Subversion tree and clone the Git repoository. +It's likely best to retain your subversion tree, in case there's something you've forgotten about there. +First, let's clone the repository: [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. +will create a clone of the FreeBSD src repository into a subdirectory called `freebsd-src` and include the 'notes' about the revisions. +We are currently mirroring the source repository to https://github.com/freebsd/freebsd-src.git as well. +https://github.com/freebsd/freebsd-legacy.git has the old github mirror with the old hashes should you need that for your migration. +The github `master` branch has been frozen. +As the default in git has change, we've shifted from `master` to `main`, the new repository uses `main`. +We also mirror the repository to gitlab at https://gitlab.com/FreeBSD/src.git . -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: +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 repository without this, or wish to add notes to a 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. +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. +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 +% 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. +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: +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 add _files_ % 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. +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. +At this point, your work is preserved, and in the Git repository. ===== 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. +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. +If you are used to `git pull`, we 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 branch. [source,shell] .... % git config --global pull.ff only .... +You may need to omit the --global if you want this setting to only this repository. [source,shell] .... @@ -1506,9 +1491,8 @@ in the main directory. % 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. +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. @@ -1551,19 +1535,16 @@ that they exactly match the passwd entry in FreeBSD cluster. Use .... freefall% gen-gitconfig.sh .... -on freefall.freebsd.org to get recipe that you can use directly, assuming -/usr/local/bin is in the PATH. +on freefall.freebsd.org to get a 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. +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: +If your push is rejected due to losing a commit race, rebase your branch before trying again: [source,shell] .... % git checkout working @@ -1593,13 +1574,12 @@ 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 +Note: as of this writing, 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, +is the legacy 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 +contains the instructions for migrating to the new `main` branch. +We'll 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 @@ -1616,15 +1596,15 @@ This also assumes a clean tree before starting... .... ===== 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: +For each branch FOO, do the following after fetching the `freebsd` sources and creating a local `main` branch 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. +And you'll now be tracking the official repository. 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. +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] ....