The branch main has been updated by olce: URL: https://cgit.FreeBSD.org/src/commit/?id=af2c7d9f6452f2281a832b03375910f99230f924
commit af2c7d9f6452f2281a832b03375910f99230f924 Author: Olivier Certner <[email protected]> AuthorDate: 2025-10-03 12:05:46 +0000 Commit: Olivier Certner <[email protected]> CommitDate: 2026-03-06 17:14:35 +0000 style.9: Encourage style changes when doing significant modifications The rule of allowing style changes when about half or more of a file (or group of files), coupled with the advice of avoiding stylistic changes, could be interpreted as forbidding most style changes, even in heavily modified functions. In order to rule out that interpretation and ease transition towards our prescribed style: 1. Clarify that avoiding stylistic changes concerns only "standalone" ones. 2. Actually encourage changing the style, and extend the cases where it is explicitly allowed to do so to any single logical unit as little as a function, keeping the existing "about half" of modified code as a rule of thumb. When point 2 above applies, encourage to commit pure style changes separately, and to add style-only commits to '.git-blame-ignore-revs'. Add a specific note ruling out "horizontal" style changes spanning unrelated directories in the whole tree, which make the merge (MFC) process more difficult. While here, be slightly more stringent on new kernel code. While here, regroup the paragraphs talking about style, and put them at the end (before the recent C++ section). While here, rephrase the requirement on third-party maintained code to be slightly less stringent. Reviewed by: jhb, imp Sponsored by: The FreeBSD Foundation Differential Revision: https://reviews.freebsd.org/D52885 --- share/man/man9/style.9 | 52 +++++++++++++++++++++++++++++--------------------- 1 file changed, 30 insertions(+), 22 deletions(-) diff --git a/share/man/man9/style.9 b/share/man/man9/style.9 index c9c3af23864a..65636a8af828 100644 --- a/share/man/man9/style.9 +++ b/share/man/man9/style.9 @@ -446,14 +446,6 @@ Functions that are used locally in more than one module go into a separate header file, e.g., .Qq Pa extern.h . .Pp -In general code can be considered -.Dq "new code" -when it makes up about 50% or more of the file(s) involved. -This is enough -to break precedents in the existing code and use the current -.Nm -guidelines. -.Pp The kernel has a name associated with parameter types, e.g., in the kernel use: .Bd -literal @@ -877,20 +869,6 @@ That is, without regard to whether an option takes arguments or not. The alphabetical ordering should take into account the case ordering shown above. .Pp -New core kernel code should be reasonably compliant with the -.Nm -guides. -The guidelines for third-party maintained modules and device drivers are more -relaxed but at a minimum should be internally consistent with their style. -.Pp -Stylistic changes (including whitespace changes) are hard on the source -repository and are to be avoided without good reason. -Code that is approximately -.Fx -KNF -.Nm -compliant in the repository must not diverge from compliance. -.Pp Whenever possible, code should be run through a code checker (e.g., various static analyzers or .Nm cc Fl Wall ) @@ -917,6 +895,36 @@ Only use the annotation for the entire if statement, rather than individual clauses. Do not add these annotations without empirical evidence of the likelihood of the branch. +.Pp +New core kernel code should be compliant with the +.Nm +guides. +The guidelines for third-party maintained modules and device drivers are more +relaxed. +Their code is expected to at least be internally consistent with their style. +.Pp +Stylistic changes, including whitespace ones, complicate the work of downstream +consumers and may impair developers' ability to trace the history of some +changes. +Such standalone must be avoided, and should not span unrelated directories as +this increases the chances of conflicts when merging to stable and release +branches (MFCs). +On the other hand, when a significant portion, usually about a half, of some +logical unit of code, be it a function, group of functions, file or group of +files, is going to be modified, developers are encouraged to amend the style of +the whole unit as described in this document. +In this case, style changes to otherwise unmodified code should be committed +separately. +Style-only commits should be added to the file +.Pa .git-blame-ignore-revs +at the top of the source repository to hide them from +.Ql git blame . +Comments in this file indicate how to use it. +Code that is approximately +.Fx +KNF +.Nm +compliant in the repository must not diverge from compliance. .Ss C++ KNF style was originally defined as a style for C. C++ introduces several new idioms which do not have an existing corollary
