From nobody Tue Jan 03 23:15:00 2023 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 4NmpVF0jwFz2p6Tm for ; Tue, 3 Jan 2023 23:15:01 +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 "R3" (verified OK)) by mx1.freebsd.org (Postfix) with ESMTPS id 4NmpVF0GRsz3Mpd; Tue, 3 Jan 2023 23:15:01 +0000 (UTC) (envelope-from git@FreeBSD.org) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1672787701; 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=zKIUTRCdHPy4GjHB9NgY8ogpBF2cTWKnBIVlUtlPNm8=; b=fhL1EHfsORAEqaA1OQc7x0aWTDBR07sWI37JkGyn/bsFirmG6W5KjPxcTGiEYD3K6msqD9 LV5wYJgtk80R0wILw+RnVTH0Vxxw8iWZol85i3RyxA6Egu2Vmx1w0/06Sv2mzyYJD1PMFr jsOvAfNZquDLP6sLwiEna7/drv3jZ0FO09G6Y7h0iX70Ejg7ErWSYq73AaJ3xHYvLIH20F yWnF0h8AJDNeDxg7r1lLbyqzy2GgpitKigcDgqMLM4s3nxlANkOKsLmZfy/72eq7w7uxZl uYlKu7j9bxLRbVgHUY5ICD2syXdBxui+cQuU251oJmpQNOQk/e2TpxyB4sgjrA== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1672787701; 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=zKIUTRCdHPy4GjHB9NgY8ogpBF2cTWKnBIVlUtlPNm8=; b=LEcpRRASjPKab+PbSmwgXDxpS0yM2gp8pIOuti56SHA0iXAZ5ewc6srs/6+3ldyGq3SbAM XlBU5OnJ8qngOkAMKylwKAillGCKUCrDXjOmKZaJzVyguULmT+pTB56oAXRyiLnN8eBk5S P7oRRwaHA7YonHgasFRZlLFqi46odUHskxoFqPbOOvtptnK3JYpa60LK7DH+rzWwxvOAOJ aCY74yI27e6eBnH88VXl7MQFtmA9/2W9EqKzzNGIQP2tqk0+1L7rAPAkLKSeTssWnqVKjD w3aLL0KvT2Y4LZ8aqrGPjPixmdSYEvNUIQ/1w01EJYPiAhz6YiHR/48aVmEnDg== ARC-Authentication-Results: i=1; mx1.freebsd.org; none ARC-Seal: i=1; s=dkim; d=freebsd.org; t=1672787701; a=rsa-sha256; cv=none; b=GPceEQkJ6gbaz5bVv1Y225VJ+26cFgdPktmNjZiMaWm/7g8/E26z6PRRki4sjnXx9ckc/Q ZzDbwK5upis7PmZttJE5DV1tlWYGMB1rovy/ko0p4LIx66aD3OrmF87HoyVi/E51Egvh9F 01fIKeot6PL5SsexwSFNqFVxsvfc8YriUhARkz6w5k7koQBgWh8BoUxvU9p0aQMKhm5zxl kx58gE+hTwbegNwjZmKAeLWKDIRN1N5R7tCkJ/+cjFgs0E0arEhSG2L3QAoop+ztvXj86P XYUi8kY4SyXn411J7fQPL9YYcMKyAM5GABHDLPto8j2nT5Ucy8D0DellgsPjhg== 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 4NmpVD6TNMzpxp; Tue, 3 Jan 2023 23:15:00 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from gitrepo.freebsd.org ([127.0.1.44]) by gitrepo.freebsd.org (8.16.1/8.16.1) with ESMTP id 303NF03I076816; Tue, 3 Jan 2023 23:15:00 GMT (envelope-from git@gitrepo.freebsd.org) Received: (from git@localhost) by gitrepo.freebsd.org (8.16.1/8.16.1/Submit) id 303NF08V076815; Tue, 3 Jan 2023 23:15:00 GMT (envelope-from git) Date: Tue, 3 Jan 2023 23:15:00 GMT Message-Id: <202301032315.303NF08V076815@gitrepo.freebsd.org> To: doc-committers@FreeBSD.org, dev-commits-doc-all@FreeBSD.org From: Pau Amma Subject: git: 63894dffe8 - main - Miscellaneous small changes to the Committer's Guide. 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: Sender: owner-dev-commits-doc-all@freebsd.org X-BeenThere: dev-commits-doc-all@freebsd.org MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit X-Git-Committer: pauamma X-Git-Repository: doc X-Git-Refname: refs/heads/main X-Git-Reftype: branch X-Git-Commit: 63894dffe8ed65c9dc705959bc07c8a62991007d Auto-Submitted: auto-generated X-ThisMailContainsUnwantedMimeParts: N The branch main has been updated by pauamma: URL: https://cgit.FreeBSD.org/doc/commit/?id=63894dffe8ed65c9dc705959bc07c8a62991007d commit 63894dffe8ed65c9dc705959bc07c8a62991007d Author: Pau Amma AuthorDate: 2022-10-22 18:16:57 +0000 Commit: Pau Amma CommitDate: 2023-01-03 23:11:37 +0000 Miscellaneous small changes to the Committer's Guide. PR below plus a few more I spotted while working on it. While there, check nearby URLs still work and use https:. PR: https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=261812 Reviewed by: carlavlla, gjb, philip Approved by: carlavilla (mentor), gjb (mentor, earlier version) Differential Revision: https://reviews.freebsd.org/D37091 --- .../en/articles/committers-guide/_index.adoc | 48 +++++++++++++--------- 1 file changed, 28 insertions(+), 20 deletions(-) diff --git a/documentation/content/en/articles/committers-guide/_index.adoc b/documentation/content/en/articles/committers-guide/_index.adoc index 1a2762cd11..dd67ca83f7 100644 --- a/documentation/content/en/articles/committers-guide/_index.adoc +++ b/documentation/content/en/articles/committers-guide/_index.adoc @@ -2,7 +2,7 @@ title: Committer's Guide authors: - author: The FreeBSD Documentation Project -copyright: 1999-2021 The FreeBSD Documentation Project +copyright: 1999-2022 The FreeBSD Documentation Project description: Introductory information for FreeBSD committers trademarks: ["freebsd", "coverity", "ibm", "intel", "general"] weight: 25 @@ -48,7 +48,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). +(For instance, some people only have rights to work with the Problem Report database.) Please see <> 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. @@ -77,19 +77,19 @@ toc::[] |`smtp.FreeBSD.org:587` (see also <>). |`_src/_` Git Repository -|`ssh://git@gitrepo.FreeBSD.org/src.git` (see also <>). +|`ssh://git@gitrepo.FreeBSD.org/src.git` |`_doc/_` Git Repository -|`ssh://git@gitrepo.FreeBSD.org/doc.git` (see also <>). +|`ssh://git@gitrepo.FreeBSD.org/doc.git` |`_ports/_` Git Repository -|`ssh://git@gitrepo.FreeBSD.org/ports.git` (see also <>). +|`ssh://git@gitrepo.FreeBSD.org/ports.git` |_Internal Mailing Lists_ -|developers (technically called all-developers), doc-developers, doc-committers, ports-developers, ports-committers, src-developers, src-committers. (Each project repository has its own -developers and -committers mailing lists. Archives for these lists can be found in the files [.filename]#/local/mail/repository-name-developers-archive# and [.filename]#/local/mail/repository-name-committers-archive# on the `FreeBSD.org` cluster.) +|developers (technically called all-developers), doc-developers, doc-committers, ports-developers, ports-committers, src-developers, src-committers. (Each project repository has its own -developers and -committers mailing lists. Archives for these lists can be found in the files [.filename]#/local/mail/repository-name-developers-archive# and [.filename]#/local/mail/repository-name-committers-archive# on `freefall.FreeBSD.org`.) |_Core Team monthly reports_ -|[.filename]#/home/core/public/monthly-reports# on the `FreeBSD.org` cluster. +|[.filename]#/home/core/public/reports# on the `FreeBSD.org` cluster. |_Ports Management Team monthly reports_ |[.filename]#/home/portmgr/public/monthly-reports# on the `FreeBSD.org` cluster. @@ -177,7 +177,7 @@ Change (N)ame, (C)omment, (E)mail or (O)kay/(Q)uit? o You need a Passphrase to protect your secret key. .... -<.> 2048-bit keys with a three-year expiration provide adequate protection at present (2013-12). http://danielpocock.com/rsa-key-sizes-2048-or-4096-bits[] describes the situation in more detail. +<.> 2048-bit keys with a three-year expiration provide adequate protection at present (2022-10). <.> A three year key lifespan is short enough to obsolete keys weakened by advancing computer power, but long enough to reduce key management problems. @@ -185,7 +185,7 @@ You need a Passphrase to protect your secret key. + After the email address is entered, a passphrase is requested. Methods of creating a secure passphrase are contentious. -Rather than suggest a single way, here are some links to sites that describe various methods: http://world.std.com/~reinhold/diceware.html[], http://www.iusmentis.com/security/passphrasefaq/[], http://xkcd.com/936/[], http://en.wikipedia.org/wiki/Passphrase[]. +Rather than suggest a single way, here are some links to sites that describe various methods: https://world.std.com/~reinhold/diceware.html[], https://www.iusmentis.com/security/passphrasefaq/[], https://xkcd.com/936/[], https://en.wikipedia.org/wiki/Passphrase[]. ==== Protect the private key and passphrase. @@ -266,7 +266,7 @@ Committers are encouraged to seek review for their work as part of the normal de === Policy for Committer Activity in Other Trees * All committers may modify [.filename]#src/share/misc/committers-*.dot#, [.filename]#src/usr.bin/calendar/calendars/calendar.freebsd#, and [.filename]#ports/astro/xearth/files#. -* doc committers may commit documentation changes to [.filename]#src# files, such as man pages, READMEs, fortune databases, calendar files, and comment fixes without approval from a src committer, subject to the normal care and tending of commits. +* doc committers may commit documentation changes to [.filename]#src# files, such as manual pages, READMEs, fortune databases, calendar files, and comment fixes without approval from a src committer, subject to the normal care and tending of commits. * Any committer may make changes to any other tree with an "Approved by" from a non-mentored committer with the appropriate bit. Mentored committers can provide a "Reviewed by" but not an "Approved by". * Committers can acquire an additional bit by the usual process of finding a mentor who will propose them to core, doceng, or portmgr, as appropriate. When approved, they will be added to 'access' and the normal mentoring period will ensue, which will involve a continuing of "Approved by" for some period. @@ -385,7 +385,7 @@ freebsd https://git.freebsd.org/${repo}.git (fetch) freebsd git@gitrepo.freebsd.org:${repo}.git (push) .... + -Again, note that `gitrepo.freebsd.org` will be canonicalized to `repo.freebsd.org` in the future. +Again, note that `gitrepo.freebsd.org` has been canonicalized to `repo.freebsd.org`. * Install commit message template hook: + @@ -416,7 +416,7 @@ git worktree add -b admin ../${repo}-admin internal/admin .... For browsing `internal/admin` branch on web: -https://cgit.freebsd.org/${repo}/log/?h=internal/admin +`https://cgit.freebsd.org/${repo}/log/?h=internal/admin` For pushing, either specify the full refspec: @@ -1863,7 +1863,7 @@ You'll need to do the following once to update the push URL if you are a FreeBSD % git remote set-url --push freebsd ssh://git@gitrepo.freebsd.org/src.git .... -(note that gitrepo.freebsd.org will be change to repo.freebsd.org in the future.) +(Note that gitrepo.freebsd.org now points to the same addresses as repo.freebsd.org.) You will also need to add `freebsd` as the location to push to. The author recommends that your upstream GitHub repository remain the default push location so that you only push things into FreeBSD you intend to by making it explicit. @@ -2508,13 +2508,15 @@ 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 <> to generate or set a Kerberos for use with other FreeBSD services like the bug tracking database. +See <> 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 + -https://wiki.freebsd.org[FreeBSD Wiki] Account - A wiki account allows sharing projects and ideas. Those who do not yet have an account can follow instructions on the https://wiki.freebsd.org/AboutWiki[AboutWiki Page] to obtain one. Contact mailto:wiki-admin@FreeBSD.org[wiki-admin@FreeBSD.org] if you need help with your Wiki account. +link:https://wiki.freebsd.org[FreeBSD Wiki] Account - A wiki account allows sharing projects and ideas. +Those who do not yet have an account can follow instructions on the link:https://wiki.freebsd.org/Wiki/About[Wiki/About page] to obtain one. +Contact mailto:wiki-admin@FreeBSD.org[wiki-admin@FreeBSD.org] if you need help with your Wiki account. . Optional: Update Wiki Information + -Wiki Information - After gaining access to the wiki, some people add entries to the https://wiki.freebsd.org/HowWeGotHere[How We Got Here], https://wiki.freebsd.org/IRC/Nicknames[IRC Nicks], and https://wiki.freebsd.org/Community/Dogs[Dogs of FreeBSD] pages. +Wiki Information - After gaining access to the wiki, some people add entries to the https://wiki.freebsd.org/HowWeGotHere[How We Got Here], https://wiki.freebsd.org/IRC/Nicknames[IRC Nicks], https://wiki.freebsd.org/Community/Dogs[Dogs of FreeBSD], and or https://wiki.freebsd.org/Community/Cats[Cats of FreeBSD] pages. . Optional: Update Ports with Personal Information + [.filename]#ports/astro/xearth/files/freebsd.committers.markers# and [.filename]#src/usr.bin/calendar/calendars/calendar.freebsd# - Some people add entries for themselves to these files to show where they are located or the date of their birthday. @@ -3176,13 +3178,19 @@ As of March 2021, approximately 25,000 out of 90,000 files in the tree have been == Developer Relations When working directly on your own code or on code which is already well established as your responsibility, then there is probably little need to check with other committers before jumping in with a commit. -Working on a bug in an area of the system which is clearly orphaned (and there are a few such areas, to our shame), the same applies. -When modifying parts of the system which are maintained, formally, or informally, consider asking for review just as a developer would have before becoming a committer. +When working on a bug in an area of the system which is clearly orphaned (and there are a few such areas, to our shame), the same applies. +When modifying parts of the system which are maintained, formally or informally, consider asking for a review just as a developer would have before becoming a committer. For ports, contact the listed `MAINTAINER` in the [.filename]#Makefile#. To determine if an area of the tree is maintained, check the MAINTAINERS file at the root of the tree. If nobody is listed, scan the revision history to see who has committed changes in the past. -An example script that lists each person who has committed to a given file along with the number of commits each person has made can be found at on `freefall` at [.filename]#~eadler/bin/whodid#. +To list the names and email addresses of all commit authors for a given file in the last 2 years and the number of commits each has authored, ordered by descending number of commits, use: + +[source,shell] +---- +% git -C /path/to/repo shortlog -sne --since="2 years" -- relative/path/to/file +---- + If queries go unanswered or the committer otherwise indicates a lack of interest in the area affected, go ahead and commit it. [IMPORTANT] @@ -3295,7 +3303,7 @@ If there is something you want merged from FreeBSD-CURRENT to FreeBSD-STABLE (wh `{so-name}` is the link:https://www.FreeBSD.org/security/[FreeBSD Security Officer] and oversees the `{security-officer}`. {committers-name}:: -{svn-src-all}, {svn-ports-all} and {svn-doc-all} are the mailing lists that the version control system uses to send commit messages to. +{dev-src-all}, {dev-ports-all} and {dev-doc-all} are the mailing lists that the version control system uses to send commit messages to. _Never_ send email directly to these lists. Only send replies to this list when they are short and are directly related to a commit.