diff --git a/documentation/content/en/articles/committers-guide/_index.adoc b/documentation/content/en/articles/committers-guide/_index.adoc --- a/documentation/content/en/articles/committers-guide/_index.adoc +++ b/documentation/content/en/articles/committers-guide/_index.adoc @@ -95,7 +95,7 @@ |[.filename]#/home/portmgr/public/monthly-reports# on the `FreeBSD.org` cluster. |_Noteworthy `src/` Git Branches:_ -|`stable/n` (`n`-STABLE), `main` (-CURRENT) +|`stable/N` (`N`-STABLE), `main` (-CURRENT) |=== man:ssh[1] is required to connect to the project hosts. For more information, @@ -459,9 +459,9 @@ `main` is the default branch. -For FreeBSD-STABLE, branch names include `stable/12` and `stable/13`. +For FreeBSD-STABLE, branch names include `stable/N` (where `N` is the major release number, i.e. up to `14` as of 2024) -For FreeBSD-RELEASE, release engineering branch names include `releng/12.4` and `releng/13.2`. +For FreeBSD-RELEASE, release engineering branch names include `releng/N.n` (where `N` is the most recent major and `n` its associated minor release number, i.e. 14.2 as of November 2024). https://www.freebsd.org/releng/[] shows: @@ -874,7 +874,7 @@ It is a good resource for issues that arise occasionally but are too obscure for this guide. ===== Switching to a Different FreeBSD Branch -If you wish to shift from stable/12 to the current branch. +If you wish to shift from stable/13 to the current branch. If you have a deep clone, the following will suffice: [source,shell] .... @@ -884,18 +884,18 @@ If you have a local branch, though, there are one or two caveats. First, rebase will rewrite history, so you will likely want to do something to save it. Second, jumping branches tends to cause more conflicts. -If we pretend the example above was relative to stable/12, then to move to `main`, I'd suggest the following: +If we pretend the example above was relative to stable/13, then to move to `main`, I'd suggest the following: [source,shell] .... % git checkout no-color-ls -% git checkout -b no-color-ls-stable-12 # create another name for this branch -% git rebase -i stable/12 no-color-ls --onto main +% git checkout -b no-color-ls-stable-14 # create another name for this branch +% git rebase -i stable/13 no-color-ls --onto main .... What the above does is checkout no-color-ls. -Then create a new name for it (no-color-ls-stable-12) in case you need to get back to it. +Then create a new name for it (no-color-ls-stable-14) in case you need to get back to it. Then you rebase onto the `main` branch. -This will find all the commits to the current no-color-ls branch (back to where it meets up with the stable/12 branch) and then it will +This will find all the commits to the current no-color-ls branch (back to where it meets up with the stable/13 branch) and then it will replay them onto the `main` branch creating a new no-color-ls branch there (which is why I had you create a place holder name). [[mfc-with-git]] @@ -909,7 +909,7 @@ [source,shell] .... -% git checkout stable/X +% git checkout stable/N % git cherry-pick -x $HASH --edit .... @@ -918,7 +918,7 @@ [source,shell] .... -% git checkout stable/X +% git checkout stable/N % git cherry-pick -x $HASH -m 1 --edit .... @@ -932,8 +932,8 @@ MFCs to branches that require approval require a bit more care. The process is the same for either a typical merge or an exceptional direct commit. -* Merge or direct commit to the appropriate `stable/X` branch first before merging to the `releng/X.Y` branch. -* Use the hash that's in the `stable/X` branch for the MFC to `releng/X.Y` branch. +* Merge or direct commit to the appropriate `stable/N` branch first before merging to the `releng/N.n` branch. +* Use the hash that's in the `stable/N` branch for the MFC to `releng/N.n` branch. * Leave both "cherry picked from" lines in the commit message. * Be sure to add the `Approved by:` line when you are in the editor. @@ -949,38 +949,38 @@ [source,shell] .... -% git checkout -b tmp-branch stable/X +% git checkout -b tmp-branch stable/N % for h in $HASH_LIST; do git cherry-pick -x $h; done -% git rebase -i stable/X +% git rebase -i stable/N # mark each of the commits after the first as 'squash' # Update the commit message to reflect all elements of commit, if necessary. # Be sure to retain the "cherry picked from" lines. -% git push freebsd HEAD:stable/X +% git push freebsd HEAD:stable/N .... If the push fails due to losing the commit race, rebase and try again: [source,shell] .... -% git checkout stable/X +% git checkout stable/N % git pull % git checkout tmp-branch -% git rebase stable/X -% git push freebsd HEAD:stable/X +% git rebase stable/N +% git push freebsd HEAD:stable/N .... Once the MFC is complete, you can delete the temporary branch: [source,shell] .... -% git checkout stable/X +% git checkout stable/N % git branch -d tmp-branch .... ==== MFC a vendor import Vendor imports are the only thing in the tree that creates a merge commit in the `main` branch. -Cherry picking merge commits into stable/XX presents an additional difficulty because there are two parents for a merge commit. +Cherry picking merge commits into stable/N presents an additional difficulty because there are two parents for a merge commit. Generally, you'll want the first parent's diff since that's the diff to `main` (though there may be some exceptions). [source,shell] @@ -1006,7 +1006,7 @@ then the easiest way is to use `git reset --hard` like so: [source,shell] .... -% git reset --hard freebsd/stable/12 +% git reset --hard freebsd/stable/13 .... though if you have some revs you want to keep, and others you don't, using `git rebase -i` is better. @@ -1572,10 +1572,10 @@ [source,shell] .... % cd freebsd-current -% git worktree add ../freebsd-stable-12 stable/12 +% git worktree add ../freebsd-stable-12 stable/13 .... -this will checkout `stable/12` into a directory named `freebsd-stable-12` that's a peer to the `freebsd-current` directory. +this will checkout `stable/13` into a directory named `freebsd-stable-12` that's a peer to the `freebsd-current` directory. Once created, it's updated very similarly to how you might expect: [source,shell] @@ -1584,9 +1584,9 @@ % git checkout main % git pull --ff-only # changes from upstream now local and current tree updated -% cd ../freebsd-stable-12 -% git merge --ff-only freebsd/stable/12 -# now your stable/12 is up to date too +% cd ../freebsd-stable-13 +% git merge --ff-only freebsd/stable/13 +# now your stable/13 is up to date too .... I recommend using `--ff-only` because it's safer and you avoid accidentally getting into a 'merge nightmare' where you have an extra change in your tree, forcing a complicated merge rather than a simple one.