git: 5055f6624b - main - Harmonize the cross repo advice.

The branch main has been updated by imp:

URL: https://cgit.FreeBSD.org/doc/commit/?id=5055f6624bd0bdf00c4a94cfd7cccb9b31a3b9c6

commit 5055f6624bd0bdf00c4a94cfd7cccb9b31a3b9c6
Author:     Warner Losh <imp@FreeBSD.org>
AuthorDate: 2026-07-14 22:59:44 +0000
Commit:     Warner Losh <imp@FreeBSD.org>
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 <<doc-blanket-approval>>).
+* 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.