Merge branch 'freebsd:main' into patch-11

documentation/content/en/articles/building-products/_index.adoc

@@ -63,7 +63,7 @@ FreeBSD today is well-known as a high-performance server operating system.
 It is deployed on millions of web servers and internet-facing hosts worldwide.
 FreeBSD code also forms an integral part of many products, ranging from appliances such as network routers, firewalls, and storage devices, to personal computers.
 Portions of FreeBSD have also been used in commercial shrink-wrapped software
-(see crossref:building-products[freebsd-intro]).
+(see crossref:building-products[freebsd-intro, FreeBSD as a set of building blocks]).
 
 In this article we look at the link:https://www.FreeBSD.org/[FreeBSD project] as a software engineering resource-as a collection of building blocks and processes which you can use to build products.
 
@@ -96,24 +96,24 @@ After reading this article you should have:
 
 The rest of the article is structured as follows:
 
-* crossref:building-products[freebsd-intro] introduces the FreeBSD project, explores its organizational structure, key technologies and release engineering processes.
-* crossref:building-products[freebsd-collaboration] describes ways to collaborate with the FreeBSD project. It examines common pitfalls encountered by corporates working with voluntary projects like FreeBSD.
-* crossref:building-products[conclusion] concludes.
+* crossref:building-products[freebsd-intro, FreeBSD as a set of building blocks] introduces the FreeBSD project, explores its organizational structure, key technologies and release engineering processes.
+* crossref:building-products[freebsd-collaboration, Collaborating with FreeBSD] describes ways to collaborate with the FreeBSD project. It examines common pitfalls encountered by corporates working with voluntary projects like FreeBSD.
+* crossref:building-products[conclusion, Conclusion] concludes.
 
 [[freebsd-intro]]
 == FreeBSD as a set of building blocks
 
 FreeBSD makes an excellent foundation on which to build products:
 
 * FreeBSD source code is distributed under a liberal BSD license facilitating
-  its adoption in commercial products crossref:building-products[Mon2005] with minimum hassle.
+  its adoption in commercial products crossref:building-products[Mon2005,"Why you should use a BSD style license for your Open Source Project"] with minimum hassle.
 * The FreeBSD project has excellent engineering practices that can be leveraged.
 * The project offers exceptional transparency into its workings, allowing organizations using its code to plan effectively for the future.
 * The culture of the FreeBSD project, carried over from the Computer Science
   Research Group at The University of California, Berkeley
-  crossref:building-products[McKu1999-1], fosters high-quality work. Some features in FreeBSD define the state of the art.
+  crossref:building-products[McKu1999-1,"Twenty Years of Berkeley Unix: From AT&T-Owned to Freely Redistributable"], fosters high-quality work. Some features in FreeBSD define the state of the art.
 
-crossref:building-products[GoldGab2005] examines the business reasons for using open-source in greater detail.
+crossref:building-products[GoldGab2005,"Innovation Happens Elsewhere: Open Source as Business Strategy"] examines the business reasons for using open-source in greater detail.
 For organizations, the benefits of using FreeBSD components in their products include a shorter time to market, lower development costs and lower development risks. 
 
 === Building with FreeBSD
@@ -163,7 +163,7 @@ FreeBSD's in-kernel Netgraph (man:netgraph[4]) framework allows kernel networkin
 +
 FreeBSD supports a number of filesystems, and its native UFS2 filesystem
 supports soft updates, snapshots and very large filesystem sizes (16TB per
-		filesystem) crossref:building-products[McKu1999].
+		filesystem) crossref:building-products[McKu1999,"Soft Updates: A Technique for Eliminating Most Synchronous Writes in the Fast Filesystem"].
 +
 FreeBSD's in-kernel GEOM (man:geom[4]) framework allows kernel storage modules to be composed in flexible ways.
 * Over {numports} ported applications, both commercial and open-source, managed via the FreeBSD ports collection.
@@ -186,10 +186,10 @@ Conflict resolution is performed by a nine member "Core Team" that is elected fr
 FreeBSD does not have "corporate" committers.
 Individual committers are required to take responsibility for the changes they introduce to the code.
 The extref:{committers-guide}[FreeBSD Committer's guide]
-crossref:building-products[ComGuide] documents the rules and responsibilities for committers.
+crossref:building-products[ComGuide,"Committer's Guide"] documents the rules and responsibilities for committers.
 
 FreeBSD's project model is examined in detail in
-crossref:building-products[Nik2005].
+crossref:building-products[Nik2005,"A project model for the FreeBSD Project"].
 
 === FreeBSD Release Engineering Processes
 
@@ -214,7 +214,7 @@ The release engineering team publishes a link:https://www.FreeBSD.org/releng/[ro
 The dates laid down in the road map are not deadlines; FreeBSD is released when its code and documentation are ready.
 
 FreeBSD's release engineering processes are described in
-crossref:building-products[RelEngDoc].
+crossref:building-products[RelEngDoc,"FreeBSD Release Engineering"].
 
 [[freebsd-collaboration]]
 == Collaborating with FreeBSD
@@ -227,7 +227,8 @@ Using open-source code is best viewed not as a one-off activity, but as an __ong
 The best projects to collaborate with are the ones that are __live__; i.e., with an active community, clear goals and a transparent working style.
 
 * FreeBSD has an active developer community around it. At the time of writing there are many thousands of contributors from every populated continent in the world and over 300 individuals with write access to the project's source repositories.
-* The goals of the FreeBSD project are crossref:building-products[Hub1994]:
+* The goals of the FreeBSD project are
+  crossref:building-products[Hub1994,"Contributing to the FreeBSD Project"]:
 
 ** To develop a high-quality operating system for popular computer hardware, and,
 ** To make our work available to all under a liberal license.
@@ -246,11 +247,11 @@ A common mistake that companies make when venturing into the open-source world i
 monetary rewards entering the picture. The factors that motivate individuals are
 complex, ranging from altruism, to an interest in solving the kinds of problems
 that FreeBSD attempts to solve. In this environment, "elegance is never
-optional"crossref:building-products[Nor1993].
+optional"crossref:building-products[Nor1993,"Tutorial on Good Lisp Programming Style"].
 
 *The Long Term View.* FreeBSD traces its roots back nearly twenty years to the work of the Computer Science Research Group at the University of California Berkeley.footnote:[FreeBSD's source repository contains a history of the project since its inception, and there are CDROMs available that contain earlier code from the CSRG.] A number of the original CSRG developers remain associated with the project.
 
-The project values long-term perspectives crossref:building-products[Nor2001]. A frequent acronym encountered in the project is DTRT, which stands for "Do The Right Thing".
+The project values long-term perspectives crossref:building-products[Nor2001,"Teach Yourself Programming in Ten Years"]. A frequent acronym encountered in the project is DTRT, which stands for "Do The Right Thing".
 
 *Development Processes.* Computer programs are tools for communication: at one level programmers communicate their intentions using a precise notation to a tool (a compiler) that translates their instructions to executable code.
 At another level, the same notation is used for communication of intent between two programmers.
@@ -259,7 +260,7 @@ Formal specifications and design documents are seldom used in the project.
 Clear and well-written code and well-written change logs
 (crossref:building-products[fig-change-log, A sample change log entry]) are used in their place.
 FreeBSD development happens by "rough consensus and running
-code"crossref:building-products[Carp1996].
+code"crossref:building-products[Carp1996,"The Architectural Principles of the Internet"].
 
 [.programlisting]
 ....
@@ -297,10 +298,8 @@ For example:
 +
 *Track FreeBSD source code.* The project makes it easy to mirror its SVN repository using extref:{committers-guide}[svnsync, svn-advanced-use-setting-up-svnsync]. Having the complete history of the source is useful when debugging complex problems and offers valuable insight into the intentions of the original developers. Use a capable source control system that allows you to easily merge changes between the upstream FreeBSD code base and your own in-house code.
 +
-crossref:building-products[fig-svn-blame, An annotated source listing generated
-using `svn blame`] shows a portion of an annotated listing of the file
-referenced by the change log in crossref:building-products[fig-change-log, A
-sample change log entry].
+crossref:building-products[fig-svn-blame, An annotated source listing generated using `svn blame`] shows a portion of an annotated listing of the file
+referenced by the change log in crossref:building-products[fig-change-log, A sample change log entry].
 The ancestry of each line of the source is clearly visible.
 Annotated listings showing the history of every file that is part of FreeBSD are https://svnweb.freebsd.org/[available on the web].
 +
@@ -345,7 +344,7 @@ The http://www.bsdcertification.org/[BSD Certification Group] offers certificati
 +
 For less critical needs, you can ask for help on the link:https://lists.freebsd.org/[project mailing lists].
 A useful guide to follow when asking for help is given in
-crossref:building-products[Ray2004].
+crossref:building-products[Ray2004,"How to ask questions the smart way"].
 Publicize your involvement::
 You are not required to publicize your use of FreeBSD, but doing so helps both your effort as well as that of the project.
 +

documentation/content/en/articles/committers-guide/_index.adoc

@@ -49,7 +49,7 @@ All new committers should read this document before they start, and existing com
 Almost all FreeBSD developers have commit rights to one or more repositories.
 However, a few developers do not, and some of the information here applies to them as well.
 (For instance, some people only have rights to work with the Problem Report database.)
-Please see crossref:committers-guide[non-committers] for more information.
+Please see crossref:committers-guide[non-committers, Issues Specific to Developers Who Are Not Committers] for more information.
 
 This document may also be of interest to members of the FreeBSD community who want to learn more about how the project works.
 
@@ -74,7 +74,7 @@ toc::[]
 |`ref*.FreeBSD.org`, `universe*.freeBSD.org` (see also link:https://www.FreeBSD.org/internal/machines/[FreeBSD Project Hosts])
 
 |_SMTP Host_
-|`smtp.FreeBSD.org:587` (see also crossref:committers-guide[smtp-setup]).
+|`smtp.FreeBSD.org:587` (see also crossref:committers-guide[smtp-setup, SMTP Access Setup]).
 
 |`_src/_` Git Repository
 |`ssh://git@gitrepo.FreeBSD.org/src.git`
@@ -99,7 +99,7 @@ toc::[]
 |===
 
 man:ssh[1] is required to connect to the project hosts. For more information,
-	see crossref:committers-guide[ssh.guide].
+	see crossref:committers-guide[ssh.guide, SSH Quick-Start Guide].
 
 Useful links:
 
@@ -112,7 +112,7 @@ Useful links:
 
 Cryptographic keys conforming to the OpenPGP (__Pretty Good Privacy__) standard are used by the FreeBSD project to authenticate committers.
 Messages carrying important information like public SSH keys can be signed with the OpenPGP key to prove that they are really from the committer.
-See https://nostarch.com/releases/pgp_release.pdf[PGP & GPG: Email for the Practical Paranoid by Michael Lucas] and http://en.wikipedia.org/wiki/Pretty_Good_Privacy[] for more information.
+See https://nostarch.com/releases/pgp_release.pdf[PGP & GPG: Email for the Practical Paranoid by Michael Lucas] and https://en.wikipedia.org/wiki/Pretty_Good_Privacy[] for more information.
 
 [[pgpkeys-creating]]
 === Creating a Key
@@ -1518,7 +1518,7 @@ Note: merging vendor branch commits will not work with this technique.
 
 ===== Finding the Subversion Revision
 
-You'll need to make sure that you've fetched the notes (see the crossref:committers-guide[git-mini-daily-use]for details).
+You'll need to make sure that you've fetched the notes (see the crossref:committers-guide[git-mini-daily-use, Daily use]for details).
 Once you have these, notes will show up in the git log command like so:
 
 [source,shell]
@@ -2179,7 +2179,7 @@ It is very important to have a current PGP/GnuPG key in the repository. The key
 Add an entry for each additional mentor/mentee relationship in the bottom section.
 . Generate a Kerberos Password
 +
-See crossref:committers-guide[kerberos-ldap] to generate or set a Kerberos account for use with other FreeBSD services like the link:https://bugs.freebsd.org/bugzilla/[bug-tracking database] (you get a bug-tracking account as part of that step).
+See crossref:committers-guide[kerberos-ldap, Kerberos and LDAP web Password for FreeBSD Cluster] to generate or set a Kerberos account for use with other FreeBSD services like the link:https://bugs.freebsd.org/bugzilla/[bug-tracking database] (you get a bug-tracking account as part of that step).
 . Optional: Enable Wiki Account
 +
 link:https://wiki.freebsd.org[FreeBSD Wiki] Account - A wiki account allows sharing projects and ideas.
@@ -2229,7 +2229,7 @@ For those willing to send e-mail messages through the FreeBSD.org infrastructure
 . Enable STARTTLS.
 . Ensure your `From:` address is set to `_yourusername_@FreeBSD.org`.
 . For authentication, you can use your FreeBSD Kerberos username and password
-  (see crossref:committers-guide[kerberos-ldap]). The `_yourusername_/mail` principal is preferred, as it is only valid for authenticating to mail resources.
+  (see crossref:committers-guide[kerberos-ldap, Kerberos and LDAP web Password for FreeBSD Cluster]). The `_yourusername_/mail` principal is preferred, as it is only valid for authenticating to mail resources.
 +
 [NOTE]
 ======
@@ -2380,7 +2380,7 @@ Document that approval with an `Approved by:` line in the commit message.
 When the mentor decides that a mentee has learned the ropes and is ready to commit on their own, the mentor announces it with a commit to [.filename]#mentors#.
 This file is in the [.filename]#admin# orphan branch of each repository.
 Detailed information on how to access these branches can be found in
-crossref:committers-guide[admin-branch].
+crossref:committers-guide[admin-branch, "admin" branch].
 
 [[pre-commit-review]]
 == Pre-Commit Review
@@ -2931,7 +2931,7 @@ Committers with non-``FreeBSD.org`` Bugzilla accounts can have the old account m
 . Log in using your old account.
 . Open new bug. Choose `Services` as the Product, and `Bug Tracker` as the Component. In bug description list accounts you wish to be merged.
 . Log in using `FreeBSD.org` account and post comment to newly opened bug to
-  confirm ownership. See crossref:committers-guide[kerberos-ldap] for more details on how to generate or set a password for your `FreeBSD.org` account.
+  confirm ownership. See crossref:committers-guide[kerberos-ldap, Kerberos and LDAP web Password for FreeBSD Cluster] for more details on how to generate or set a password for your `FreeBSD.org` account.
 . If there are more than two accounts to merge, post comments from each of them.
 ====
 
@@ -2952,7 +2952,7 @@ Committers with non-``FreeBSD.org`` Phabricator accounts can have the old accoun
 ====
 . Change your Phabricator account email to your `FreeBSD.org` email.
 . Open new bug on our bug tracker using your `FreeBSD.org` account, see
-  crossref:committers-guide[bugzilla] for more information. Choose `Services` as the Product, and `Code Review` as the Component. In bug description request that your Phabricator account be renamed, and provide a link to your Phabricator user. For example, `https://reviews.freebsd.org/p/bob_example.com/`
+  crossref:committers-guide[bugzilla, Bugzilla] for more information. Choose `Services` as the Product, and `Code Review` as the Component. In bug description request that your Phabricator account be renamed, and provide a link to your Phabricator user. For example, `https://reviews.freebsd.org/p/bob_example.com/`
 ====
 
 [IMPORTANT]
@@ -3578,7 +3578,7 @@ During that time, build problems were fixed, and the release packages were built
 This practice is no longer used, as the packages for the releases are built from the current stable, quarterly branch.
 
 For more information on how to merge commits to the quarterly branch, see
-crossref:committers-guide[ports-qa-misc-request-mfh].
+crossref:committers-guide[ports-qa-misc-request-mfh, What is the procedure to request authorization for merging a commit to the quarterly branch?].
 
 [[ports-qa-quarterly]]
 === Quarterly Branches
@@ -3727,16 +3727,16 @@ A few people who have access to the FreeBSD machines do not have commit bits.
 Almost all of this document will apply to these developers as well (except things specific to commits and the mailing list memberships that go with them).
 In particular, we recommend that you read:
 
-* crossref:committers-guide[admin]
-* crossref:committers-guide[conventions-everyone]
+* crossref:committers-guide[admin, Administrative Details]
+* crossref:committers-guide[conventions-everyone, For Everyone]
 +
 [NOTE]
 ====
 Get your mentor to add you to the "Additional Contributors" ([.filename]#doc/shared/contrib-additional.adoc#), if you are not already listed there.
 ====
-* crossref:committers-guide[developer.relations]
-* crossref:committers-guide[ssh.guide]
-* crossref:committers-guide[rules]
+* crossref:committers-guide[developer.relations, Developer Relations]
+* crossref:committers-guide[ssh.guide, SSH Quick-Start Guide]
+* crossref:committers-guide[rules, The FreeBSD Committers' Big List of Rules]
 
 [[google-analytics]]
 == Information About Google Analytics

documentation/content/en/articles/committers-guide/_index.po

@@ -246,7 +246,7 @@ msgid ""
 "Messages carrying important information like public SSH keys can be signed "
 "with the OpenPGP key to prove that they are really from the committer.  See "
 "https://nostarch.com/releases/pgp_release.pdf[PGP & GPG: Email for the "
-"Practical Paranoid by Michael Lucas] and http://en.wikipedia.org/wiki/"
+"Practical Paranoid by Michael Lucas] and https://en.wikipedia.org/wiki/"
 "Pretty_Good_Privacy[] for more information."
 msgstr ""