Differential D31926 Diff 95542 documentation/content/en/articles/committers-guide/_index.adoc

Changeset View

Standalone View

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

Context not available.
	:sectnumlevels: 6	:sectnumlevels: 6
	:source-highlighter: rouge	:source-highlighter: rouge
	:experimental:	:experimental:
		:images-path: articles/committers-guide/

	ifeval::["{backend}" == "html5"]	ifdef::env-beastie+backend-html5[]
	include::shared/authors.adoc[]	include::shared/authors.adoc[]
	include::shared/en/teams.adoc[lines=16..-1]	include::shared/mirrors.adoc[]
	include::shared/en/mailing-lists.adoc[]	include::shared/releases.adoc[]
	include::shared/en/urls.adoc[]	include::shared/{{% lang %}}/mailing-lists.adoc[]
		include::shared/{{% lang %}}/urls.adoc[]
		:imagesdir: ../../../images/{images-path}
	endif::[]	endif::[]

	ifeval::["{backend}" == "pdf"]	ifndef::env-beastie[]
	include::../../../../shared/authors.adoc[]	include::../../../../shared/asciidoctor.adoc[]
	include::../../../../shared/en/teams.adoc[lines=16..-1]
	include::../../../../shared/en/mailing-lists.adoc[]
	include::../../../../shared/en/urls.adoc[]
	endif::[]

	ifeval::["{backend}" == "epub3"]
	include::../../../../shared/authors.adoc[]
	include::../../../../shared/en/teams.adoc[lines=16..-1]
	include::../../../../shared/en/mailing-lists.adoc[]
	include::../../../../shared/en/urls.adoc[]
	endif::[]	endif::[]

	[.abstract-title]	[.abstract-title]
Context not available.

	* Changes in [.filename]#documentation/content/en/books/porters-handbook/versions/_index.adoc#	* Changes in [.filename]#documentation/content/en/books/porters-handbook/versions/_index.adoc#
	+	+
	link:{porters-handbook}versions/[__FreeBSD_version Values (Porter's Handbook)], mainly used for src committers.	extref:{porters-handbook}versions/[__FreeBSD_version Values (Porter's Handbook)], mainly used for src committers.
	* Changes in [.filename]#documentation/content/en/articles/contributors/contrib-additional.adoc#	* Changes in [.filename]#documentation/content/en/articles/contributors/contrib-additional.adoc#
	+	+
	link:{contributors}#contrib-additional[Additional FreeBSD Contributors'] maintenance.	extref:{contributors}[Additional FreeBSD Contributors, contrib-additional] maintenance.
	* All link:#commit-steps[Steps for New Committers], doc related	* All link:#commit-steps[Steps for New Committers], doc related
	* Security advisories; Errata Notices; Releases;	* Security advisories; Errata Notices; Releases;
	+	+
Context not available.
	+	+
	Used by {donations}.	Used by {donations}.

	Before any commit, a build test is necessary; see the 'Overview' and 'The FreeBSD Documentation Build Process' sections of the link:{fdp-primer}[FreeBSD Documentation Project Primer for New Contributors] for more details.	Before any commit, a build test is necessary; see the 'Overview' and 'The FreeBSD Documentation Build Process' sections of the extref:{fdp-primer}[FreeBSD Documentation Project Primer for New Contributors] for more details.

	[[git-primer]]	[[git-primer]]
	== Git Primer	== Git Primer
Context not available.
	....	....
	so that won't be covered in depth here.	so that won't be covered in depth here.

	If you want to build a custom kernel, link:{handbook}#kernelconfig[the kernel config section] of the FreeBSD Handbook recommends creating a file MYKERNEL under sys/${ARCH}/conf with your changes against GENERIC.	If you want to build a custom kernel, extref:{handbook}[the kernel config section, kernelconfig] of the FreeBSD Handbook recommends creating a file MYKERNEL under sys/${ARCH}/conf with your changes against GENERIC.
	To have MYKERNEL disregarded by Git, it can be added to .git/info/exclude.	To have MYKERNEL disregarded by Git, it can be added to .git/info/exclude.

	===== Updating	===== Updating
Context not available.
	The cgit repository web interface for use with web browsers is at https://cgit.FreeBSD.org/ports/ .	The cgit repository web interface for use with web browsers is at https://cgit.FreeBSD.org/ports/ .
	The production Git repository is at https://git.FreeBSD.org/ports.git and at ssh://anongit@git.FreeBSD.org/ports.git (or anongit@git.FreeBSD.org:ports.git).	The production Git repository is at https://git.FreeBSD.org/ports.git and at ssh://anongit@git.FreeBSD.org/ports.git (or anongit@git.FreeBSD.org:ports.git).

	There is also a mirror on GitHub, see link:{handbook}mirrors/#mirrors[External mirrors] for an overview.	There is also a mirror on GitHub, see extref:{handbook}/mirrors[External mirrors, mirrors] for an overview.
	The 'current' branch is 'main' .	The 'current' branch is 'main' .
	The quarterly branches are named 'yyyyQn' for year 'yyyy' and quarter 'n'.	The quarterly branches are named 'yyyyQn' for year 'yyyy' and quarter 'n'.

Context not available.
	[.filename]#doc/shared/authors.adoc# - Add an author entity. Later steps depend on this entity, and missing this step will cause the [.filename]#doc/# build to fail. This is a relatively easy task, but remains a good first test of version control skills.	[.filename]#doc/shared/authors.adoc# - Add an author entity. Later steps depend on this entity, and missing this step will cause the [.filename]#doc/# build to fail. This is a relatively easy task, but remains a good first test of version control skills.
	. Update the List of Developers and Contributors	. Update the List of Developers and Contributors
	+	+
	[.filename]#doc/documentation/content/en/articles/contributors/contrib-committers.adoc# - Add an entry, which will then appear in the "Developers" section of the link:{contributors}#staff-committers[Contributors List]. Entries are sorted by last name.	[.filename]#doc/documentation/content/en/articles/contributors/contrib-committers.adoc# - Add an entry, which will then appear in the "Developers" section of the extref:{contributors}[Contributors List, staff-committers]. Entries are sorted by last name.
	+	+
	[.filename]#doc/documentation/content/en/articles/contributors/contrib-additional.adoc# - _Remove_ the entry. Entries are sorted by first name.	[.filename]#doc/documentation/content/en/articles/contributors/contrib-additional.adoc# - _Remove_ the entry. Entries are sorted by first name.
	. Add a News Item	. Add a News Item
Context not available.

	You can find out more about Bugzilla at:	You can find out more about Bugzilla at:

	* link:{pr-guidelines}[FreeBSD Problem Report Handling Guidelines]	* extref:{pr-guidelines}[FreeBSD Problem Report Handling Guidelines]
	* link:https://www.FreeBSD.org/support/[https://www.FreeBSD.org/support]	* link:https://www.FreeBSD.org/support/[https://www.FreeBSD.org/support]

	[[phabricator]]	[[phabricator]]
Context not available.
	It is not a conflict resolution body.	It is not a conflict resolution body.
	The vast majority of documentation related discussion takes place on the {freebsd-doc}.	The vast majority of documentation related discussion takes place on the {freebsd-doc}.
	More details regarding the doceng team can be found in its https://www.FreeBSD.org/internal/doceng/[charter].	More details regarding the doceng team can be found in its https://www.FreeBSD.org/internal/doceng/[charter].
	Committers interested in contributing to the documentation should familiarize themselves with the link:{fdp-primer}[Documentation Project Primer].	Committers interested in contributing to the documentation should familiarize themselves with the extref:{fdp-primer}[Documentation Project Primer].

	`{re-members}`::	`{re-members}`::
	These are the members of the `{re}`.	These are the members of the `{re}`.
Context not available.
	. Respect existing maintainers if listed.	. Respect existing maintainers if listed.
	+	+
	Many parts of FreeBSD are not "owned" in the sense that any specific individual will jump up and yell if you commit a change to "their" area, but it still pays to check first.	Many parts of FreeBSD are not "owned" in the sense that any specific individual will jump up and yell if you commit a change to "their" area, but it still pays to check first.
	One convention we use is to put a maintainer line in the [.filename]#Makefile# for any package or subtree which is being actively maintained by one or more people; see link:{developers-handbook}#policies[Source Tree Guidelines and Policies] for documentation on this.	One convention we use is to put a maintainer line in the [.filename]#Makefile# for any package or subtree which is being actively maintained by one or more people; see extref:{developers-handbook}[Source Tree Guidelines and Policies, policies] for documentation on this.
	Where sections of code have several maintainers, commits to affected areas by one maintainer need to be reviewed by at least one other maintainer.	Where sections of code have several maintainers, commits to affected areas by one maintainer need to be reviewed by at least one other maintainer.
	In cases where the "maintainer-ship" of something is not clear, look at the repository logs for the files in question and see if someone has been working recently or predominantly in that area.	In cases where the "maintainer-ship" of something is not clear, look at the repository logs for the files in question and see if someone has been working recently or predominantly in that area.
	. Any disputed change must be backed out pending resolution of the dispute if requested by a maintainer. Security related changes may override a maintainer's wishes at the Security Officer's discretion.	. Any disputed change must be backed out pending resolution of the dispute if requested by a maintainer. Security related changes may override a maintainer's wishes at the Security Officer's discretion.
Context not available.

	Check the port, preferably to make sure it compiles and packages correctly.	Check the port, preferably to make sure it compiles and packages correctly.

	The link:{porters-handbook}testing[Porters Handbook's Testing Chapter] contains more detailed instructions.	The extref:{porters-handbook}testing[Porters Handbook's Testing Chapter] contains more detailed instructions.
	See the link:{porters-handbook}testing#testing-portclippy[Portclippy / Portfmt] and the link:{porters-handbook}testing#testing-poudriere[Poudriere] sections.	See the extref:{porters-handbook}testing[Portclippy / Portfmt, testing-portclippy] and the extref:{porters-handbook}testing[Poudriere, testing-poudriere] sections.

	You do not necessarily have to eliminate all warnings but make sure you have fixed the simple ones.	You do not necessarily have to eliminate all warnings but make sure you have fixed the simple ones.

	If the port came from a submitter who has not contributed to the Project before, add that person's name to the link:{contributors}#contrib-additional[Additional Contributors] section of the FreeBSD Contributors List.	If the port came from a submitter who has not contributed to the Project before, add that person's name to the extref:{contributors}[Additional Contributors, contrib-additional] section of the FreeBSD Contributors List.

	Close the PR if the port came in as a PR.	Close the PR if the port came in as a PR.
	To close a PR, change the state to `Issue Resolved` and the resolution as `Fixed`.	To close a PR, change the state to `Issue Resolved` and the resolution as `Fixed`.

	[NOTE]	[NOTE]
	====	====
	If for some reason using link:{porters-handbook}testing#testing-poudriere[Poudriere] to test the new port is not possible, the bare minimum of testing includes this sequence:	If for some reason using extref:{porters-handbook}testing[Poudriere, testing-poudriere] to test the new port is not possible, the bare minimum of testing includes this sequence:

	[source,shell]	[source,shell]
	....	....
Context not available.
	[[ports-qa-new-category-how]]	[[ports-qa-new-category-how]]
	==== What is the procedure for creating a new category?	==== What is the procedure for creating a new category?

	Please see link:{porters-handbook}#proposing-categories[Proposing a New Category] in the Porter's Handbook.	Please see extref:{porters-handbook}[Proposing a New Category, proposing-categories] in the Porter's Handbook.
	Once that procedure has been followed and the PR has been assigned to the {portmgr}, it is their decision whether or not to approve it.	Once that procedure has been followed and the PR has been assigned to the {portmgr}, it is their decision whether or not to approve it.
	If they do, it is their responsibility to:	If they do, it is their responsibility to:

Context not available.
	. Once this is done, you can commit the updated [.filename]#ports/Makefile# to connect the new category to the build and also commit the [.filename]#Makefile# changes for the old category or categories.	. Once this is done, you can commit the updated [.filename]#ports/Makefile# to connect the new category to the build and also commit the [.filename]#Makefile# changes for the old category or categories.
	. Add appropriate entries to [.filename]#ports/MOVED#.	. Add appropriate entries to [.filename]#ports/MOVED#.
	. Update the documentation by modifying:	. Update the documentation by modifying:
	** the link:{porters-handbook}#PORTING-CATEGORIES[list of categories] in the Porter's Handbook	** the extref:{porters-handbook}[list of categories, PORTING-CATEGORIES] in the Porter's Handbook
	+	+
	. Only once all the above have been done, and no one is any longer reporting problems with the new ports, should the old ports be deleted from their previous locations in the repository.	. Only once all the above have been done, and no one is any longer reporting problems with the new ports, should the old ports be deleted from their previous locations in the repository.
	====	====
Context not available.

	This is much simpler than a physical category. Only a few modifications are needed:	This is much simpler than a physical category. Only a few modifications are needed:

	* the link:{porters-handbook}#PORTING-CATEGORIES[list of categories] in the Porter's Handbook	* the extref:{porters-handbook}[list of categories, PORTING-CATEGORIES] in the Porter's Handbook

	[[ports-qa-misc-questions]]	[[ports-qa-misc-questions]]
	=== Miscellaneous Questions	=== Miscellaneous Questions
Context not available.