articles/contributing Pet vale

- Change INDEX-8 to INDEX-13
- Remove references to portmaster/portupgrade [1]

Approved by:	portmgr [1]

2 files changed, 96 insertions, 45 deletions

diff --git a/.vale/styles/Vocab/Terms/accept.txt b/.vale/styles/Vocab/Terms/accept.txt
index 49368cab11..1e83c94af6 100644
--- a/.vale/styles/Vocab/Terms/accept.txt
+++ b/.vale/styles/Vocab/Terms/accept.txt
@@ -1,6 +1,7 @@
 (?i)bpf
 (?:je|tc)malloc
 AMCC\'s
+ABIs?
 APIs?
 Accetta
 Adaptec
@@ -14,6 +15,7 @@ DARPA
 DTDs
 DTrace
 ECMAscript
+EFNet
 Englewood
 Ewens
 Excelan
@@ -31,6 +33,7 @@ Karels
 Kernighan
 Konsole
 Lua
+Libera
 MFC
 Macklem
 Mellanox
@@ -65,12 +68,11 @@ Winsock
 [Dd]illo
 [Dd]ummynet
 [Ee]thernets
-[Ff]alkon
-[Ff]ortran
-[Ff]ramebuffer
+[Ff](?:alkon|ixup|ortran|ramebuffer)
 [Jj]ourna(?:led|ling)
 [Kk](?:byte|develop|help|obj|onqueror)
 [Ll][Xx][Qq]t
+[Ll][Ll][Vv][Mm]
 [Mm](?:akefile|icrosystems|map|ulticast)
 [Nn](?:eovim|etgraph|etmap)
 [Oo]kular
@@ -157,7 +159,6 @@ libutil
 lib(?:alias|elf|lzma|m|md|objc|pam|pcap|pthread|thr|ulog|utempter)
 lightdm
 lldb?
-llvm
 lockless
 lookups
 lseek
@@ -202,7 +203,7 @@ prepended
 procfs
 poudriere
 public_html
-re(?:adline|adv|base|branded|cv|cvfrom|cvmsg|entrant)
+re(?:adline|adv|base|branded|cv|cvfrom|cvmsg|entrant|po)
 reimplement(?:ation|ed|ing)
 rm(?:dir|port)
 rtld
diff --git a/documentation/content/en/articles/contributing/_index.adoc b/documentation/content/en/articles/contributing/_index.adoc
index ceefd904e5..c19f294c80 100644
--- a/documentation/content/en/articles/contributing/_index.adoc
+++ b/documentation/content/en/articles/contributing/_index.adoc
@@ -41,6 +41,8 @@ ifndef::env-beastie[]
 include::../../../../../shared/asciidoctor.adoc[]
 endif::[]
 
+pass:[<!-- vale FreeBSD.Pronouns = NO -->]
+
 [.abstract-title]
 Abstract
 
@@ -50,7 +52,9 @@ This article describes the different ways in which an individual or organization
 
 toc::[]
 
-So you want to contribute to FreeBSD? That is great! FreeBSD _relies_ on the contributions of its user base to survive.
+So you want to contribute to FreeBSD?
+That is great!
+FreeBSD _relies_ on the contributions of its user base to survive.
 Your contributions are not only appreciated, they are vital to FreeBSD's continued growth.
 
 A large and growing number of international contributors, of greatly varying ages and areas of technical expertise, develop FreeBSD.
@@ -65,8 +69,11 @@ As such, our [.filename]#TODO# lists span a very wide range of tasks: from docum
 People of any skill level, in almost any area, can almost certainly help the project.
 
 Commercial entities engaged in FreeBSD-related enterprises are also encouraged to contact us.
-Do you need a special extension to make your product work? You will find us receptive to your requests, given that they are not too outlandish.
-Are you working on a value-added product? Please let us know! We may be able to work cooperatively on some aspect of it.
+Do you need a special extension to make your product work?
+You will find us receptive to your requests, given that they are not too outlandish.
+Are you working on a value-added product?
+Please let us know!
+We may be able to work cooperatively on some aspect of it.
 The free software world is challenging many existing assumptions about how software is developed, sold, and maintained, and we urge you to at least give it a second look.
 
 [[contrib-what]]
@@ -81,9 +88,18 @@ Many people who are involved in FreeBSD are not programmers.
 The Project includes documentation writers, Web designers, and support people.
 All that these people need to contribute is an investment of time and a willingness to learn.
 
-. Read through the FAQ and Handbook periodically. If anything is poorly explained, ambiguous, out of date or incorrect, let us know. Even better, send us a fix (AsciiDoc is not difficult to learn, but there is no objection to plain text submissions).
-. Help translate FreeBSD documentation into your native language. If documentation already exists for your language, you can help translate additional documents or verify that the translations are up-to-date and correct. First take a look at the extref:{fdp-primer}[Translations FAQ, translations] in the FreeBSD Documentation Project Primer. You are not committing yourself to translating every single FreeBSD document by doing this - as a volunteer, you can do as much or as little translation as you desire. Once someone begins translating, others almost always join the effort. If you only have the time or energy to translate one part of the documentation, please translate the installation instructions.
-. Read the {freebsd-questions} occasionally (or even regularly). It can be very satisfying to share your expertise and help people solve their problems; sometimes you may even learn something new yourself! These forums can also be a source of ideas for things to improve upon. 
+. Read through the FAQ and Handbook periodically.
+If anything is poorly explained, ambiguous, out of date or incorrect, let us know.
+Even better, send us a fix (AsciiDoc is not difficult to learn, but there is no objection to plain text submissions).
+. Help translate FreeBSD documentation into your native language.
+If documentation already exists for your language, you can help translate additional documents or verify that the translations are up-to-date and correct.
+First take a look at the extref:{fdp-primer}[Translations FAQ, translations] in the FreeBSD Documentation Project Primer.
+You are not committing yourself to translating every single FreeBSD document by doing this - as a volunteer, you can do as much or as little translation as you desire.
+Once someone begins translating, others almost always join the effort.
+If you only have the time or energy to translate one part of the documentation, please translate the installation instructions.
+. Read the {freebsd-questions} occasionally (or even regularly).
+It can be very satisfying to share your expertise and help people solve their problems; sometimes you may even learn something new yourself!
+These forums can also be a source of ideas for things to improve upon.
 
 [[ongoing-programmer-tasks]]
 === Ongoing Programmer Tasks
@@ -92,14 +108,21 @@ Most of the tasks listed here may require a considerable investment of time, an
 However, there are also many useful tasks which are suitable for "weekend hackers".
 
 . If you run FreeBSD-CURRENT and have a good Internet connection, there is a machine `current.FreeBSD.org` which builds a full release once a day-every now and again, try to install the latest release from it and report any failures in the process.
-. Read the {freebsd-bugs}. There may be a problem you can comment constructively on or with patches you can test. Or you could even try to fix one of the problems yourself.
+. Read the {freebsd-bugs}.
+There may be a problem you can comment constructively on or with patches you can test.
+Or you could even try to fix one of the problems yourself.
 . If you know of any bug fixes which have been successfully applied to -CURRENT but have not been merged into -STABLE after a decent interval (normally a couple of weeks), send the committer a polite reminder.
 . Move contributed software to [.filename]#src/contrib# in the source tree.
 . Make sure code in [.filename]#src/contrib# is up to date.
-. Build the source tree (or just part of it) with extra warnings enabled and clean up the warnings. A list of build warnings can also be found from our https://ci.freebsd.org[CI] by selecting a build and checking "LLVM/Clang Warnings".
+. Build the source tree (or just part of it) with extra warnings enabled and clean up the warnings.
+A list of build warnings can also be found from our https://ci.freebsd.org[CI] by selecting a build and checking "LLVM/Clang Warnings".
 . Fix warnings for ports which do deprecated things like using `gets()` or including [.filename]#malloc.h#.
 . If you have contributed any ports and you had to make FreeBSD-specific changes, send your patches back to the original authors (this will make your life easier when they bring out the next version).
-. Get copies of formal standards like POSIX(R). Compare FreeBSD's behavior to that required by the standard. If the behavior differs, particularly in subtle or obscure corners of the specification, send in a PR about it. If you are able, figure out how to fix it and include a patch in the PR. If you think the standard is wrong, ask the standards body to consider the question.
+. Get copies of formal standards like POSIX(R).
+Compare FreeBSD's behavior to that required by the standard.
+If the behavior differs, particularly in subtle or obscure corners of the specification, send in a PR about it.
+If you are able, figure out how to fix it and include a patch in the PR.
+If you think the standard is wrong, ask the standards body to consider the question.
 . Suggest further tasks for this list!
 
 === Work through the PR Database
@@ -126,7 +149,8 @@ Whether you are looking for an ongoing role, or a fun challenge for a rainy day,
 There are a number of easy ways you can contribute to keeping the ports tree up to date and in good working order:
 
 * Find some cool or useful software and extref:{porters-handbook}[create a port] for it.
-* There are a large number of ports that have no maintainer. Become a maintainer and <<adopt-port>>.
+* There are a large number of ports that have no maintainer.
+Become a maintainer and <<adopt-port>>.
 * If you have created or adopted a port, be aware of <<maintain-port>>.
 * When you are looking for a quick challenge you could <<fix-broken>>.
 
@@ -150,14 +174,20 @@ See extref:{handbook}[The FreeBSD Handbook, eresources-mail] for more informatio
 If you are submitting a simple patch to the src repo, please consider submitting it to the project's GitHub mirror as https://github.com/freebsd/freebsd-src/pulls[a pull request].
 Suitable submissions should:
 
-* It is ready or nearly ready to be committed. A committer should be able to land this patch with less than 10 minutes of additional work.
+* It is ready or nearly ready to be committed.
+A committer should be able to land this patch with less than 10 minutes of additional work.
 * It passes all the GitHub CI jobs.
 * You can respond to feedback quickly.
-* It touches fewer than about 10 files and the changes are less than about 200 lines. Changes larger than this may be OK, or you may be asked to submit multiple pull requests of a more manageable size.
-* Each logical change is a separate commit within the pull request. Commit messages for each change should follow extref:{committers-guide}#commit-log-message[commit log guide].
-* All commits have your name and valid email address as you'd like to see them in the FreeBSD repository as the author. Fake github.com addresses cannot be used.
-* The scope of the pull request should not change during review. If the review suggests changes that expand the scope, please create an independent pull request.
-* Fixup commits should be squashed with the commit they are fixing. Each commit in your branch should be suitable for FreeBSD's repository.
+* It touches fewer than about 10 files and the changes are less than about 200 lines.
+Changes larger than this may be OK, or you may be asked to submit multiple pull requests of a more manageable size.
+* Each logical change is a separate commit within the pull request.
+Commit messages for each change should follow extref:{committers-guide}#commit-log-message[commit log guide].
+* All commits have your name and valid email address as you'd like to see them in the FreeBSD repository as the author.
+Fake github.com addresses cannot be used.
+* The scope of the pull request should not change during review.
+If the review suggests changes that expand the scope, please create an independent pull request.
+* Fixup commits should be squashed with the commit they are fixing.
+Each commit in your branch should be suitable for FreeBSD's repository.
 * Commits should include one or more `Signed-off-by:` lines with full name and email address certifying https://developercertificate.org/[Developer Certificate of Origin].
 
 When updating pull request, please rebase with a forced push rather than a merge commit.
@@ -175,7 +205,7 @@ Try to fill-in each field of the bug report.
 Unless they exceed 65KB, include any patches directly in the report.
 If the patch is suitable to be applied to the source tree put `[PATCH]` in the synopsis of the report.
 When including patches, _do not_ use cut-and-paste because cut-and-paste turns tabs into spaces and makes them unusable.
-When patches are a lot larger than 20KB, consider compressing them (eg. with man:gzip[1] or man:bzip2[1]) prior to uploading them.
+When patches are a lot larger than 20KB, consider compressing them (for example with man:gzip[1] or man:bzip2[1]) prior to uploading them.
 
 After filing a report, you should receive confirmation along with a tracking number.
 Keep this tracking number so that you can update us with details about the problem.
@@ -222,7 +252,7 @@ Once you have a set of diffs (which you may test with the man:patch[1] command),
 _Do not_ just send the diffs to the {freebsd-hackers} or they will get lost! We greatly appreciate your submission (this is a volunteer project!); because we are busy, we may not be able to address it immediately, but it will remain in the PR database until we do.
 Indicate your submission by including `[PATCH]` in the synopsis of the report.
 
-If you feel it appropriate (e.g. you have added, deleted, or renamed files), bundle your changes into a `tar` file.
+If you feel it appropriate (for example you have added, deleted, or renamed files), bundle your changes into a `tar` file.
 Archives created with man:shar[1] are also welcome.
 
 If your change is of a potentially sensitive nature, such as if you are unsure of copyright issues governing its further distribution then you should send it to {core-email} directly rather than submitting as a bug report.
@@ -244,12 +274,13 @@ The complete listing can be found on the link:https://www.FreeBSD.org/internal/s
 
 === Money or Hardware
 
-We are always very happy to accept donations to further the cause of the FreeBSD Project and, in a volunteer effort like ours, a little can go a long way! Donations of hardware are also very important to expanding our list of supported peripherals since we generally lack the funds to buy such items ourselves.
+We are always very happy to accept donations to further the cause of the FreeBSD Project and, in a volunteer effort like ours, a little can go a long way!
+Donations of hardware are also very important to expanding our list of supported peripherals since we generally lack the funds to buy such items ourselves.
 
 [[donations]]
 ==== Donating Funds
 
-The https://www.freebsdfoundation.org[FreeBSD Foundation] is a non-profit, tax-exempt foundation established to further the goals of the FreeBSD Project. 
+The https://www.freebsdfoundation.org[FreeBSD Foundation] is a non-profit, tax-exempt foundation established to further the goals of the FreeBSD Project.
 As a 501(c)3 entity, the Foundation is generally exempt from US federal income tax as well as Colorado State income tax.
 Donations to a tax-exempt entity are often deductible from taxable federal income.
 
@@ -292,11 +323,11 @@ Many unmaintained ports can have pending updates, this can be seen at the https:
 
 On https://portsfallout.com/fallout?port=&maintainer=ports%40FreeBSD.org[PortsFallout] can be seen a list of unmaintained ports with errors.
 
-Some ports affect a large number of others due to dependencies and slave port relationships.
+Some ports affect a large number of others due to dependencies and secondary port relationships.
 Generally, we want people to have some experience before they maintain such ports.
 
-You can find out whether or not a port has dependencies or slave ports by looking at a master index of ports called [.filename]#INDEX#.
-(The name of the file varies by release of FreeBSD; for instance, [.filename]#INDEX-8#.) Some ports have conditional dependencies that are not included in a default [.filename]#INDEX# build.
+You can find out whether or not a port has dependencies or secondary ports by looking at a primary index of ports called [.filename]#INDEX#.
+(The name of the file varies by release of FreeBSD; for instance, [.filename]#INDEX-13#.) Some ports have conditional dependencies that are not included in a default [.filename]#INDEX# build.
 We expect you to be able to recognize such ports by looking through other ports' [.filename]#Makefile#'s.
 
 ==== How to adopt the port
@@ -338,13 +369,18 @@ As a maintainer, you will need to manage the following challenges:
 
 * *Changes affecting dependent ports.* If other ports depend on a port that you maintain, changes to your port may require coordination with other maintainers.
 
-* *Interaction with other users, maintainers and developers.* Part of being a maintainer is taking on a support role. You are not expected to provide general support (but we welcome it if you choose to do so). What you should provide is a point of coordination for FreeBSD-specific issues regarding your ports.
+* *Interaction with other users, maintainers and developers.* Part of being a maintainer is taking on a support role.
+You are not expected to provide general support (but we welcome it if you choose to do so). What you should provide is a point of coordination for FreeBSD-specific issues regarding your ports.
 
-* *Bug hunting.* A port may be affected by bugs which are specific to FreeBSD. You will need to investigate, find, and fix these bugs when they are reported. Thoroughly testing a port to identify problems before they make their way into the Ports Collection is even better.
+* *Bug hunting.* A port may be affected by bugs which are specific to FreeBSD.
+You will need to investigate, find, and fix these bugs when they are reported.
+Thoroughly testing a port to identify problems before they make their way into the Ports Collection is even better.
 
-* *Changes to ports infrastructure and policy.* Occasionally the systems that are used to build ports and packages are updated or a new recommendation affecting the infrastructure is made. You should be aware of these changes in case your ports are affected and require updating.
+* *Changes to ports infrastructure and policy.* Occasionally the systems that are used to build ports and packages are updated or a new recommendation affecting the infrastructure is made.
+You should be aware of these changes in case your ports are affected and require updating.
 
-* *Changes to the base system.* FreeBSD is under constant development. Changes to software, libraries, the kernel or even policy changes can cause flow-on change requirements to ports.
+* *Changes to the base system.* FreeBSD is under constant development.
+Changes to software, libraries, the kernel or even policy changes can cause flow-on change requirements to ports.
 
 ==== Maintainer responsibilities
 
@@ -374,11 +410,18 @@ You need to be able to generate a patch between the original port and your updat
 +
 Thoroughly review and test your changes:
 
-** Build, install and test your port on as many platforms and architectures as you can. It is common for a port to work on one branch or platform and fail on another.
-** Make sure your port's dependencies are complete. The recommended way of doing this is by installing your own ports tinderbox. See <<resources>> for more information.
-** Check that the packing list is up to date. This involves adding in any new files and directories and removing unused entries.
-** Verify your port using man:portlint[1] as a guide. See <<resources>> for important information about using portlint.
-** Consider whether changes to your port might cause any other ports to break. If this is the case, coordinate the changes with the maintainers of those ports. This is especially important if your update changes the shared library version; in this case, at the very least, the dependent ports will need to get a `PORTREVISION` bump so that they will automatically be upgraded by automated tools such as portmaster or man:portupgrade[1].
+** Build, install and test your port on as many platforms and architectures as you can.
+It is common for a port to work on one branch or platform and fail on another.
+** Make sure your port's dependencies are complete.
+The recommended way of doing this is by installing your own ports tinderbox.
+See <<resources>> for more information.
+** Check that the packing list is up to date.
+This involves adding in any new files and directories and removing unused entries.
+** Verify your port using man:portlint[1] as a guide.
+See <<resources>> for important information about using portlint.
+** Consider whether changes to your port might cause any other ports to break.
+If this is the case, coordinate the changes with the maintainers of those ports.
+This is especially important if your update changes the shared library version; in this case, at the very least, the dependent ports will need to get a `PORTREVISION` bump so that they will automatically be upgraded by automated tools such as package:ports-mgmt/poudriere[].
 
 . Submit changes
 +
@@ -403,7 +446,8 @@ A prompt response will help get your PR committed faster, and is better for main
 . And Finally
 +
 Your changes will be committed and your port will have been updated.
-The PR will then be closed by the committer. That's it!
+The PR will then be closed by the committer.
+That is it!
 ====
 
 ===== Ensure your ports continue to build correctly
@@ -446,7 +490,8 @@ If the failure was reported to you by a user, ask them to send you information w
 . Investigate and find a solution
 +
 Unfortunately there is no straightforward process to follow to do this.
-Remember, though: if you are stuck, ask for help! The {freebsd-ports} is a good place to start, and the upstream developers are often very helpful.
+Remember, though: if you are stuck, ask for help!
+The {freebsd-ports} is a good place to start, and the upstream developers are often very helpful.
 . Submit changes
 +
 Just as with updating a port, you should now incorporate changes, review and test, submit your changes in a PR, and provide feedback if required.
@@ -545,7 +590,8 @@ https://portsfallout.com/[PortsFallout] shows port issues gathered from the Free
 
 It is OK to send changes for a maintained port as well, but remember to ask the maintainer in case they are already working on the problem.
 
-Once you have found a bug or problem, collect information, investigate and fix! If there is an existing PR, follow up to that.
+Once you have found a bug or problem, collect information, investigate and fix!
+If there is an existing PR, follow up to that.
 Otherwise create a new PR.
 Your changes will be reviewed and, if everything checks out, committed.
 
@@ -553,7 +599,8 @@ Your changes will be reviewed and, if everything checks out, committed.
 === When to call it quits
 
 As your interests and commitments change, you may find that you no longer have time to continue some (or all) of your ports contributions.
-That is fine! Please let us know if you are no longer using a port or have otherwise lost time or interest in being a maintainer.
+That is fine!
+Please let us know if you are no longer using a port or have otherwise lost time or interest in being a maintainer.
 In this way we can go ahead and allow other people to try to work on existing problems with the port without waiting for your response.
 Remember, FreeBSD is a volunteer project, so if maintaining a port is no fun any more, it is probably time to let someone else do it!
 
@@ -564,10 +611,12 @@ By this, we mean that there are unresolved problems or pending updates that have
 [[resources]]
 === Resources for ports maintainers and contributors
 
-The extref:{porters-handbook}[Porter's Handbook] is your hitchhiker's guide to the ports system. Keep it handy!
+The extref:{porters-handbook}[Porter's Handbook] is your hitchhiker's guide to the ports system.
+Keep it handy!
 
 extref:{problem-reports}[Writing FreeBSD Problem Reports] describes how to best formulate and submit a PR.
-In 2005 more than eleven thousand ports PRs were submitted! Following this article will greatly assist us in reducing the time needed to handle your PRs.
+In 2005 more than eleven thousand ports PRs were submitted!
+Following this article will greatly assist us in reducing the time needed to handle your PRs.
 
 The https://bugs.freebsd.org/bugzilla/query.cgi[Problem Report database].
 
@@ -575,7 +624,7 @@ The http://portscout.FreeBSD.org[FreeBSD Ports distfile scanner (portscout)] can
 You can check on your own ports or use it to find ports that need their `MASTER_SITES` updated.
 
 package:ports-mgmt/poudriere[] is the most thorough way to test a port through the entire cycle of installation, packaging, and deinstallation.
-Documentation is located at the https://github.com/freebsd/poudriere[poudriere github repository]
+Documentation is located at the https://github.com/freebsd/poudriere[poudriere GitHub repository]
 
 man:portlint[1] is an application which can be used to verify that your port conforms to many important stylistic and functional guidelines.
 portlint is a simple heuristic application, so you should use it __only as a guide__.
@@ -591,7 +640,8 @@ https://portsfallout.com/[PortsFallout] is a place to help in searching for the
 [[ideas-contributing]]
 == Getting Started in Other Areas
 
-Looking for something interesting to get started that is not mentioned elsewhere in this article? The FreeBSD Project has several Wiki pages containing areas within which new contributors can get ideas on how to get started.
+Looking for something interesting to get started that is not mentioned elsewhere in this article?
+The FreeBSD Project has several Wiki pages containing areas within which new contributors can get ideas on how to get started.
 
 The https://wiki.freebsd.org/JuniorJobs[Junior Jobs] page has a list of projects that might be of interest to people just getting started in FreeBSD, and want to work on interesting things to get their feet wet.