From nobody Thu Jul 23 10:00:40 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 4h5RT501BHz6lW7K for ; Thu, 23 Jul 2026 10:00:41 +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 "YR1" (not verified)) by mx1.freebsd.org (Postfix) with ESMTPS id 4h5RT42G81z3Vxb for ; Thu, 23 Jul 2026 10:00:40 +0000 (UTC) (envelope-from git@FreeBSD.org) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1784800840; 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=dPlKQ7+U1F8LVJwfJFQ+9ClnGK2NsKfBNlkaoqbR4UY=; b=hHk0xkxtjPcP4DRkd8nW5Qxenq9DX/me8dx7pkpG0rmDo+V9FmX2sgYKDU4OzMzvse6ZKo qotfP9kX6sbAWk0I5L1A32EqysyHyc+WlB4BqrgfGZtbXjkSFKl3FHW9DnmDHCwT56Ux2F lwzIWXdZUSIHiz5MRVc9NBQW1FvfAaN9jdYkXlk5yRYb6mbU5Kau9ajJ5PkSBbekckfBAT zJq+QyXv4iq6C/yIIYyKBRJLjBEybON4m+db1Yj+lQ4zzDsz/U/PE/XroWqt2A7OO4xR+A uYCFLLgyfglfGT4fBIizIumuuN7EjiXO9OkL8Ue/lzHf/1QwhYzrnMzHkNSi0g== ARC-Seal: i=1; s=dkim; d=freebsd.org; t=1784800840; a=rsa-sha256; cv=none; b=A5EmwP3YjiWHi2H1rgRAFBsKQkh8yupIH735QA73sWJzevLtUKrnO7EuGVGESkAHqFbPtC tROxcxo7c0hdFEbxQh45qgWi01HeVOp/1NsF2ZZ1jyJ44kjBZqp7Cgun0DzOhS1zOKqbO2 jiiyyMgAYny51+OqpChDA2oIDeLAWigMDdhqSUKjntA2KjMT75BmrDxsJG30McTOJkHIAy cNa6yHhNjEVYAFuuj5w+hQIKzQaRCGoa9vICmpHFGGtT235jZncPvNF5SzjTyJ2fquvl1T SDyVyxE1h0jF8WdqtNhaVuBbhKgkIxg0RyD28upncgRWKyxm9fEE4mlBtUWUpQ== 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=1784800840; 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=dPlKQ7+U1F8LVJwfJFQ+9ClnGK2NsKfBNlkaoqbR4UY=; b=nqouS71VvJf/JgR/K3V9NFMlpfa4uBXO1GVrkc664AEEuddxSUgH0GkN3ajys295ptX7HW +uogkVKUkcnYzifWtOggY3vK8baxI94rA560RyXUZ37iAsbpQybOQ0DpOsYT4f469AEWgK kZB6Vb+4K3+MSHSFCvJBI8Wc0uXzlwvp7Ss1sh9ZFq9Kr/o+pDh+Ta4kZubZB5QIZAShjt WjmLBA32KpkDTWGLQ8fT4ZNp6pVATYXscsSIp/R31AdfunEuWXGCVXizJu2fr4n4U3yKfv ty+OAoPsPNXBu23w6lpm4oNVF3kmaigNdXSLHwcxGSg4VVPgUBy5sdKsO/zURw== Received: from gitrepo.freebsd.org (gitrepo.freebsd.org [IPv6:2610:1c1:1:6068::e6a:5]) by mxrelay.nyi.freebsd.org (Postfix) with ESMTP id 4h5RT41M2Cz10bV for ; Thu, 23 Jul 2026 10:00:40 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from git (uid 1279) (envelope-from git@FreeBSD.org) id 3d334 by gitrepo.freebsd.org (DragonFly Mail Agent v0.13+ on gitrepo.freebsd.org); Thu, 23 Jul 2026 10:00:40 +0000 To: src-committers@FreeBSD.org, dev-commits-src-all@FreeBSD.org, dev-commits-src-branches@FreeBSD.org From: Olivier Certner Subject: git: 90f53c300ac9 - stable/14 - 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 List-Id: List-Post: List-Help: List-Subscribe: List-Unsubscribe: List-Owner: Precedence: list 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/stable/14 X-Git-Reftype: branch X-Git-Commit: 90f53c300ac9ddce9a10f9f67e1c22660148fce6 Auto-Submitted: auto-generated Date: Thu, 23 Jul 2026 10:00:40 +0000 Message-Id: <6a61e648.3d334.5e0670d0@gitrepo.freebsd.org> The branch stable/14 has been updated by olce: URL: https://cgit.FreeBSD.org/src/commit/?id=90f53c300ac9ddce9a10f9f67e1c22660148fce6 commit 90f53c300ac9ddce9a10f9f67e1c22660148fce6 Author: Olivier Certner AuthorDate: 2025-10-03 12:05:46 +0000 Commit: Olivier Certner CommitDate: 2026-07-23 09:59:04 +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 (cherry picked from commit af2c7d9f6452f2281a832b03375910f99230f924) --- 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