git: 7cad8b831f - main - fdp-primer: Add Managing Contributor Lists section
- Go to: [ bottom of page ] [ top of archives ] [ this month ]
Date: Sun, 02 Mar 2025 18:15:45 UTC
The branch main has been updated by dbaio:
URL: https://cgit.FreeBSD.org/doc/commit/?id=7cad8b831fc4b45a526170b6a4ef3557b69f20de
commit 7cad8b831fc4b45a526170b6a4ef3557b69f20de
Author: Jim Brown <jpb@jimby.name>
AuthorDate: 2025-03-02 17:27:20 +0000
Commit: Danilo G. Baio <dbaio@FreeBSD.org>
CommitDate: 2025-03-02 18:11:00 +0000
fdp-primer: Add Managing Contributor Lists section
Reviewed by: dbaio
Differential Revision: https://reviews.freebsd.org/D49185
---
.../en/books/fdp-primer/structure/_index.adoc | 112 ++++++++++++++++++++-
1 file changed, 109 insertions(+), 3 deletions(-)
diff --git a/documentation/content/en/books/fdp-primer/structure/_index.adoc b/documentation/content/en/books/fdp-primer/structure/_index.adoc
index 76bb7b2d63..864ad53d7e 100644
--- a/documentation/content/en/books/fdp-primer/structure/_index.adoc
+++ b/documentation/content/en/books/fdp-primer/structure/_index.adoc
@@ -82,7 +82,7 @@ This directory is shared between `documentation` and the `website`.
| *website*
| Contains the link:https://www.FreeBSD.org[FreeBSD website] in AsciiDoc format.
-Contains subdirectories to further categorize the information by languages.
+Contains subdirectories to further categorize the information by languages.
|===
[[structure-locale]]
@@ -108,7 +108,7 @@ For more information take a look link:https://gohugo.io/getting-started/configur
| *content*
| Contain the books, articles and webpages.
-One directory exists for each available translation of the documentation, for example `en` and `zh-tw`.
+One directory exists for each available translation of the documentation, for example `en` and `zh-tw`.
| *data*
| Contain custom data for build the website in link:https://en.wikipedia.org/wiki/TOML[TOML] format.
@@ -129,7 +129,7 @@ For more information take a look link:https://gohugo.io/templates/[here].
For example to generate the Table of Contents of the books, etc.
| *beastie.png*
-| This image doesn't need an introduction ;)
+| This image does not need an introduction ;)
| *LICENSE*
| License of the documentation, shared and website. BSD 2-Clause License.
@@ -258,3 +258,109 @@ toc::[]
[[intro]]
== Introduction
....
+
+== Managing Contributor Lists
+
+The FreeBSD project recognizes contributors in several different lists in the documentation and in printed materials.
+This section describes how the documentation team manages changes to these lists.
+
+=== Finding the Correct Files
+
+extref:{contributors}[Contributors] to FreeBSD are maintained in article format.
+The source file for managing the *Contributors* article file is located at:
+
+[subs=+quotes]
+----
+doc
+ /documentation
+ /content
+ /{language}
+ /articles
+ /contributors
+ [.filename]#_index.adoc# – Contains a list of include files that apply to each section.
+ [.filename]#_index.po# – Translation page
+ [.filename]#contrib-develinmemoriam.adoc# - content of “In Memoriam” section
+ [.filename]#contrib-develinmemoriam.po# – Translation page
+----
+
+Copies of this contributors directory may exist in other content language directories.
+
+Note that the file [.filename]#contrib-develinmemoriam.adoc# is also found in this directory.
+See below for additional information.
+
+The [.filename]#contributors/_index.adoc# file is designed as a collection of include files.
+The include files are listed in the Hugo specific section of the source file.
+The section is divided into several parts with "ifdef::" statements.
+There is a sub-section for website output and one for non-website (including PDF) output.
+
+The text for each section of the *Contributors* page contains an "include::" statement.
+For example, the entry for "Port Manager Alumni" is `include::{include-contrib-portmgralumni}[]`.
+This pulls in the text for port manager alumni into the rendered output.
+
+To make a change, edit the appropriate include file:
+
+[subs=+quotes]
+----
+include-contrib-committers: [.filename]#~/doc/shared/contrib-committers.adoc#
+include-contrib-corealumni: [.filename]#~/doc/shared/contrib-corealumni.adoc#
+include-contrib-develalumni: [.filename]#~/doc/shared/contrib-develalumni.adoc#
+include-contrib-portmgralumni: [.filename]#~/doc/shared/contrib-portmgralumni.adoc#
+include-contrib-additional: [.filename]#~/doc/shared/contrib-additional.adoc#
+include-contrib-386bsd: [.filename]#~/doc/shared/contrib-386bsd.adoc#
+
+Also, edit the [.filename]#authors.adoc# file: [.filename]#~/doc/shared/authors.adoc#
+and any related translations.
+
+----
+
+In general, if a person is being added, there is only one edit necessary, and they can be added to the appropriate include file.
+If a person is being moved from "current" to "alumni" status, two edits are required - one to remove and one to insert for the appropriate files.
+The order of entries for all files is found in the table below.
+
+[cols="25%,25%,25%,25%", frame="none", options="header"]
+|===
+| Purpose | Section Anchor | File in ~/doc/shared/ | Order Specification
+| *FreeBSD Developers* | include-contrib-committers | [.filename]#contrib-committers.adoc# | alphabetical order by last name
+| *Core Team Alumni* | include-contrib-corealumni | [.filename]#contrib-corealumni.adoc# | rough reverse chronological order
+| *Development Team Alumni* | include-contrib-develalumni | [.filename]#contrib-develalumni.adoc# | rough reverse chronological order
+| *Ports Management Team Alumni* | include-contrib-portmgralumni | [.filename]#contrib-portmgralumni.adoc# | rough reverse chronological order
+| *Additional FreeBSD Contributors* | include-contrib-additional | [.filename]#contrib-additional.adoc# | alphabetical order by first name
+| *386BSD Patch Kit Patch Contributors* | include-contrib-386bsd | [.filename]#contrib-386bsd.adoc# | alphabetical order by first name
+| *Contributors to the central server project* | No include file used | [.filename]#contributors/_index.adoc# | unordered
+| *Direct funding* | No include file used | [.filename]#contributors/_index.adoc# | unordered
+| *Hardware contributors* | No include file used | [.filename]#contributors/_index.adoc# | unordered
+| *Special contributors* | No include file used | [.filename]#contributors/_index.adoc# | unordered
+|===
+
+=== "In Memoriam" Section
+
+If the intent is to notify the BSD community of the death of a community member, the following procedures should be used:
+
+. Search the files above for the name, email address, and nickname (such as `foobsd`).
+. Since the member is deceased (which should be double checked) remove the name from the appropriate file and add them to the "In Memoriam" file ([.filename]#contrib-develinmemoriam.adoc# as noted above) by editing the appropriate files.
+Try to find some additional information about their contributions to FreeBSD over the years and add it with their entry in the file.
+This may require asking in the development mailing lists, contacting colleagues, contacting the FreeBSD Foundation, or searching through the commit logs.
+. Where an email address is found with a name, remove the email address, but leave the name.
++
+[cols="25%,25%,25%,25%", frame="none", options="header"]
+|===
+| Purpose | Section Anchor | File in ~/doc/documentation/content/{language}/articles/contributors/ | Order Specification
+| *Development Team: In Memoriam* | [.filename]#contrib-develinmemoriam.adoc# | [.filename]#contrib-develinmemoriam.adoc# | rough reverse chronological order
+|===
++
+. In the [.filename]#~/doc/shared/authors.adoc# file, comment out (using one backslash '\') the email address to avoid creating the email link "mailto:"
+See the example for `itojun` below:
++
+[source.programlisting,asciidoc]
+....
+[shared/authors.adoc]
+
+[..]
+
+:itojun-name: Jun-ichiro Itoh
+:itojun-email: \itojun@FreeBSD.org
+:itojun: {itojun-name} <{itojun-email}>
+
+[..]
+....
+