From nobody Tue Jul 14 23:01:06 2026 X-Original-To: dev-commits-doc-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 4h0FCr05r6z6lRFM for ; Tue, 14 Jul 2026 23:01:12 +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 4h0FCq6XDQz3HKC for ; Tue, 14 Jul 2026 23:01:11 +0000 (UTC) (envelope-from git@FreeBSD.org) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1784070071; 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=u4dXGmzVjV5YoF5S4ev7fJh00weU91OZNq4N6SwQok4=; b=lLzl69Ra8TNt8wU3sjklKrAcDUwpdFKmTm4SYigU0QaQGMvhQsjeM7HlfT6xFJyKqA4Ed/ TU6NFPg1RGxeQebHtX5WD00IYKLp2gDfV1WHy7F4lPnH8YcZZJorEFfZ1v97I8INBhRTMK v1Ugd7zbsZoOKQ3vWanVrwUIKwHy/Amn4Kw32GbdMyNXy8SkFhBfdeViC921/IljJ1JAFy CvT4LMRiZWadUqY3GR5H4LF7D9kDieHjiCJwXjBOkt7DZ1JZd2W35p16krC1+TQQriaqVM aOjXIJL2XrXmLJOLE8R5tXnznk2gRIIZ2ewa8BY+vyWjYmCDbNrOvWL1e+xCdQ== ARC-Seal: i=1; s=dkim; d=freebsd.org; t=1784070071; a=rsa-sha256; cv=none; b=UVWSm2bUrHD9eVm0POE/6n38O+5pJFyLa5MshZYEEiApjSTFyR6/iahtmKTDdwOuyG8t82 PxWphvZkDYqseikQJJDvz1YSPWXj+6m/ozVMl4/I9/3wwqPvCphA6MGxtqUvoggXZD9PAx SsK2M8UFAgccMWKS6ISpqzlM7PME1ArJAg8DAViH/gjkC3D2S89Uy/XejAlwF/KlY/RaSZ GokSH0kUktXbD4NEM0a+WvuuqlVm4ScsbWGycGCY7Vv9uo3jycxI4GSCF7hi2QtSOMLh7i KXdgejNPvGAO+swBr8YTE1yhgvehdEYiZQOpoIwhFEYQg4XSPy0ENkzqsukENg== 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=1784070071; 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=u4dXGmzVjV5YoF5S4ev7fJh00weU91OZNq4N6SwQok4=; b=QC1QjIbAg9nip0RAHEftdWXcTBtEmdvu3+bXdy+2XCbUPfgUb2Jlak4Bk/iBMlYtVeycJm YgTiDGFBJOr1DQI9n6nl5OwfxTagTFx3+4Ea98PvQ0a2M87ru2XN5d6tH2zBZ2tTGBfvUl mLLeT6LxN5lnh/KaxV3djZhpEe4WA2d4FskUE47XUvGxiTuVTkHTQe02l60rG3AzC53qAA LHkIV/xMCOtSkGQQYfFT2O0pO6Pa3jA+AooaQJSNYCRucSK6dFfzCVq42kSfij0ql+yS+j z2rwvB9QQy/jBTtRgkAQiL6/yJVzjXIv69iqJAbc81BjrtjIvzKkiFiAdi9zEw== Received: from gitrepo.freebsd.org (gitrepo.freebsd.org [IPv6:2610:1c1:1:6068::e6a:5]) by mxrelay.nyi.freebsd.org (Postfix) with ESMTP id 4h0FCq4wd3z14bM for ; Tue, 14 Jul 2026 23:01:11 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from git (uid 1279) (envelope-from git@FreeBSD.org) id 21b3f by gitrepo.freebsd.org (DragonFly Mail Agent v0.13+ on gitrepo.freebsd.org); Tue, 14 Jul 2026 23:01:06 +0000 To: doc-committers@FreeBSD.org, dev-commits-doc-all@FreeBSD.org From: Warner Losh Subject: git: 5055f6624b - main - Harmonize the cross repo advice. List-Id: Commit messages for all branches of the doc repository List-Archive: https://lists.freebsd.org/archives/dev-commits-doc-all List-Help: List-Post: List-Subscribe: List-Unsubscribe: X-BeenThere: dev-commits-doc-all@freebsd.org Sender: owner-dev-commits-doc-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: imp X-Git-Repository: doc X-Git-Refname: refs/heads/main X-Git-Reftype: branch X-Git-Commit: 5055f6624bd0bdf00c4a94cfd7cccb9b31a3b9c6 Auto-Submitted: auto-generated Date: Tue, 14 Jul 2026 23:01:06 +0000 Message-Id: <6a56bfb2.21b3f.3648443e@gitrepo.freebsd.org> The branch main has been updated by imp: URL: https://cgit.FreeBSD.org/doc/commit/?id=5055f6624bd0bdf00c4a94cfd7cccb9b31a3b9c6 commit 5055f6624bd0bdf00c4a94cfd7cccb9b31a3b9c6 Author: Warner Losh AuthorDate: 2026-07-14 22:59:44 +0000 Commit: Warner Losh CommitDate: 2026-07-14 22:59:44 +0000 Harmonize the cross repo advice. The other committer's guide was written years before the cross repo commit bit stuff. Harmonize and expand a little the advice given to make it also match the tone of the new policy and our usual practices being a little more relaxed than what was documented previously. Sponsored by: Netflix Feedback by: jhb Differential Revision: https://reviews.freebsd.org/D58007 --- .../en/articles/committers-guide/_index.adoc | 27 ++++++++++++++++++---- .../content/en/internal/cross-repo-commits.adoc | 3 +++ 2 files changed, 25 insertions(+), 5 deletions(-) diff --git a/documentation/content/en/articles/committers-guide/_index.adoc b/documentation/content/en/articles/committers-guide/_index.adoc index b974f62b70..70b1bf8f4c 100644 --- a/documentation/content/en/articles/committers-guide/_index.adoc +++ b/documentation/content/en/articles/committers-guide/_index.adoc @@ -260,11 +260,28 @@ Committers are encouraged to seek review for their work as part of the normal de === Policy for Committer Activity in Other Trees +Committers are trusted to use good judgment when working outside their primary area. +The link:https://www.freebsd.org/internal/cross-repo-commits/[Cross Repo Commit Policy] describes the overall framework. +The following guidelines apply: + +==== General Guidelines + +These changes do not require review or approval from a committer in the target repository: + * All committers may modify [.filename]#src/share/misc/committers-*.dot#, [.filename]#src/usr.bin/calendar/calendars/calendar.freebsd#, and [.filename]#ports/astro/xearth/files#. -* doc committers may commit documentation changes to [.filename]#src# files, such as manual pages, READMEs, fortune databases, calendar files, and comment fixes without approval from a src committer, subject to the normal care and tending of commits. -* Any committer may make changes to any other tree with an "Approved by" from a non-mentored committer with the appropriate bit. -Mentored committers can provide a "Reviewed by" but not an "Approved by". -* Committers can acquire an additional bit by the usual process of finding a mentor who will propose them to srcmgr, doceng, or portmgr, as appropriate. When approved, they will be added to 'access' and the normal mentoring period will ensue, which will involve a continuing of "Approved by" for some period. +* All committers may commit documentation changes to [.filename]#src# files, such as manual pages, READMEs, fortune databases, calendar files, and comment fixes, subject to the normal care and tending of commits. +* Obvious trivial fixes — typos, broken links, and similar trivial corrections — may be committed by any committer to any repository (see also <>). +* When you have recently introduced a build breakage that's trivial to resolve, though a revert and a full review usually is better for anything non-trivial. + +==== Non-Obvious Changes + +For changes beyond those described here, committers should seek review from committers with the appropriate bit in the target repository. +When in doubt, seek review, even if you have a commit bit in the repo. +Always test build and test run or read files affected by the change. + +==== Acquiring Additional Commit Bits + +Committers can acquire an additional bit by the usual process of finding a mentor who will propose them to srcmgr, doceng, or portmgr, as appropriate. [[doc-blanket-approval]] ==== Documentation Implicit (Blanket) Approval @@ -2625,7 +2642,7 @@ There are several cases where approval is customary: * while a new committer is under mentorship * commits to an area of the tree covered by the LOCKS file (src) * during a release cycle -* committing to a repo where you do not hold a commit bit (e.g. src committer committing to docs) +* committing non-obvious changes to a repo where you do not hold a commit bit (e.g. src committer committing to docs); for obvious fixes, `Reviewed by:` is sufficient * committing to a port maintained by someone else While under mentorship, get mentor approval before the commit. Enter the mentor's username in this field, and note that they are a mentor: diff --git a/website/content/en/internal/cross-repo-commits.adoc b/website/content/en/internal/cross-repo-commits.adoc index bb8019479e..1b567f2e8d 100644 --- a/website/content/en/internal/cross-repo-commits.adoc +++ b/website/content/en/internal/cross-repo-commits.adoc @@ -16,6 +16,9 @@ This policy provides flexibility for contributors to commit across repositories ** *Expert Consultation:* Repository experts are consulted for non-trivial changes. ** *Stricter Rules:* The committer remains deferential to areas requiring formal oversight (e.g., the `ports/Mk` tree). ** *Scale:* The larger or more complex the change, the more critical it is to seek review and wait for explicit approval. +** *When in Doubt:* Seek review from a committer experienced in the target repository before committing. * *Accountability:* Committers must accept feedback on both process and content. If a mistake occurs, the default action is an immediate backout, followed by a more formal review, as appropriate. When in doubt, ask first and seek a sanity check. + +See the extref:{committers-guide}[Committer's Guide] for specific blanket grants and commit message conventions.