Differential D37091 Diff 114737 documentation/content/en/articles/committers-guide/_index.adoc

Changeset View

Standalone View

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

	---			---
	title: Committer's Guide			title: Committer's Guide
	authors:			authors:
	- author: The FreeBSD Documentation Project			- 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			description: Introductory information for FreeBSD committers
	trademarks: ["freebsd", "coverity", "ibm", "intel", "general"]			trademarks: ["freebsd", "coverity", "ibm", "intel", "general"]
	weight: 25			weight: 25
	tags: ["FreeBSD Committer's Guide", "Guide", "Community"]			tags: ["FreeBSD Committer's Guide", "Guide", "Community"]
	---			---

	= Committer's Guide			= Committer's Guide
	:doctype: article			:doctype: article
	Show All 29 Lines
	[.abstract-title]			[.abstract-title]
	Abstract			Abstract

	This document provides information for the FreeBSD committer community.			This document provides information for the FreeBSD committer community.
	All new committers should read this document before they start, and existing committers are strongly encouraged to review it from time to time.			All new committers should read this document before they start, and existing committers are strongly encouraged to review it from time to time.

	Almost all FreeBSD developers have commit rights to one or more repositories.			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.			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.			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.			This document may also be of interest to members of the FreeBSD community who want to learn more about how the project works.

	'''			'''

	toc::[]			toc::[]

	Show All 12 Lines

	\|_Reference Machines_			\|_Reference Machines_
	\|`ref.FreeBSD.org`, `universe.freeBSD.org` (see also link:https://www.FreeBSD.org/internal/machines/[FreeBSD Project Hosts])			\|`ref.FreeBSD.org`, `universe.freeBSD.org` (see also link:https://www.FreeBSD.org/internal/machines/[FreeBSD Project Hosts])

	\|_SMTP Host_			\|_SMTP Host_
	\|`smtp.FreeBSD.org:587` (see also <<smtp-setup>>).			\|`smtp.FreeBSD.org:587` (see also <<smtp-setup>>).

	\|`_src/_` Git Repository			\|`_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			\|`_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			\|`_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_			\|_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_			\|_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.
				philipUnsubmitted Not Done Inline Actions I think these locations should spell out freefall rather than `FreeBSD.org` cluster. This information probably dates back to when we had NFS mounts to machine-whose-name-we-do-not-speak all over the cluster. philip: I think these locations should spell out freefall rather than `FreeBSD.org` cluster. This…

	\|_Ports Management Team monthly reports_			\|_Ports Management Team monthly reports_
	\|[.filename]#/home/portmgr/public/monthly-reports# on the `FreeBSD.org` cluster.			\|[.filename]#/home/portmgr/public/monthly-reports# on the `FreeBSD.org` cluster.

	\|_Noteworthy `src/` Git Branches:_			\|_Noteworthy `src/` Git Branches:_
	\|`stable/n` (`n`-STABLE), `main` (-CURRENT)			\|`stable/n` (`n`-STABLE), `main` (-CURRENT)
	\|===			\|===

	▲ Show 20 Lines • Show All 71 Lines • ▼ Show 20 Lines
	Comment:			Comment:
	You selected this USER-ID:			You selected this USER-ID:
	"Chucky Daemon <notreal@example.com>"			"Chucky Daemon <notreal@example.com>"

	Change (N)ame, (C)omment, (E)mail or (O)kay/(Q)uit? o			Change (N)ame, (C)omment, (E)mail or (O)kay/(Q)uit? o
	You need a Passphrase to protect your secret key.			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).
				philipUnsubmitted Not Done Inline Actions Does a more authoritative source exist than some individual's personal diary? philip: Does a more authoritative source exist than some individual's personal diary?
				pauamma_gundo.comAuthorUnsubmitted Done Inline Actions Probably, but I'm unable to evaluate those claims. Implied question ("which authoritative sources discuss key sizes?") is beyond me. All I can suggest is removing the link if deemed too unreliable. pauamma_gundo.com: Probably, but I'm unable to evaluate those claims. Implied question ("which authoritative…

	<.> A three year key lifespan is short enough to obsolete keys weakened by advancing computer power, but long enough to reduce key management problems.			<.> A three year key lifespan is short enough to obsolete keys weakened by advancing computer power, but long enough to reduce key management problems.

	<.> Use your real name here, preferably matching that shown on government-issued ID to make it easier for others to verify your identity. Text that may help others identify you can be entered in the `Comment` section.			<.> Use your real name here, preferably matching that shown on government-issued ID to make it easier for others to verify your identity. Text that may help others identify you can be entered in the `Comment` section.
	+			+
	After the email address is entered, a passphrase is requested.			After the email address is entered, a passphrase is requested.
	Methods of creating a secure passphrase are contentious.			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.			Protect the private key and passphrase.
	If either the private key or passphrase may have been compromised or disclosed, immediately notify mailto:accounts@FreeBSD.org[accounts@FreeBSD.org] and revoke the key.			If either the private key or passphrase may have been compromised or disclosed, immediately notify mailto:accounts@FreeBSD.org[accounts@FreeBSD.org] and revoke the key.

	Committing the new key is shown in <<commit-steps, Steps for New Committers>>.			Committing the new key is shown in <<commit-steps, Steps for New Committers>>.

	[[kerberos-ldap]]			[[kerberos-ldap]]
	▲ Show 20 Lines • Show All 64 Lines • ▼ Show 20 Lines
	However, common sense dictates that a committer who has not previously worked in an area of the tree seek review prior to committing, seek approval from the appropriate responsible party, and/or work with a mentor.			However, common sense dictates that a committer who has not previously worked in an area of the tree seek review prior to committing, seek approval from the appropriate responsible party, and/or work with a mentor.
	Since the rules regarding code maintenance differ by area of the tree, this is as much for the benefit of the committer working in an area of less familiarity as it is for others working on the tree.			Since the rules regarding code maintenance differ by area of the tree, this is as much for the benefit of the committer working in an area of less familiarity as it is for others working on the tree.

	Committers are encouraged to seek review for their work as part of the normal development process, regardless of the area of the tree where the work is occurring.			Committers are encouraged to seek review for their work as part of the normal development process, regardless of the area of the tree where the work is occurring.

	=== Policy for Committer Activity in Other Trees			=== 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#.			* 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.			* 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".			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.			* 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.

	[[doc-blanket-approval]]			[[doc-blanket-approval]]
	==== Documentation Implicit (Blanket) Approval			==== Documentation Implicit (Blanket) Approval

	Some types of fixes have "blanket approval" from the {doceng}, allowing any committer to fix those categories of problems on any part of the doc tree.			Some types of fixes have "blanket approval" from the {doceng}, allowing any committer to fix those categories of problems on any part of the doc tree.
	▲ Show 20 Lines • Show All 102 Lines • ▼ Show 20 Lines
	+			+
	[source,shell]			[source,shell]
	....			....
	% git remote -v			% git remote -v
	freebsd https://git.freebsd.org/${repo}.git (fetch)			freebsd https://git.freebsd.org/${repo}.git (fetch)
	freebsd git@gitrepo.freebsd.org:${repo}.git (push)			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:			* Install commit message template hook:
	+			+
	[source,shell]			[source,shell]
	....			....
	% fetch https://cgit.freebsd.org/src/plain/tools/tools/git/hooks/prepare-commit-msg -o .git/hooks			% fetch https://cgit.freebsd.org/src/plain/tools/tools/git/hooks/prepare-commit-msg -o .git/hooks
	% chmod 755 .git/hooks/prepare-commit-msg			% chmod 755 .git/hooks/prepare-commit-msg
	....			....
	Show All 14 Lines
	Alternatively, you can add a worktree for the `admin` branch:			Alternatively, you can add a worktree for the `admin` branch:

	[source,shell]			[source,shell]
	....			....
	git worktree add -b admin ../${repo}-admin internal/admin			git worktree add -b admin ../${repo}-admin internal/admin
	....			....

	For browsing `internal/admin` branch on web:			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:			For pushing, either specify the full refspec:

	[source,shell]			[source,shell]
	....			....
	git push freebsd HEAD:refs/internal/admin			git push freebsd HEAD:refs/internal/admin
	....			....

	▲ Show 20 Lines • Show All 1,430 Lines • ▼ Show 20 Lines
	If you need to then commit work to FreeBSD, you can do so following the `Time to push changes upstream` instructions.			If you need to then commit work to FreeBSD, you can do so following the `Time to push changes upstream` instructions.
	You'll need to do the following once to update the push URL if you are a FreeBSD committer:			You'll need to do the following once to update the push URL if you are a FreeBSD committer:

	[source,shell]			[source,shell]
	....			....
	% git remote set-url --push freebsd ssh://git@gitrepo.freebsd.org/src.git			% 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.			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.			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.

	[[git-faq]]			[[git-faq]]
	=== Git FAQ			=== Git FAQ

	This section provides a number of targeted answers to questions that are likely to come up often for users and developers.			This section provides a number of targeted answers to questions that are likely to come up often for users and developers.
	▲ Show 20 Lines • Show All 628 Lines • ▼ Show 20 Lines
	======			======
	. Update Mentor and Mentee Information			. Update Mentor and Mentee Information
	+			+
	[.filename]#src/share/misc/committers-<repository>.dot# - Add an entry to the current committers section, where _repository_ is `doc`, `ports`, or `src`, depending on the commit privileges granted.			[.filename]#src/share/misc/committers-<repository>.dot# - Add an entry to the current committers section, where _repository_ is `doc`, `ports`, or `src`, depending on the commit privileges granted.
	+			+
	Add an entry for each additional mentor/mentee relationship in the bottom section.			Add an entry for each additional mentor/mentee relationship in the bottom section.
	. Generate a Kerberos Password			. 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			. 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			. 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			. 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.			[.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.
	. Optional: Prevent Duplicate Mailings			. Optional: Prevent Duplicate Mailings
	+			+
	Subscribers to {dev-commits-doc-all}, {dev-commits-ports-all} or {dev-commits-src-all} might wish to unsubscribe to avoid receiving duplicate copies of commit messages and followups.			Subscribers to {dev-commits-doc-all}, {dev-commits-ports-all} or {dev-commits-src-all} might wish to unsubscribe to avoid receiving duplicate copies of commit messages and followups.
	====			====

	▲ Show 20 Lines • Show All 645 Lines • ▼ Show 20 Lines
	The project draws identifiers from SPDX's list of valid https://spdx.org/licenses/[short license identifiers].			The project draws identifiers from SPDX's list of valid https://spdx.org/licenses/[short license identifiers].
	The project uses only the _SPDX-License-Identifier_ tag.			The project uses only the _SPDX-License-Identifier_ tag.

	As of March 2021, approximately 25,000 out of 90,000 files in the tree have been marked.			As of March 2021, approximately 25,000 out of 90,000 files in the tree have been marked.
	[[developer.relations]]			[[developer.relations]]
	== Developer Relations			== 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.			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 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 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#.			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.			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.			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.			If queries go unanswered or the committer otherwise indicates a lack of interest in the area affected, go ahead and commit it.

	[IMPORTANT]			[IMPORTANT]
	====			====
	Avoid sending private emails to maintainers.			Avoid sending private emails to maintainers.
	Other people might be interested in the conversation, not just the final output.			Other people might be interested in the conversation, not just the final output.
	====			====

	▲ Show 20 Lines • Show All 96 Lines • ▼ Show 20 Lines
	This team is responsible for setting release deadlines and controlling the release process.			This team is responsible for setting release deadlines and controlling the release process.
	During code freezes, the release engineers have final authority on all changes to the system for whichever branch is pending release status.			During code freezes, the release engineers have final authority on all changes to the system for whichever branch is pending release status.
	If there is something you want merged from FreeBSD-CURRENT to FreeBSD-STABLE (whatever values those may have at any given time), these are the people to talk to about it.			If there is something you want merged from FreeBSD-CURRENT to FreeBSD-STABLE (whatever values those may have at any given time), these are the people to talk to about it.

	`{so}`::			`{so}`::
	`{so-name}` is the link:https://www.FreeBSD.org/security/[FreeBSD Security Officer] and oversees the `{security-officer}`.			`{so-name}` is the link:https://www.FreeBSD.org/security/[FreeBSD Security Officer] and oversees the `{security-officer}`.

	{committers-name}::			{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.			_Never_ send email directly to these lists.
	Only send replies to this list when they are short and are directly related to a commit.			Only send replies to this list when they are short and are directly related to a commit.

	{developers-name}::			{developers-name}::
	All committers are subscribed to -developers.			All committers are subscribed to -developers.
	This list was created to be a forum for the committers "community" issues.			This list was created to be a forum for the committers "community" issues.
	Examples are Core voting, announcements, etc.			Examples are Core voting, announcements, etc.
	+			+
	▲ Show 20 Lines • Show All 755 Lines • Show Last 20 Lines