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/X` (`X`-STABLE), `main` (-CURRENT) |=== man:ssh[1] is required to connect to the project hosts. For more information, @@ -455,13 +455,18 @@ However, there are times when you may wish to do a shallow clone. ===== Branch Names -FreeBSD-CURRENT uses the `main` branch. +FreeBSD uses the following branch names: +* `main` - used for FreeBSD-CURRENT; `main` is the default branch. -For FreeBSD-STABLE, branch names include `stable/12` and `stable/13`. +* `stable/X` - used for FreeBSD-STABLE; +`X` is the major release number, for example `stable/14` -For FreeBSD-RELEASE, release engineering branch names include `releng/12.4` and `releng/13.2`. +* `releng/X.Y` - used for FreeBSD-RELEASE; +release engineering branch names are of this form; +`X` is an appropriate recent major and `Y` its associated minor release number; +for example `releng/14.2`. https://www.freebsd.org/releng/[] shows: @@ -791,7 +796,7 @@ Once you enter that, you have your own **local** branch in the Git repo. Build and install it like you normally would, following the directions in the handbook. Git differs from other version control systems in that you have to tell it explicitly which files to commit. -I have opted to do it on the commit command line, but you can also do it with `git add` which many of the more in depth tutorials cover. +The above example does so on the commit command line, but you can also do it with `git add` which many of the more in depth tutorials cover. ====== Time to update @@ -817,7 +822,7 @@ That is OK. Do not panic. Instead, handle them the same as any other merge conflicts. -To keep it simple, I will just describe a common issue that may arise. +To keep it simple, let's describe a common issue that may arise. A pointer to a complete treatment can be found at the end of this section. Let's say the includes changes upstream in a radical shift to terminfo as well as a name change for the option. @@ -874,7 +879,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/X` (`X` being a current release number) to the current branch. If you have a deep clone, the following will suffice: [source,shell] .... @@ -884,19 +889,19 @@ 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/14, then to move to `main`, you can do so the following way: [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/14 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 -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). +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 you had to create a place holder name). [[mfc-with-git]] === MFC (Merge From Current) Procedures @@ -939,7 +944,7 @@ [source,shell] .... -% git checkout releng/13.0 +% git checkout releng/X.Y % git cherry-pick -x $HASH --edit .... @@ -980,7 +985,7 @@ ==== 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/X 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 +1011,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/X .... though if you have some revs you want to keep, and others you don't, using `git rebase -i` is better. @@ -1272,7 +1277,7 @@ % git branch -D YYY .... -Note: I used `XXX` and `YYY` to make it obvious they are terrible names and should not leave your machine. +Note: The example uses `XXX` and `YYY` to make it obvious they are terrible names and should not leave your machine. If you use such names for other work, then you'll need to pick different names, or risk losing the other work. There is nothing magic about these names. Upstream will not allow you to push them, but never the less, please pay attention to the exact commands above. @@ -1336,7 +1341,7 @@ % git commit -m "Import GlorbNitz frobnosticator revision 3.1415" .... -As above, I used `-m` for simplicity, but you should likely create a commit message that explains what a Glorb is and why you'd use a Nitz to get it. +As above,`-m` is used for simplicity, but you should likely create a commit message that explains what a Glorb is and why you'd use a Nitz to get it. Not everybody will know so, for your actual commit, you should follow the crossref:committers-guide[commit-log-message,commit log message] section instead of emulating the brief style used here. @@ -1572,10 +1577,10 @@ [source,shell] .... % cd freebsd-current -% git worktree add ../freebsd-stable-12 stable/12 +% git worktree add ../freebsd-stable-X stable/X .... -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/X` into a directory named `freebsd-stable-X` that's a peer to the `freebsd-current` directory. Once created, it's updated very similarly to how you might expect: [source,shell] @@ -1584,12 +1589,12 @@ % 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-X +% git merge --ff-only freebsd/stable/X +# now your stable/X 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. +It is recommend to use `--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. Here's https://adventurist.me/posts/00296[a good writeup] that goes into more detail.