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/{betarel-current-major}` (`{betarel-current-major}-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/{betarel-current-major}` -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/{betarel-current}`. 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/{betarel-current-major}` to the current branch. If you have a deep clone, the following will suffice: [source,shell] .... @@ -884,19 +889,22 @@ 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/{betarel-current-major}`, then to move to `main`, you can do so the following way. +Replace `X` with the desired major release number, for example `{betarel-current-major}`: [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-X # create another name for this branch +% git rebase -i stable/X 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 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). +What the above does is + +. checkout `no-color-ls`. +. then create a new name for it (for example `no-color-ls-stable-{betarel-current-major}`) 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/X` branch (for example `stable/{betarel-current-major}`) 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 @@ -932,14 +940,15 @@ 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/{betarel-current-major}` branch first before merging to the `releng/{betarel-current}` branch. +* Use the hash that's in the `stable/{betarel-current-major}` branch for the MFC to `releng/{betarel-current}` 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. +Make sure to replace `X.Y` with the correct release number, for example `{betarel-current}`: [source,shell] .... -% git checkout releng/13.0 +% git checkout releng/X.Y % git cherry-pick -x $HASH --edit .... @@ -947,6 +956,7 @@ ==== Multiple commit MFC +Same as for single commits, make sure to replace `X` with the approprate major release number in the following code snippets, for example `{betarel-current-major}`: [source,shell] .... % git checkout -b tmp-branch stable/X @@ -980,7 +990,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/{betarel-current-major} 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] @@ -1003,10 +1013,10 @@ ==== Redoing a MFC If you do a MFC, and it goes horribly wrong and you want to start over, -then the easiest way is to use `git reset --hard` like so: +then the easiest way is to use `git reset --hard` like so (replace `X` with the appropriate release number, for example `{betarel-current-major}`): [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 +1282,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 +1346,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. @@ -1567,15 +1577,15 @@ % git clone -o freebsd --config remote.freebsd.fetch='+refs/notes/*:refs/notes/*' $URL freebsd-current .... -then once that's cloned, you can simply create a worktree from it: +then once that's cloned, you can simply create a worktree from it (replace `X` with the appropriate major release number, for example `{betarel-current-major}`): [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 +1594,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. @@ -2986,7 +2996,7 @@ `{so-name}` is the link:https://www.FreeBSD.org/security/[FreeBSD Security Officer] and oversees the `{security-officer}`. {committers-name}:: -{dev-src-all}, {dev-ports-all} and {dev-doc-all} are the mailing lists that the version control system uses to send commit messages to. +{dev-commits-src-all}, {dev-commits-ports-all} and {dev-commits-doc-all} are the mailing lists that the version control system uses to send commit messages to. _Never_ send email directly to these lists. Only send replies to this list when they are short and are directly related to a commit. @@ -3141,7 +3151,7 @@ There is also really no point in having FreeBSD-CURRENT be a testing ground if changes are merged over to FreeBSD-STABLE immediately. Changes need a chance to be tested by the FreeBSD-CURRENT developers, so allow some time to elapse before merging unless the FreeBSD-STABLE fix is critical, time sensitive or so obvious as to make further testing unnecessary (spelling fixes to manual pages, obvious bug/typo fixes, etc.) In other words, apply common sense. + -Changes to the security branches (for example, `releng/9.3`) must be approved by a member of the `{security-officer}`, or in some cases, by a member of the `{re}`. +Changes to the security branches (for example, `releng/{betarel-current}`) must be approved by a member of the `{security-officer}`, or in some cases, by a member of the `{re}`. . Do not fight in public with other committers; it looks bad. + This project has a public image to uphold and that image is very important to all of us, especially if we are to continue to attract new members.