1 files changed, 27 insertions, 15 deletions
diff --git a/documentation/content/en/articles/committers-guide/_index.adoc b/documentation/content/en/articles/committers-guide/_index.adoc
index 1adfc46e2b..07cece334d 100644
--- a/documentation/content/en/articles/committers-guide/_index.adoc
+++ b/documentation/content/en/articles/committers-guide/_index.adoc
@@ -188,8 +188,7 @@ Rather than suggest a single way, here are some links to sites that describe var
 Protect the private key and passphrase.
 If either the private key or passphrase may have been compromised or disclosed, immediately notify mailto:accounts@FreeBSD.org[accounts@FreeBSD.org] and revoke the key.
 
-Committing the new key is shown in crossref:committers-guide[commit-steps, Steps
-for New Committers].
+Committing the new key is shown in crossref:committers-guide[commit-steps, Steps for New Committers].
 
 [[kerberos-ldap]]
 == Kerberos and LDAP web Password for FreeBSD Cluster
@@ -533,7 +532,7 @@ e.g.:
 ....
 so that won't be covered in depth here.
 
-If you want to build a custom kernel, extref:{handbook}[the kernel config section, kernelconfig] of the FreeBSD Handbook recommends creating a file MYKERNEL under sys/${ARCH}/conf with your changes against GENERIC.
+If you want to build a custom kernel, extref:{handbook}kernelconfig[the kernel config section, kernelconfig] of the FreeBSD Handbook recommends creating a file MYKERNEL under sys/${ARCH}/conf with your changes against GENERIC.
 To have MYKERNEL disregarded by Git, it can be added to .git/info/exclude.
 
 ===== Updating
@@ -688,9 +687,9 @@ The ports tree operates the same way.
 The branch names are different and the repositories are in different locations.
 
 The cgit repository web interface for use with web browsers is at https://cgit.FreeBSD.org/ports/ .
-The production Git repository is at https://git.FreeBSD.org/ports.git and at ssh://anongit@git.FreeBSD.org/ports.git (or anongit@git.FreeBSD.org:ports.git).
+The production Git repository is at https://git.FreeBSD.org/ports.git and at ssh://anongit@git.FreeBSD.org/ports.git (or `anongit@git.FreeBSD.org:ports.git`).
 
-There is also a mirror on GitHub, see extref:{handbook}/mirrors[External mirrors, mirrors] for an overview.
+There is also a mirror on GitHub, see extref:{handbook}mirrors[External mirrors, mirrors] for an overview.
 The _latest_ branch is `main`.
 The _quarterly_ branches are named `yyyyQn` for year 'yyyy' and quarter 'n'.
 
@@ -833,8 +832,10 @@ To abort and get back to the state before "git rebase", run "git rebase --abort"
 Could not apply 646e0f9cda11... no color ls
 ....
 which looks scary.
+
 If you bring up an editor, you will see it is a typical 3-way merge conflict resolution that you may be familiar with from other source code systems (the rest of ls.c has been omitted):
 [source,shell]
+....
  <<<<<<< HEAD
  #ifdef COLORLS_NEW
  #include <terminfo.h>
@@ -844,7 +845,9 @@ If you bring up an editor, you will see it is a typical 3-way merge conflict res
  #include <termcap.h>
  >>>>>>> 646e0f9cda11... no color ls
 ....
+
 The new code is first, and your code is second.
+
 The right fix here is to just add a #undef COLORLS_NEW before #ifdef and then delete the old changes:
 [source,shell]
 ....
@@ -853,6 +856,7 @@ The right fix here is to just add a #undef COLORLS_NEW before #ifdef and then de
 #include <terminfo.h>
 ....
 save the file.
+
 The rebase was interrupted, so you have to complete it:
 [source,shell]
 ....
@@ -1391,7 +1395,7 @@ Here 'good' means:
 . All the right files, and none of the wrong ones, were merged into contrib/glorbnitz.
 . No other changes are in the tree.
 . The commit messages look crossref:committers-guide[commit-log-message,good]. It should contain a summary of what's changed since the last merge to the FreeBSD `main` branch and any caveats.
-. UPDATING should be updated if there is anything of note, such as user visible changes, important upgrade concerns, etc.
+. `RELNOTES` and `UPDATING` should be updated if there is anything of note, such as user visible changes, important upgrade concerns, etc.
 
 [NOTE]
 ====
@@ -1971,11 +1975,11 @@ Before you begin, make sure that your local Git repo is up to date and has the
 correct origins set crossref:committers-guide[keeping_current,as shown above].
 
 [source,shell]
-````
+....
 % git remote -v
 freebsd https://git.freebsd.org/src.git (fetch)
 freebsd ssh://git@gitrepo.freebsd.org/src.git (push)
-````
+....
 
 The first step is to create a fork of https://github.com/freebsd/freebsd-src[FreeBSD] on GitHub following these https://docs.github.com/en/github/getting-started-with-github/fork-a-repo[guidelines].
 The destination of the fork should be your own, personal, GitHub account (gvnn3 in my case).
@@ -2480,15 +2484,16 @@ The subject should, by itself, allow the reader to quickly determine if the chan
 
 The subject line should be as short as possible while still retaining the required information.
 This is to make browsing Git log more efficient, and so that git log --oneline can display the short hash and subject on a single 80-column line.
-A good rule of thumb is to stay below 63 characters, and aim for about 50 or fewer if possible.
+A good rule of thumb is to stay below 67 characters, and aim for about 50 or fewer if possible.
 
 === Prefix the subject line with a component, if applicable
 
 If the change relates to a specific component the subject line may be prefixed with that component name and a colon (:).
+If applicable, try to use the same prefix used in previous commits to the same files.
 
 ✓ `foo: Add -k option to keep temporary data`
 
-Include the prefix in the 63-character limit suggested above, so that `git log --oneline` avoids wrapping.
+Include the prefix in the 67-character limit suggested above, so that `git log --oneline` avoids wrapping.
 
 === Capitalize the first letter of the subject
 
@@ -2648,6 +2653,10 @@ We include the commit title so that the referenced commit can be located even in
 
 |`Relnotes:`
 |If the change is a candidate for inclusion in the release notes for the next release from the branch, set to `yes`.
+|Candidates are user-visible changes, new features, compatibility breaks, etc..
+|If you forget to set this line, or want to provide more details, add an entry to the `RELNOTES` file in the root of the src tree.
+|The `RELNOTES` file is used to generate release notes for the next release.
+|Do not use the `Relnotes:` line to describe the change: its only valid value is `yes`.
 
 |`Security:`
 |If the change is related to a security vulnerability or security exposure, include one or more references or a description of the issue. If possible, include a VuXML URL or a CVE ID.
@@ -2971,6 +2980,9 @@ You can find out more about Bugzilla at:
 The FreeBSD Project utilizes https://reviews.freebsd.org[Phabricator] for code review requests.
 See the https://wiki.freebsd.org/Phabricator[Phabricator wiki page] for details.
 
+Please use the `git arc` command provided by `devel/freebsd-git-devtools` (install the port or package, then type `git help arc` for documentation) to create and update Phabricator reviews.
+This will make it easier for others to review and test your patches.
+
 Committers with non-``FreeBSD.org`` Phabricator accounts can have the old account renamed to the ``FreeBSD.org`` account by following these steps:
 
 [.procedure]
@@ -3145,7 +3157,7 @@ When in doubt, ask for review!
 . Respect existing maintainers if listed.
 +
 Many parts of FreeBSD are not "owned" in the sense that any specific individual will jump up and yell if you commit a change to "their" area, but it still pays to check first.
-One convention we use is to put a maintainer line in the [.filename]#Makefile# for any package or subtree which is being actively maintained by one or more people; see extref:{developers-handbook}[Source Tree Guidelines and Policies, policies] for documentation on this.
+One convention we use is to put a maintainer line in the [.filename]#Makefile# for any package or subtree which is being actively maintained by one or more people; see extref:{developers-handbook}policies[Source Tree Guidelines and Policies, policies] for documentation on this.
 Where sections of code have several maintainers, commits to affected areas by one maintainer need to be reviewed by at least one other maintainer.
 In cases where the "maintainer-ship" of something is not clear, look at the repository logs for the files in question and see if someone has been working recently or predominantly in that area.
 . Any disputed change must be backed out pending resolution of the dispute if requested by a maintainer. Security related changes may override a maintainer's wishes at the Security Officer's discretion.
@@ -3641,7 +3653,7 @@ The `-x` parameter ensures the hash `$HASH` of the `main` branch is included in
 [[ports-qa-new-category-how]]
 ==== What is the procedure for creating a new category?
 
-Please see extref:{porters-handbook}[Proposing a New Category, proposing-categories] in the Porter's Handbook.
+Please see extref:{porters-handbook}makefiles[Proposing a New Category, proposing-categories] in the Porter's Handbook.
 Once that procedure has been followed and the PR has been assigned to the {portmgr}, it is their decision whether or not to approve it.
 If they do, it is their responsibility to:
 
@@ -3675,7 +3687,7 @@ To do this, use the [.filename]#chkorigin.sh# tool: `env PORTSDIR=/path/to/ports
 . Once this is done, you can commit the updated [.filename]#ports/Makefile# to connect the new category to the build and also commit the [.filename]#Makefile# changes for the old category or categories.
 . Add appropriate entries to [.filename]#ports/MOVED#.
 . Update the documentation by modifying:
-** the extref:{porters-handbook}[list of categories, PORTING-CATEGORIES] in the Porter's Handbook
+** the extref:{porters-handbook}makefiles[list of categories, porting-categories] in the Porter's Handbook
 +
 . Only once all the above have been done, and no one is any longer reporting problems with the new ports, should the old ports be deleted from their previous locations in the repository.
 ====
@@ -3684,7 +3696,7 @@ To do this, use the [.filename]#chkorigin.sh# tool: `env PORTSDIR=/path/to/ports
 
 This is much simpler than a physical category. Only a few modifications are needed:
 
-* the extref:{porters-handbook}[list of categories, PORTING-CATEGORIES] in the Porter's Handbook
+* the extref:{porters-handbook}makefiles[list of categories, porting-categories] in the Porter's Handbook
 
 [[ports-qa-misc-questions]]
 === Miscellaneous Questions
@@ -3710,7 +3722,7 @@ No unauthorized commits may ever be made to ports maintained by those groups.
 The packages are built multiple times each week.
 If a port fails, the maintainer will receive an email from `pkg-fallout@FreeBSD.org`.
 
-Reports for all the package builds (official, experimental, and non-regression) are aggregated at link:pkg-status.FreeBSD.org[pkg-status.FreeBSD.org].
+Reports for all the package builds (official, experimental, and non-regression) are aggregated at link:https://pkg-status.FreeBSD.org[pkg-status.FreeBSD.org].
 
 [[ports-qa-misc-INDEX]]
 ==== I added a new port. Do I need to add it to the [.filename]#INDEX#?