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. diff --git a/documentation/content/en/articles/contributing/_index.adoc b/documentation/content/en/articles/contributing/_index.adoc --- a/documentation/content/en/articles/contributing/_index.adoc +++ b/documentation/content/en/articles/contributing/_index.adoc @@ -229,9 +229,10 @@ Chances of this can be minimized somewhat by subscribing to the {freebsd-announce} and the {freebsd-current} lists, where discussions on the current state of the system take place. Assuming that you can manage to secure fairly up-to-date sources to base your changes on, the next step is to produce a set of diffs to send to the FreeBSD maintainers. -This is done with the man:diff[1] command. -The preferred man:diff[1] format for submitting patches is the unified output format generated by `diff -u`. +This can be done manually with the man:diff[1] command or by making use of the diff feature built into man:git[1]. + +When using man:diff[1], the preferred format for submitting patches is the unified output format generated by `diff -u`. [source,shell] .... @@ -249,12 +250,31 @@ See man:diff[1] for more information. -Once you have a set of diffs (which you may test with the man:patch[1] command), you should submit them for inclusion with FreeBSD as a bug report. +man:git[1] can generate a unified diff and include more contextual information through its `-U` flag: + +[source,shell] +.... +% git format-patch -U9999 origin/main +.... + +This will generate a set of patches containing all your changes in contrast to the main branch. + +Once you have a set of diffs (which you may test with the man:patch[1] command), you should submit them for inclusion with FreeBSD as a bug report at link:https://bugs.freebsd.org[Bugzilla]. _Do not_ just send the diffs to the {freebsd-hackers} or they will get lost! We greatly appreciate your submission (this is a volunteer project!); because we are busy, we may not be able to address it immediately, but it will remain in the PR database until we do. Indicate your submission by including `[PATCH]` in the synopsis of the report. -If you feel it appropriate (for example you have added, deleted, or renamed files), bundle your changes into a `tar` file. -Archives created with man:shar[1] are also welcome. +If your work bundles significant changes (for example you have added, deleted, or renamed files), it is recommended to upload your changes to a service like link:https://reviews.freebsd.org[Phabricator] for review. You can do so by adding a comment to your PR listing the URL to the review. +Vice versa, it is helpful and recommended to reference the link to the PR on Phabricator as well. + +To help the review process, it is possible to generate a single diff file [.filename]#patch.diff# through + +[source,shell] +... +git diff -U9999 main origin/main > patch.diff +... + +which can then be uploaded to link:https://reviews.freebsd.org[Phabricator] for public review. +A bug report should still be filed on Bugzilla when uploading to Phabricator and it is recommended to link the Phabricator review in the bug report. If your change is of a potentially sensitive nature, such as if you are unsure of copyright issues governing its further distribution then you should send it to {core-email} directly rather than submitting as a bug report. The {core-email} reaches a much smaller group of people who do much of the day-to-day work on FreeBSD. @@ -265,8 +285,7 @@ === New Code or Major Value-Added Packages -In the case of a significant contribution of a large body work, or the addition of an important new feature to FreeBSD, it becomes almost always necessary to either send changes as tar files or upload them to a web or FTP site for other people to access. -If you do not have access to a web or FTP site, ask on an appropriate FreeBSD mailing list for someone to host the changes for you. +In the case of a significant contribution of a large body work, or the addition of an important new feature to FreeBSD, it becomes almost always necessary to either upload them to link:https://reviews.freebsd.org[Phabricator], or use a service like link:https://github.com[Github] link:https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests[pull requests] for other people to access and review. When working with large amounts of code, the touchy subject of copyrights also invariably comes up. FreeBSD prefers free software licenses such as BSD or ISC. @@ -371,7 +390,8 @@ * *Changes affecting dependent ports.* If other ports depend on a port that you maintain, changes to your port may require coordination with other maintainers. * *Interaction with other users, maintainers and developers.* Part of being a maintainer is taking on a support role. -You are not expected to provide general support (but we welcome it if you choose to do so). What you should provide is a point of coordination for FreeBSD-specific issues regarding your ports. +You are not expected to provide general support (but we welcome it if you choose to do so). +What you should provide is a point of coordination for FreeBSD-specific issues regarding your ports. * *Bug hunting.* A port may be affected by bugs which are specific to FreeBSD. You will need to investigate, find, and fix these bugs when they are reported.