From nobody Sun Mar 2 18:15:45 2025 X-Original-To: dev-commits-doc-all@mlmmj.nyi.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2610:1c1:1:606c::19:1]) by mlmmj.nyi.freebsd.org (Postfix) with ESMTP id 4Z5VVn6RHqz5pnWv for ; Sun, 02 Mar 2025 18:15:45 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from mxrelay.nyi.freebsd.org (mxrelay.nyi.freebsd.org [IPv6:2610:1c1:1:606c::19:3]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256 client-signature RSA-PSS (4096 bits) client-digest SHA256) (Client CN "mxrelay.nyi.freebsd.org", Issuer "R10" (verified OK)) by mx1.freebsd.org (Postfix) with ESMTPS id 4Z5VVn5Qxsz3JtJ; Sun, 02 Mar 2025 18:15:45 +0000 (UTC) (envelope-from git@FreeBSD.org) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1740939345; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding; bh=yi/xE2TiZE5/VsPFUuTKhUp9Oz5ge4/hP52dvB5bpKw=; b=PAsV17xiGTmSDayySqqvixy05FOa0U8NMh7gnpIkuy9nmVwlpzs1+LtwQ7CKtsEUQLIfsF yLc5erMZ11uoLCvjIbHmiT8RaNdLvAnGtmV3TuvCxcFTosZv26Qa5oCbhiAANbWhyGcB+g 6afY5I2c9W7NLZphZ5I7dmknI6GSNwqYqjTJtboM5QAHLsK5aXIce+0Za14B/wFwwgQW0B ZNxBdFECddjeUu0N8ZHEp9Noc5HWirh623j9Hb/ieqMymstAh88EApYGuHDX9/5SF7MXlt 0orAavEUBWG6ngTuLQzRJRKxnesvvFME8AIp2omSlgertJ6134MqQEReUBQ0gg== ARC-Seal: i=1; s=dkim; d=freebsd.org; t=1740939345; a=rsa-sha256; cv=none; b=soI1CUIg5zO3nCDkxW7+B5ODona25w+mUYENFPU3Je1p1y1vNDsckg7q3/PqGnKqSpJ6Cv IeY4ld1FU+e+ZKVC+jdtWtaqh1WfO/VCZ+d4OYUEYmfZ1WAGP78f6i8O7T39TCJABYC6S9 qkZZBi++8vqD4KYWZXqHvCkFTPiq0/JQlItTcB50OI3HCUr86fQuSQVE7v3ZUN+zv/OGo9 FrKT+xs2uER3VxR1WrgARKLQvOabmMe+P+eRR4w+fEWUhixlheDrJ8jWY+8rqM4emrAAXB 8AfvPSThOG5otBHK29Mg9kvCPYFBugMC2745vsPaupVRfMjkpWO/PO306YQNmg== ARC-Authentication-Results: i=1; mx1.freebsd.org; none ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1740939345; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding; bh=yi/xE2TiZE5/VsPFUuTKhUp9Oz5ge4/hP52dvB5bpKw=; b=vLjG/Uw41rdohSnN0V2y2B+WWfWsFS0/bA+j1FZx3j+xCxTd8T3grs3por7cbK9vXzUTv5 XT78lhrljePf6kUa8z+zncM8Rik3CYhLkkfhidT5jKJUPCHSgN/OxoZ83oGHGsIfHGflJn 3tJ3R0DM7+dMdV/YJ9t9PRuCzhrTsuXM+tKTQfFl58mCHj74n+oBH96KM404nc3vJKMYUy 4KCq+Yf5Er7WaOfR1plds5TN9DNCjNDpKx0sT0Q9tBUXprrJoAlLHI59epoq1ZqpI4MT7C qfxJEgjNaOu2o8H2T9alZcnyAPVkGxUwluSH3c8hVyYDWDwWM/A71DSiySSMdg== Received: from gitrepo.freebsd.org (gitrepo.freebsd.org [IPv6:2610:1c1:1:6068::e6a:5]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256) (Client did not present a certificate) by mxrelay.nyi.freebsd.org (Postfix) with ESMTPS id 4Z5VVn4tfYz1BfN; Sun, 02 Mar 2025 18:15:45 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from gitrepo.freebsd.org ([127.0.1.44]) by gitrepo.freebsd.org (8.18.1/8.18.1) with ESMTP id 522IFjEk045066; Sun, 2 Mar 2025 18:15:45 GMT (envelope-from git@gitrepo.freebsd.org) Received: (from git@localhost) by gitrepo.freebsd.org (8.18.1/8.18.1/Submit) id 522IFjXw045063; Sun, 2 Mar 2025 18:15:45 GMT (envelope-from git) Date: Sun, 2 Mar 2025 18:15:45 GMT Message-Id: <202503021815.522IFjXw045063@gitrepo.freebsd.org> To: doc-committers@FreeBSD.org, dev-commits-doc-all@FreeBSD.org From: "Danilo G. Baio" Subject: git: 7cad8b831f - main - fdp-primer: Add Managing Contributor Lists section List-Id: Commit messages for all branches of the doc repository List-Archive: https://lists.freebsd.org/archives/dev-commits-doc-all List-Help: List-Post: List-Subscribe: List-Unsubscribe: X-BeenThere: dev-commits-doc-all@freebsd.org Sender: owner-dev-commits-doc-all@FreeBSD.org MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit X-Git-Committer: dbaio X-Git-Repository: doc X-Git-Refname: refs/heads/main X-Git-Reftype: branch X-Git-Commit: 7cad8b831fc4b45a526170b6a4ef3557b69f20de Auto-Submitted: auto-generated The branch main has been updated by dbaio: URL: https://cgit.FreeBSD.org/doc/commit/?id=7cad8b831fc4b45a526170b6a4ef3557b69f20de commit 7cad8b831fc4b45a526170b6a4ef3557b69f20de Author: Jim Brown AuthorDate: 2025-03-02 17:27:20 +0000 Commit: Danilo G. Baio 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}> + +[..] +.... +