git: 63894dffe8 - main - Miscellaneous small changes to the Committer's Guide.
- Go to: [ bottom of page ] [ top of archives ] [ this month ]
Date: Tue, 03 Jan 2023 23:15:00 UTC
The branch main has been updated by pauamma:
URL: https://cgit.FreeBSD.org/doc/commit/?id=63894dffe8ed65c9dc705959bc07c8a62991007d
commit 63894dffe8ed65c9dc705959bc07c8a62991007d
Author: Pau Amma <pauamma@FreeBSD.org>
AuthorDate: 2022-10-22 18:16:57 +0000
Commit: Pau Amma <pauamma@FreeBSD.org>
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 <<non-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.
@@ -77,19 +77,19 @@ toc::[]
|`smtp.FreeBSD.org:587` (see also <<smtp-setup>>).
|`_src/_` Git Repository
-|`ssh://git@gitrepo.FreeBSD.org/src.git` (see also <<git-getting-started-base-layout>>).
+|`ssh://git@gitrepo.FreeBSD.org/src.git`
|`_doc/_` Git Repository
-|`ssh://git@gitrepo.FreeBSD.org/doc.git` (see also <<git-getting-started-doc-layout>>).
+|`ssh://git@gitrepo.FreeBSD.org/doc.git`
|`_ports/_` Git Repository
-|`ssh://git@gitrepo.FreeBSD.org/ports.git` (see also <<git-getting-started-ports-layout>>).
+|`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 <<kerberos-ldap>> to generate or set a Kerberos for use with other FreeBSD services like the bug tracking database.
+See <<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).
. 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.