From nobody Fri Mar 6 17:15:42 2026 X-Original-To: dev-commits-src-all@mlmmj.nyi.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2610:1c1:1:606c::19:1]) by mlmmj.nyi.freebsd.org (Postfix) with ESMTP id 4fSCjH4PMwz6T6TW for ; Fri, 06 Mar 2026 17:15:47 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from mxrelay.nyi.freebsd.org (mxrelay.nyi.freebsd.org [IPv6:2610:1c1:1:606c::19:3]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256 client-signature RSA-PSS (4096 bits) client-digest SHA256) (Client CN "mxrelay.nyi.freebsd.org", Issuer "R12" (not verified)) by mx1.freebsd.org (Postfix) with ESMTPS id 4fSCjH3Nz9z3GZJ for ; Fri, 06 Mar 2026 17:15:47 +0000 (UTC) (envelope-from git@FreeBSD.org) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1772817347; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding; bh=cZfF2ci3Dg3ycRWHLXapGNliX8+xyuApMMuLUrnpj3w=; b=vtONReH0STRzr8UZat22miewWIEwAaOG6HQ0iJIRb4dg2j2jfUPXik4KtGrHkbK24ey1cD hqjCrZYjnVvnQadP9Eo20PePWcb1Pnui8Xj6SjKd1k/fETKffuNdR4lL6MaTl7Tqpp3s5x ibWr+UAIpWM0twZgKrqx/FDI/pxXTYfhvkhb/8CsgVjtqfJlu9G4GHPugcOzl5HXZX87XV Z9hDWTttShfQuyqEZSQxAGRYOW7Ys0bhBXSLvQG5DpOpL5T97I/OXD/6IDds6fwODFUvVU Mz1EGpskZqBB8fYIzVPP+ZhDGKn+EZGNzr/B4uxrBZ+c1ezB6Mlenob/Nu+GjA== ARC-Seal: i=1; s=dkim; d=freebsd.org; t=1772817347; a=rsa-sha256; cv=none; b=BK1VeHVqucie5lS2QYDYVc4TByujeV8rPi4XN0A7fy/+IxnOe5wYWRgTH1zpAtakk+jt1C LvZT6sXdSPsxui4sgiuSJscSmqszjpDMI/1jv02VuM0KcVA+e4DovDehBKPLu0RGY+wW1e Jz0OYPt0/AAP9VYsabSuO51AAWLW/aCN5Qxyo4AzIl1KZLxqiTIqpkY7ti/DKQsV1JuWFm cXb8LyyITu+Go4SkBsvqJj45OELRTRCQkU70YTn1BxqmKsfR82XZzGZIOAzYGVj2s6ygId s+3NeatMikVSbpGDKMBtyHd9HjQ/3qyfXA0nQz1z0zHDltoF0r0L0fHHnDBJ+Q== ARC-Authentication-Results: i=1; mx1.freebsd.org; none ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1772817347; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding; bh=cZfF2ci3Dg3ycRWHLXapGNliX8+xyuApMMuLUrnpj3w=; b=CGSyW4bJ17IkScJncuXLQxPE2ZKkt7WXaR7nqUuitWvEqVsHMyk6TAKhIGT42aV1aU0gi/ T6gC4yVfWEfewAvhWQW3OTnvPQq+/06wBbrELZHLOHsXRJLlL01QrNRqWQ7TD/Wk0adfTO uHDcIaSN/eTB7qvMjcunJo4OV/vN1Qi455TdiqVcO78dmOt+2n9eIYnsoriSYcpj7y77LM cjBZ5ZCyQq3L7f0B//yc4VhvMpxetQL64rNnnpQSUlc5sfugF5iLemlyZiExQ2sL/jSekD WohBvEt/jHs9TKpAmqBnyqyRYc41aJyLl4n+gk+o9O7saxgzo3c/ABc6ULqf4A== Received: from gitrepo.freebsd.org (gitrepo.freebsd.org [IPv6:2610:1c1:1:6068::e6a:5]) by mxrelay.nyi.freebsd.org (Postfix) with ESMTP id 4fSCjH2wSBzXGf for ; Fri, 06 Mar 2026 17:15:47 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from git (uid 1279) (envelope-from git@FreeBSD.org) id 3e2e4 by gitrepo.freebsd.org (DragonFly Mail Agent v0.13+ on gitrepo.freebsd.org); Fri, 06 Mar 2026 17:15:42 +0000 To: src-committers@FreeBSD.org, dev-commits-src-all@FreeBSD.org, dev-commits-src-main@FreeBSD.org From: Olivier Certner Subject: git: af2c7d9f6452 - main - style.9: Encourage style changes when doing significant modifications List-Id: Commit messages for all branches of the src repository List-Archive: https://lists.freebsd.org/archives/dev-commits-src-all List-Help: List-Post: List-Subscribe: List-Unsubscribe: X-BeenThere: dev-commits-src-all@freebsd.org Sender: owner-dev-commits-src-all@FreeBSD.org MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit X-Git-Committer: olce X-Git-Repository: src X-Git-Refname: refs/heads/main X-Git-Reftype: branch X-Git-Commit: af2c7d9f6452f2281a832b03375910f99230f924 Auto-Submitted: auto-generated Date: Fri, 06 Mar 2026 17:15:42 +0000 Message-Id: <69ab0bbe.3e2e4.5681b2ed@gitrepo.freebsd.org> The branch main has been updated by olce: URL: https://cgit.FreeBSD.org/src/commit/?id=af2c7d9f6452f2281a832b03375910f99230f924 commit af2c7d9f6452f2281a832b03375910f99230f924 Author: Olivier Certner AuthorDate: 2025-10-03 12:05:46 +0000 Commit: Olivier Certner 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