Changeset View
Standalone View
en_US.ISO8859-1/articles/committers-guide/article.xml
<?xml version="1.0" encoding="iso-8859-1"?> | <?xml version="1.0" encoding="iso-8859-1"?> | ||||
<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V5.0-Based Extension//EN" | <!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V5.0-Based Extension//EN" | ||||
"http://www.FreeBSD.org/XML/share/xml/freebsd50.dtd" [ | "http://www.freebsd.org/XML/share/xml/freebsd50.dtd" [ | ||||
wblock: This should not change. Not sure why it did. | |||||
<!ENTITY ga "Google Analytics"> | <!ENTITY ga "Google Analytics"> | ||||
]> | ]> | ||||
<article xmlns="http://docbook.org/ns/docbook" | <article xmlns="http://docbook.org/ns/docbook" | ||||
xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" | xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" | ||||
xml:lang="en"> | xml:lang="en"> | ||||
<info> | <info> | ||||
<title>Committer's Guide</title> | <title>FreeBSD Committer's Guide</title> | ||||
wblockUnsubmitted Not Done Inline Actionss/FreeBSD/&os;/ wblock: s/FreeBSD/&os;/ | |||||
<author> | <author> | ||||
<orgname>The &os; Documentation Project</orgname> | <orgname>The &os; Documentation Project</orgname> | ||||
</author> | </author> | ||||
<copyright> | <copyright> | ||||
<year>1999</year> | <year>1999</year> | ||||
<year>2000</year> | <year>2000</year> | ||||
Show All 9 Lines | <copyright> | ||||
<year>2010</year> | <year>2010</year> | ||||
<year>2011</year> | <year>2011</year> | ||||
<year>2012</year> | <year>2012</year> | ||||
<year>2013</year> | <year>2013</year> | ||||
<year>2014</year> | <year>2014</year> | ||||
<year>2015</year> | <year>2015</year> | ||||
<year>2016</year> | <year>2016</year> | ||||
<year>2017</year> | <year>2017</year> | ||||
wblockUnsubmitted Not Done Inline ActionsThis is a whitespace change. Phabricator is helpfully making sure I can't really tell which kind, but possibly a blank line with just a tab. Whitespace changes are bad, mkay? wblock: This is a whitespace change. Phabricator is helpfully making sure I can't really tell which… | |||||
<holder>The &os; Documentation Project</holder> | <holder>The &os; Documentation Project</holder> | ||||
</copyright> | </copyright> | ||||
<legalnotice xml:id="trademarks" role="trademarks"> | <legalnotice xml:id="trademarks" role="trademarks"> | ||||
&tm-attrib.freebsd; | &tm-attrib.freebsd; | ||||
&tm-attrib.coverity; | &tm-attrib.coverity; | ||||
&tm-attrib.ibm; | &tm-attrib.ibm; | ||||
&tm-attrib.intel; | &tm-attrib.intel; | ||||
&tm-attrib.sparc; | &tm-attrib.sparc; | ||||
&tm-attrib.general; | &tm-attrib.general; | ||||
</legalnotice> | </legalnotice> | ||||
<pubdate>$FreeBSD$</pubdate> | <pubdate>$FreeBSD$</pubdate> | ||||
<releaseinfo>$FreeBSD$</releaseinfo> | <releaseinfo>$FreeBSD$</releaseinfo> | ||||
<abstract> | <abstract> | ||||
<para>This document provides information for the &os; | <para>Welcome to &os;! This onboarding guide provides new &os; | ||||
committer community. All new committers should read this | committers, contributors, GSoC students, and other project | ||||
document before they start, and existing committers are | community members with the procedures, policies and tools | ||||
wblockUnsubmitted Not Done Inline ActionsUse the serial/Harvard/Oxford comma: wblock: Use the serial/Harvard/Oxford comma:
s/policies/policies,/ | |||||
strongly encouraged to review it from time to time.</para> | required to commit to the various &os; source repositories. | ||||
While not every section of this guide will apply to every new | |||||
wblockUnsubmitted Not Done Inline ActionsThe "while not" construct is kind of esoteric. Consider non-native English speakers and translators. Also, "will apply" is kind of passive. The first half of this sentence can possibly be removed: `Every project participant...` wblock: The "while not" construct is kind of esoteric. Consider non-native English speakers and… | |||||
<para>Almost all &os; developers have commit rights to one or | community member, every project participant is encouraged to | ||||
more repositories. However, a few developers do not, and some | grow their project participation in conjunction with the | ||||
of the information here applies to them as well. (For | growth of their technical abilities. Existing committers are | ||||
instance, some people only have rights to work with the | strongly encouraged to review this guide from time to time and | ||||
Problem Report database). Please see | committers who would like to mentor a new committer should | ||||
<xref linkend="non-committers"/> for more information.</para> | refer to the <link | ||||
xlink:href="http://www.freebsd.org/internal/new-account.html">New | |||||
wblockUnsubmitted Not Done Inline ActionsIndent error. Because this is inside a new tag, needs another level of indent: refer to the <link xlink:href="http://www.freebsd.org/internal/new-account.html">New Account Creation Procedure</link> page for guidance.</para> wblock: Indent error. Because this is inside a new tag, needs another level of indent:
```refer to… | |||||
<para>This document may also be of interest to members of the | Account Creation Procedure</link> page for guidance.</para> | ||||
&os; community who want to learn more about how the project | |||||
works.</para> | |||||
</abstract> | </abstract> | ||||
</info> | </info> | ||||
<sect1 xml:id="admin"> | <sect1 xml:id="benefits"> | ||||
<title>Administrative Details</title> | <title>Benefits of &os; Project Participation</title> | ||||
editor_callfortesting.orgAuthorUnsubmitted Not Done Inline ActionsA bit silly? Motivating? Dated? editor_callfortesting.org: A bit silly? Motivating? Dated? | |||||
wblockUnsubmitted Not Done Inline ActionsThe introduction? Probably. wblock: The introduction? Probably. | |||||
<informaltable frame="none" orient="port" pgwide="1"> | <sect2 xml:id="benefits-recognition"> | ||||
<tgroup cols="2"> | <title>Recognition</title> | ||||
<colspec colwidth="20*"/> | |||||
<colspec colwidth="80*"/> | <para>Recognition as an open source software contributor is the | ||||
longest lasting benefit of contributing to &os;. The &os; | |||||
project has brought together contributors from around the world | |||||
for over 20 years under three generations of leadership. &os; | |||||
is a complete operating system for various computing | |||||
architectures with a welcoming community that focuses on | |||||
tecnological innovation, flexibility and performance. | |||||
bcrUnsubmitted Not Done Inline Actionss/tecnological/technological/ bcr: s/tecnological/technological/ | |||||
Additional benefits of contributing to &os; include:</para> | |||||
</sect2> | |||||
<sect2 xml:id="benefits-freebsdmall"> | |||||
<title>FreeBSD Mall Discs</title> | |||||
bcrUnsubmitted Not Done Inline ActionsI'm not sure whether this is still the case. You might need to ask. I believe they are owned and operated by IXsystems now. bcr: I'm not sure whether this is still the case. You might need to ask. I believe they are owned… | |||||
<para>&os; committers can get a free 4-CD or DVD set at | |||||
conferences from | |||||
<link xlink:href="http://www.freebsdmall.com">&os; Mall, | |||||
Inc.</link>.</para> | |||||
</sect2> | |||||
<sect2 xml:id="benefits-irc"> | |||||
<title>Freenode <acronym>IRC</acronym> cloked hostmasks</title> | |||||
bcrUnsubmitted Not Done Inline Actionss/cloked/cloaked/ bcr: s/cloked/cloaked/ | |||||
<para>In addition, developers may request a cloaked hostmask | |||||
for their account on the Freenode IRC network in the form | |||||
of | |||||
<literal>freebsd/developer/</literal><replaceable>freefall | |||||
name</replaceable> or | |||||
<literal>freebsd/developer/</literal><replaceable>NickServ | |||||
name</replaceable>. To request a cloak, send an email to | |||||
&a.irc.email; with your requested hostmask and NickServ | |||||
account name.</para> | |||||
</sect2> | |||||
<sect2 xml:id="benefits-gandi"> | |||||
<title>Gandi.net Discounts</title> | |||||
<para>Gandi provides website hosting, cloud computing, domain | |||||
registration, and X.509 certificate services.</para> | |||||
<para>Gandi offers an E-rate discount to all &os; developers. | |||||
Send mail to <email>non-profit@gandi.net</email> using your | |||||
<literal>@freebsd.org</literal> mail address, and indicate | |||||
your Gandi handle.</para> | |||||
</sect2> | |||||
</sect1> | |||||
<sect1 xml:id="committer.types"> | |||||
<title>Commit Bit Types</title> | |||||
<para>The &os; repository has a number of components which, when | |||||
wblockUnsubmitted Not Done Inline ActionsThis sentence is really complicated. Please keep it simple. Some of us were edumacated in American schools. That also keeps it simple for non-native English speakers and translators. wblock: This sentence is really complicated. Please keep it simple. Some of us were edumacated in… | |||||
combined, support the basic operating system source, | |||||
documentation, third party application ports infrastructure, and | |||||
various maintained utilities. When &os; commit bits are | |||||
allocated, the areas of the tree where the bit may be used are | |||||
wblockUnsubmitted Not Done Inline ActionsThis sentence can be simpler: "Commit bits are specific for certain parts of the repository." Although strictly speaking, we have three different repos. wblock: This sentence can be simpler: "Commit bits are specific for certain parts of the repository."… | |||||
specified. Generally, the areas associated with a bit reflect | |||||
who authorized the allocation of the commit bit. Additional | |||||
wblockUnsubmitted Not Done Inline ActionsNot sure what this means. "The areas associated with a bit"... wblock: Not sure what this means. "The areas associated with a bit"... | |||||
areas of authority may be added at a later date: when this | |||||
wblockUnsubmitted Not Done Inline ActionsThe colon is just a sentence splice here. When possible, use two shorter sentences rather than a long one spliced with something. Colons should introduce a list or conclusion. Semicolons are generally for fictional narratives. wblock: The colon is just a sentence splice here. When possible, use two shorter sentences rather than… | |||||
occurs, the committer should follow normal commit bit allocation | |||||
procedures for that area of the tree, seeking approval from the | |||||
appropriate entity and possibly getting a mentor for that area | |||||
bcrUnsubmitted Not Done Inline ActionsI would remove "possibly" as it is always the case to mentor someone for a certain commit bit. bcr: I would remove "possibly" as it is always the case to mentor someone for a certain commit bit. | |||||
wblockUnsubmitted Not Done Inline ActionsThis whole sentence is kind of fuzzy, suggesting the reader follow the right procedures but not giving any guidance as to what they are. wblock: This whole sentence is kind of fuzzy, suggesting the reader follow the right procedures but not… | |||||
for some period of time.</para> | |||||
<informaltable frame="none" pgwide="1"> | |||||
<tgroup cols="3"> | |||||
<tbody> | <tbody> | ||||
<row> | <row> | ||||
<entry><emphasis>Login Methods</emphasis></entry> | <entry><emphasis>Committer Type</emphasis></entry> | ||||
<entry>&man.ssh.1;, protocol 2 only</entry> | <entry><emphasis>Responsible</emphasis></entry> | ||||
<entry><emphasis>Tree Components</emphasis></entry> | |||||
</row> | </row> | ||||
<row> | <row> | ||||
<entry><emphasis>Main Shell Host</emphasis></entry> | <entry>src</entry> | ||||
<entry><systemitem | <entry>core@</entry> | ||||
class="fqdomainname">freefall.FreeBSD.org</systemitem></entry> | <entry>src/, doc/ subject to appropriate review</entry> | ||||
bcrUnsubmitted Not Done Inline Actionssrc committers can not commit to doc, they need a doc bit for that. With approval and review by someone that has a bit for that area, everyone may commit to that area. For example, a ports committer may commit a change for the porters handbook when this change was approved by someone with a doc bit. bcr: src committers can not commit to doc, they need a doc bit for that. With approval and review by… | |||||
</row> | </row> | ||||
<row> | <row> | ||||
<entry><emphasis><literal>src/</literal> Subversion | <entry>doc</entry> | ||||
Root</emphasis></entry> | <entry>doceng@</entry> | ||||
<entry><literal>svn+ssh://</literal><systemitem | <entry>doc/, ports/, src/ documentation</entry> | ||||
bcrUnsubmitted Not Done Inline Actionsdoc is special in this: doc committers may make textual changes like typo fixes to comments and user visible output in src and ports (although the latter is even less common), but may not do any code changes. Even when a textual change is to be made, it is good practice to ask the responsible person (see MAINTAINERS file in the src repo) for permission. If no maintainer is listed, then ask the person that made the latest change to the code/file in question. bcr: doc is special in this: doc committers may make textual changes like typo fixes to comments and… | |||||
class="fqdomainname">repo.FreeBSD.org</systemitem><filename>/base</filename> | |||||
(see also <xref | |||||
linkend="svn-getting-started-base-layout"/>).</entry> | |||||
</row> | </row> | ||||
<row> | <row> | ||||
<entry><emphasis><literal>doc/</literal> Subversion | <entry>ports</entry> | ||||
Root</emphasis></entry> | <entry>portmgr@</entry> | ||||
<entry><literal>svn+ssh://</literal><systemitem | <entry>ports/</entry> | ||||
class="fqdomainname">repo.FreeBSD.org</systemitem><filename>/doc</filename> | |||||
(see also <xref | |||||
linkend="svn-getting-started-doc-layout"/>).</entry> | |||||
</row> | </row> | ||||
</tbody> | |||||
</tgroup> | |||||
</informaltable> | |||||
<row> | <para>Commit bits allocated prior to the development of the notion | ||||
<entry><emphasis><literal>ports/</literal> Subversion | of areas of authority may be appropriate for use in many parts | ||||
Root</emphasis></entry> | of the tree. 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.</para> | |||||
wblockUnsubmitted Not Done Inline ActionsPlease simplify this. Use small words and short sentences. It's not that the reader is stupid, it's that they have a lot going on. Also not sure about the word "tree". I think we mainly refer to repositories here and elsewhere, and should be consistent. Also also, be careful with "should" and "may". "May" generally implies permission: "You may now delete that code." while "should" is preferably only for recommendations: "But you should make a backup of it first." (And yes, avoid "you" and "your" as informal. I know I did it just there. And I'd do it again.) wblock: Please simplify this. Use small words and short sentences. It's not that the reader is stupid… | |||||
<entry><literal>svn+ssh://</literal><systemitem | <para>Committers are encouraged to seek review for their work as | ||||
class="fqdomainname">repo.FreeBSD.org</systemitem><filename>/ports</filename> | part of the normal development process, regardless of the area | ||||
wblockUnsubmitted Not Done Inline ActionsThe second half of this sentence is not needed. wblock: The second half of this sentence is not needed.
s/process,.*<\/para>/process.<\/para>/ | |||||
(see also <xref | of the tree where the work is occurring.</para> | ||||
linkend="svn-getting-started-ports-layout"/>).</entry> | |||||
</row> | |||||
<row> | <sect2> | ||||
<entry><emphasis>Internal Mailing Lists</emphasis></entry> | <title>Policy for Committer Activity in Other Trees</title> | ||||
wblockUnsubmitted Not Done Inline Actions"Tree" again. wblock: "Tree" again. | |||||
<entry>developers (technically called all-developers), | |||||
doc-developers, doc-committers, ports-developers, | <itemizedlist> | ||||
ports-committers, src-developers, src-committers. (Each | <listitem> | ||||
project repository has its own -developers and | <para>All committers may modify | ||||
-committers mailing lists. Archives for these lists can | <filename>base/head/share/misc/committers-*.dot</filename>, | ||||
be found in the files | <filename>base/head/usr.bin/calendar/calendars/calendar.freebsd</filename>, | ||||
<filename>/local/mail/<replaceable>repository-name</replaceable>-developers-archive</filename> | |||||
and | and | ||||
<filename>/local/mail/<replaceable>repository-name</replaceable>-committers-archive</filename> | <filename>ports/head/astro/xearth/files</filename>.</para> | ||||
on the <systemitem | </listitem> | ||||
class="fqdomainname">FreeBSD.org</systemitem> | |||||
cluster.)</entry> | |||||
</row> | |||||
<listitem> | |||||
<para>doc committers may commit | |||||
wblockUnsubmitted Not Done Inline Actionss/doc/Documentation/ wblock: s/doc/Documentation/ | |||||
documentation changes to <filename>src</filename> | |||||
files, such as man pages, READMEs, fortune databases, | |||||
wblockUnsubmitted Not Done Inline Actionss/such as/including/ But I'm not certain about whether enumerating all the different types of files is useful here. Could say "Documentation committers can commit spelling, grammar, and text clarification fixes to the src repository." (although recommend review from a src committer). wblock: s/such as/including/
But I'm not certain about whether enumerating all the different types of… | |||||
calendar files, and comment fixes without approval from a | |||||
src committer, subject to the normal care and tending of | |||||
commits.</para> | |||||
</listitem> | |||||
<listitem> | |||||
<para>Any committer may make changes to any other tree | |||||
with an "Approved by" from a non-mentored committer with | |||||
wblockUnsubmitted Not Done Inline ActionsI know what "non-mentored committer" means, but will a new committer? Is there a non-negative logic version of this? wblock: I know what "non-mentored committer" means, but will a new committer? Is there a non-negative… | |||||
the appropriate bit.</para> | |||||
</listitem> | |||||
<listitem> | |||||
<para>Committers can aquire 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 | |||||
wblockUnsubmitted Not Done Inline Actions'access' is a file, so should use <filename> tags and probably have more of a path. wblock: 'access' is a file, so should use <filename> tags and probably have more of a path. | |||||
will ensue, which will involve a continuing of | |||||
wblockUnsubmitted Not Done Inline Actionss/ensue/begin/ But I think this is another section where shorter, simpler sentences would help. wblock: s/ensue/begin/
But I think this is another section where shorter, simpler sentences would help. | |||||
<quote>Approved by</quote> for some period.</para> | |||||
</listitem> | |||||
<listitem> | |||||
<para>"Approved by" is only acceptable from non-mentored src | |||||
wblockUnsubmitted Not Done Inline ActionsI'm not sure about just "src", seems like that should be marked up in some way. Likewise with "Approved by", which should probably be in <literal> tags. wblock: I'm not sure about just "src", seems like that should be marked up in some way.
Likewise with… | |||||
committers -- mentored committers can provide a "Reviewed | |||||
bcrUnsubmitted Not Done Inline ActionsThis is wrong. Mentored committers must have an "Approved by:" line in their commits to indicate that their mentor (or another person with the same full commit bit) has seen and approved the commit. bcr: This is wrong. Mentored committers must have an "Approved by:" line in their commits to… | |||||
wblockUnsubmitted Not Done Inline ActionsDo not use "--", which is more properly an emdash. But don't use emdashes either, split the sentence. Short, declarative sentences. Also, markup for literal text. wblock: Do not use "--", which is more properly an emdash. But don't use emdashes either, split the… | |||||
by" but not an "Approved by".</para> | |||||
</listitem> | |||||
</itemizedlist> | |||||
</sect2> | |||||
</sect1> | |||||
<sect1 xml:id="conventions"> | |||||
<title>New Project Participant Setup, Conventions, and | |||||
Traditions</title> | |||||
<para>There are a number of things to do as a new developer. | |||||
The first set of steps is specific to committers only. These | |||||
steps must be done by a mentor for those who are not | |||||
committers.</para> | |||||
<sect2 xml:id="mentors"> | |||||
<title>Mentors</title> | |||||
<para>All new developers have a mentor assigned to them for | |||||
the first few months. A mentor is responsible for teaching | |||||
the mentee the rules and conventions of the project and | |||||
guiding their first steps in the developer community. The | |||||
mentor is also personally responsible for the mentee's actions | |||||
during this initial period.</para> | |||||
<para>For committers: do not commit anything without first | |||||
getting mentor approval. Document that approval with an | |||||
<literal>Approved by:</literal> line in the commit | |||||
message.</para> | |||||
<para>When the mentor decides that a mentee has learned the | |||||
ropes and is ready to commit on their own, the mentor | |||||
announces it with a commit to | |||||
<filename>conf/mentors</filename>. This file is in the | |||||
<filename>svnadmin</filename> branch of each | |||||
repository:</para> | |||||
<informaltable frame="none"> | |||||
<tgroup cols="2"> | |||||
<tbody> | |||||
<row> | <row> | ||||
<entry><emphasis>Core Team monthly | <entry><literal>src</literal></entry> | ||||
reports</emphasis></entry> | <entry><filename>base/svnadmin/conf/mentors</filename></entry> | ||||
<entry><filename>/home/core/public/monthly-reports</filename> | |||||
on the <systemitem | |||||
class="fqdomainname">FreeBSD.org</systemitem> | |||||
cluster.</entry> | |||||
</row> | </row> | ||||
<row> | <row> | ||||
<entry><emphasis>Ports Management Team monthly | <entry><literal>doc</literal></entry> | ||||
reports</emphasis></entry> | <entry><filename>doc/svnadmin/conf/mentors</filename></entry> | ||||
<entry><filename>/home/portmgr/public/monthly-reports</filename> | |||||
on the <systemitem | |||||
class="fqdomainname">FreeBSD.org</systemitem> | |||||
cluster.</entry> | |||||
</row> | </row> | ||||
<row> | <row> | ||||
<entry><emphasis>Noteworthy <literal>src/</literal> SVN | <entry><literal>ports</literal></entry> | ||||
Branches</emphasis></entry> | <entry><filename>ports/svnadmin/conf/mentors</filename></entry> | ||||
<entry> | |||||
<literal>stable/8</literal> (8.X-STABLE), | |||||
<literal>stable/9</literal> (9.X-STABLE), | |||||
<literal>stable/10</literal> (10.X-STABLE), | |||||
<literal>head</literal> (-CURRENT)</entry> | |||||
</row> | </row> | ||||
</tbody> | </tbody> | ||||
</tgroup> | </tgroup> | ||||
</informaltable> | </informaltable> | ||||
</sect2> | |||||
<para>&man.ssh.1; is required to connect to the project hosts. | <sect2 xml:id="devenv"> | ||||
For more information, see <xref linkend="ssh.guide"/>.</para> | <title>Development Environment</title> | ||||
<para>Useful links:</para> | <para>&os; contributors are encouraged to contribute to the project | ||||
using a &os; development environment. &os; is a self-hosted | |||||
operating system with a wide array of available graphical desktops | |||||
and contributing to &os; <emphasis>using</emphasis> &os; is the | |||||
most efficient way of identifying and resolving any issues you may | |||||
encounter. The myriad of available virtualization options make | |||||
this easier than ever if a bare-metal &os; system is not available | |||||
to you. See the <link xlink:href="&url.base;/handbook/bsdinstall.html">Installing &os;</link> | |||||
bcrUnsubmitted Not Done Inline ActionsYou can break up this long line after "<link" and indent the following "xlink..." on the next line. Also, you can do a regular line break after "Installing" in the link description. bcr: You can break up this long line after "<link" and indent the following "xlink..." on the next… | |||||
wblockUnsubmitted Not Done Inline ActionsYes. Also, if the entire <link></link> line will fit on a single line, can move it to a line of its own for readability. wblock: Yes. Also, if the entire <link></link> line will fit on a single line, can move it to a line… | |||||
section of the FreeBSD Handbook for information on installing &os; | |||||
wblockUnsubmitted Not Done Inline Actionss/FreeBSD/&os;/ wblock: s/FreeBSD/&os;/ | |||||
</para> | |||||
wblockUnsubmitted Not Done Inline ActionsMissing an ending period on the line above, and the </para> needs to be against that rather than on a new line. wblock: Missing an ending period on the line above, and the </para> needs to be against that rather… | |||||
</sect2> | |||||
<itemizedlist> | <sect2 xml:id="conventions-committers"> | ||||
<title>Setup Procedures for New Committers and Contributors</title> | |||||
wblockUnsubmitted Not Done Inline ActionsI'm not sure about the word "setup" here. wblock: I'm not sure about the word "setup" here. | |||||
<para>The fictional user "J. Random User <jru@freebsd.org>" | |||||
wblockUnsubmitted Not Done Inline ActionsPlease don't use quotes like this. There are markup tags for email addresses, and ways to use them that do not result in a mailto link: stupid phabricator link I would also say not to use freebsd.org as the mail domain, but rather example.org. wblock: Please don't use quotes like this. There are markup tags for email addresses, and ways to use… | |||||
will be used in these instructions. Replace jru's information | |||||
with your name and usrename as appropriate.</para> | |||||
bcrUnsubmitted Not Done Inline ActionsI would write "... with your real name ..." bcr: I would write "... with your **real** name ..."
s/usrename/username/ | |||||
wblockUnsubmitted Not Done Inline ActionsTelling the user to replace this information with the real information is probably not necessary. Either way, any information to be replaced must be in <replaceable> tags. wblock: Telling the user to replace this information with the real information is probably not… | |||||
<para>Those who have been given commit rights to the &os; | |||||
wblockUnsubmitted Not Done Inline ActionsPassive: s/Those who have been given commit rights/New committers/ wblock: Passive: s/Those who have been given commit rights/New committers/ | |||||
repositories must follow these steps.</para> | |||||
<itemizedlist xml:id="commit-notes"> | |||||
<listitem> | <listitem> | ||||
<para><link xlink:href="&url.base;/internal/">&os; | <para>Get mentor approval before committing each of these | ||||
Project Internal Pages</link></para> | changes!</para> | ||||
wblockUnsubmitted Not Done Inline Actionss/!/./ wblock: s/!/./ | |||||
</listitem> | </listitem> | ||||
<listitem> | <listitem> | ||||
<para><link | <para>The <filename>.ent</filename> and | ||||
xlink:href="&url.base;/internal/machines.html">&os; | <filename>.xml</filename> files mentioned below exist in | ||||
Project Hosts</link></para> | the &os; Documentation Project SVN repository at <link | ||||
xlink:href="svn.freebsd.org/doc/"><literal>svn.freebsd.org/doc/</literal></link>.</para> | |||||
wblockUnsubmitted Not Done Inline ActionsThe literal tags look like an artifact. wblock: The literal tags look like an artifact. | |||||
</listitem> | </listitem> | ||||
<listitem> | <listitem> | ||||
<para><link xlink:href="&url.base;/administration.html">&os; | <para>New files that do not have the | ||||
Project Administrative Groups</link></para> | <literal>FreeBSD=%H</literal> | ||||
<command>svn:keywords</command> property will be rejected | |||||
when attempting to commit them to the repository. Be sure | |||||
to read | |||||
<xref linkend="svn-daily-use-adding-and-removing"/> | |||||
bcrUnsubmitted Not Done Inline ActionsYou can move the <xref part of the link to the line above and indent the "linkend= ..." on this line. bcr: You can move the <xref part of the link to the line above and indent the "linkend= ..." on this… | |||||
wblockUnsubmitted Not Done Inline ActionsYou can... but this is better because it keeps the whole thing on one line for readability. wblock: You can... but this is better because it keeps the whole thing on one line for readability. | |||||
regarding adding and removing files. Verify that | |||||
<filename>~/.subversion/config</filename> contains the | |||||
necessary <quote>auto-props</quote> entries from | |||||
<filename>auto-props.txt</filename> mentioned | |||||
there.</para> | |||||
</listitem> | </listitem> | ||||
<listitem> | |||||
<para>All <filename>src</filename> commits should go to | |||||
&os.current; first before being merged to &os.stable;. | |||||
The &os.stable; branch must maintain | |||||
<acronym>ABI</acronym> and <acronym>API</acronym> | |||||
compatibility with earlier versions of that branch. Do | |||||
not merge changes that break this compatibility.</para> | |||||
</listitem> | |||||
</itemizedlist> | </itemizedlist> | ||||
<procedure xml:id="commit-steps"> | |||||
<title>Steps for New Committers and Contributors</title> | |||||
<step> | |||||
<title>Add an Author !ENTITY Entry</title> | |||||
bcrUnsubmitted Not Done Inline ActionsMaybe add <literal> tags around !ENTITY? bcr: Maybe add <literal> tags around !ENTITY? | |||||
<para>Committers: Add an author !ENTITY entry to | |||||
bcrUnsubmitted Not Done Inline ActionsDefinitely add <literal> tags around !ENTITY here. bcr: Definitely add <literal> tags around !ENTITY here. | |||||
<filename>doc/head/share/xml/authors.ent</filename>. | |||||
This is an XML element that is used throughout the &os; | |||||
wblockUnsubmitted Not Done Inline Actions<acronym> wblock: <acronym> | |||||
build system. Later steps depend on this entity, and | |||||
missing this step will cause the <filename>doc/</filename> | |||||
wblockUnsubmitted Not Done Inline Actionss/missing/skipping/ wblock: s/missing/skipping/
Passive->active: s/will cause/causes/ | |||||
build to fail. This is a relatively easy task, but remains | |||||
a good first test of version control skills. Entries are | |||||
sorted by @freebsd.org username.</para> | |||||
wblockUnsubmitted Not Done Inline ActionsNeed tags on the domain, and it should be capitalized (@FreeBSD.org). wblock: Need tags on the domain, and it should be capitalized (@FreeBSD.org). | |||||
<screen> | |||||
... | |||||
bcrUnsubmitted Not Done Inline ActionsThe ... belong to the line where the <screen> tag is. bcr: The ... belong to the line where the <screen> tag is.
<screen> is wrong here, use <userinput>… | |||||
wblockUnsubmitted Not Done Inline ActionsWell... <screen> is for screen output, and <userinput> is used inside that to show what the user types. But these are contents of files, and for that all you need is a <programlisting> element. wblock: Well... <screen> is for screen output, and <userinput> is used inside that to show what the… | |||||
<!ENTITY a.dexter "J. Random User"> | |||||
<!ENTITY a.jru.email "&a.jru; <email xmlns='http://docbook.org/ns/docbook'>jru@FreeBSD.org</email>"> | |||||
... | |||||
</screen> | |||||
bcrUnsubmitted Not Done Inline ActionsThis </userinput> tag should not be alone on a line by itself. It should close the last line of text you are displaying that way. bcr: This </userinput> tag should not be alone on a line by itself. It should close the last line of… | |||||
</step> | |||||
<step> | |||||
<title>Update the List of Developers or Contributors</title> | |||||
<para> | |||||
Committers: Add an entry to the <quote>Developers</quote> section | |||||
wblockUnsubmitted Not Done Inline ActionsThis is not a quotation, but a literal text entry. wblock: This is not a quotation, but a literal text entry. | |||||
of | |||||
<filename>doc/head/en_US.ISO8859-1/articles/contributors/contrib.committers.xml</filename> | |||||
bcrUnsubmitted Not Done Inline ActionsMaybe you can break this up into "... of <filename>contrib.committers.xml</filename>, located in <filename>doc/head/.../articles</filename> to appear ..." bcr: Maybe you can break this up into
"... of <filename>contrib.committers.xml</filename>, located… | |||||
to appear on the <link | |||||
xlink:href="&url.articles.contributors;/staff-committers.html">Contributors | |||||
List</link>. Entries are sorted by last name.</para> | |||||
<screen> | |||||
bcrUnsubmitted Not Done Inline Actionss/screen/userinput/ bcr: s/screen/userinput/ | |||||
wblockUnsubmitted Not Done Inline Actions<programlisting>, rather. wblock: <programlisting>, rather. | |||||
... | |||||
<listitem> | |||||
<para>&a.jru.email;</para> | |||||
</listitem> | |||||
... | |||||
</screen> | |||||
bcrUnsubmitted Not Done Inline ActionsLike above, this needs to be on the line where the last ... is. bcr: Like above, this needs to be on the line where the last ... is. | |||||
<para>Contributors becoming Committers: Transfer your !ENTITY | |||||
bcrUnsubmitted Not Done Inline Actions<literal>!ENTITY</literal> bcr: <literal>!ENTITY</literal> | |||||
entry from the <quote>Additional Contributors</quote> to the | |||||
<quote>Developers</quote> section.</para> | |||||
wblockUnsubmitted Not Done Inline ActionsNot <quote>. wblock: Not <quote>. | |||||
</step> | |||||
<step> | |||||
<title>Add a News Item</title> | |||||
<para>Add a News Item entry to | |||||
<filename>doc/head/share/xml/news.xml</filename> | |||||
bcrUnsubmitted Not Done Inline ActionsSentence stop at the end is missing. bcr: Sentence stop at the end is missing. | |||||
Look for the other entries that announce new committers and | |||||
follow the format. Use the date from the commit bit approval | |||||
email from <email>core@freebsd.org</email>.</para> | |||||
bcrUnsubmitted Not Done Inline ActionsThe commit bit email will not come from core for doc or ports bits. I would drop this part to just say "Use the date from the committ bit approval email." bcr: The commit bit email will not come from core for doc or ports bits. I would drop this part to… | |||||
<screen> | |||||
bcrUnsubmitted Not Done Inline ActionsUse <userinput> here, again. bcr: Use <userinput> here, again. | |||||
... | |||||
<month> | |||||
<name>9</name> | |||||
<day> | |||||
<name>23</name> | |||||
<event> | |||||
<p>New committer: | |||||
<a href="mailto:jru@FreeBSD.org">J. Random User</a> | |||||
(doc)</p> | |||||
bcrUnsubmitted Not Done Inline ActionsReplace (doc) with commit bit type (in <replaceable> tags). bcr: Replace (doc) with commit bit type (in <replaceable> tags). | |||||
</event> | |||||
</day> | |||||
</month> | |||||
... | |||||
</screen> | |||||
</step> | |||||
<step> | |||||
<title>Add a <acronym>PGP</acronym>/<acronym>GnuPG</acronym> Key</title> | |||||
<para>If you do not have a | |||||
<acronym>PGP</acronym>/<acronym>GnuPG</acronym> key or your key | |||||
is expiring relatively soon, refer to | |||||
<xref linkend="pgpkeys-creating"/> for instructions on how to | |||||
bcrUnsubmitted Not Done Inline ActionsMove the <xref part to the line above and indent the "linkend=..." part on this line. bcr: Move the <xref part to the line above and indent the "linkend=..." part on this line. | |||||
create a new <acronym>PGP</acronym>/<acronym>GnuPG</acronym> | |||||
key.</para> | |||||
<para>Add your <acronym>PGP</acronym>/<acronym>GnuPG</acronym> | |||||
key to | |||||
<filename>doc/head/share/pgpkeys/pgpkeys.ent</filename> | |||||
and | |||||
<filename>doc/head/share/pgpkeys/pgpkeys-developers.xml</filename> | |||||
using the | |||||
<filename>doc/head/share/pgpkeys/addkey.sh</filename> shell | |||||
script. See <link | |||||
xlink:href="http://svnweb.freebsd.org/doc/head/share/pgpkeys/README">README</link> | |||||
bcrUnsubmitted Not Done Inline Actionsxlink needs to be indented. bcr: xlink needs to be indented. | |||||
file for full details. Note the instructions provided by | |||||
bcrUnsubmitted Not Done Inline ActionsTwo spaces after . This probably requires a separate sweep through your changes as it may appear in multiple locations. bcr: Two spaces after . This probably requires a separate sweep through your changes as it may… | |||||
the script.</para> | |||||
<screen>&prompt.user; <userinput>./addkey.sh jru</userinput> | |||||
WARNING: Multiple keys found for <jru@FreeBSD.org<; exporting all. | |||||
bcrUnsubmitted Not Done Inline ActionsNot every new user will have multiple keys, so not sure whether we should include this line. bcr: Not every new user will have multiple keys, so not sure whether we should include this line. | |||||
WARNING: If this is not what you want, specify a key ID on the command line. | |||||
Generating jru.key... | |||||
Adding key to entity list... | |||||
Unless you are already listed there, you should now add the following | |||||
text to pgpkeys-developers.xml. Remember to keep the list sorted by | |||||
last name! | |||||
<sect2 xmlns="http://docbook.org/ns/docbook" xml:id="pgpkey-jru"> | |||||
<title>&a.jru.email;</title> | |||||
&pgpkey.jru; | |||||
</sect2> | |||||
If this is a role key or you are a core member, you should add it to | |||||
either pgpkeys-officers.xml or pgpkeys-core.xml instead. | |||||
If this is a new entry, don't forget to run the following commands | |||||
before committing: | |||||
% svn add jru.key | |||||
% svn propset svn:keywords FreeBSD=%H jru.key | |||||
</screen> | |||||
<para>Use | |||||
<filename>doc/head/share/pgpkeys/checkkey.sh</filename> to | |||||
verify that keys meet minimal best-practices | |||||
standards.</para> | |||||
<screen>&prompt.user; <userinput>./checkkey.sh jru</userinput> | |||||
WARNING: Multiple keys found for <jru@FreeBSD.org>; checking all. | |||||
WARNING: If this is not what you want, specify a key ID on the command line. | |||||
key E9A628D03AC59BFB: RSA, 2048 bits | |||||
key okay, E9A628D03AC59BFB meets minimal requirements | |||||
</screen> | |||||
<para>After adding and checking a key, add both updated | |||||
files to source control and then commit them. Entries in | |||||
this file are sorted by last name.</para> | |||||
<note> | |||||
<para>It is very important to have a current | |||||
<acronym>PGP</acronym>/Gnu<acronym>PG</acronym> key in | |||||
the repository. The key may be required for positive | |||||
identification of a committer. For example, the | |||||
&a.admins; might need it for account recovery. A | |||||
complete keyring of <systemitem | |||||
class="fqdomainname">freebsd.org</systemitem> users is | |||||
available for download from <link | |||||
xlink:href="&url.base;/doc/pgpkeyring.txt">http://www.freebsd.org/doc/pgpkeyring.txt</link>.</para> | |||||
</note> | |||||
</step> | |||||
<step> | |||||
<title>Update Mentor and Mentee Information</title> | |||||
<para>Add an entry to the current committers section of | |||||
<filename>base/head/share/misc/committers-<replaceable>repository</replaceable>.dot</filename> | |||||
where <replaceable>repository</replaceable> is | |||||
<literal>doc</literal>, <literal>ports</literal>, or | |||||
<literal>src</literal>, depending on the commit privileges | |||||
granted.</para> | |||||
<para>Add an entry for each additional mentor/mentee | |||||
relationship in the bottom section.</para> | |||||
</step> | |||||
<step> | |||||
<title>Generate a <application>Kerberos</application> | |||||
Password</title> | |||||
<para>See <xref linkend="kerberos-ldap"/> to generate or | |||||
set a <application>Kerberos</application> for use with | |||||
bcrUnsubmitted Not Done Inline Actionsthere seems to be a word missing after Kerberos. bcr: there seems to be a word missing after Kerberos. | |||||
other &os; services like the bug tracking database.</para> | |||||
</step> | |||||
<step> | |||||
<title>Set Up a Phabricator Account</title> | |||||
editor_callfortesting.orgAuthorUnsubmitted Not Done Inline ActionsChange all to reviews.freebsd.org. editor_callfortesting.org: Change all to reviews.freebsd.org. | |||||
<para>A <link xlink:href="http://reviews.freebsd.org">reviews.freebsd.org</link> | |||||
a.k.a. "Phabricator" account allows you to submit patches for | |||||
review by other project members for discussion and revision prior | |||||
to committing. Visit <link xlink:href="http://reviews.freebsd.org/auth/register/">reviews.freebsd.org/auth/register/</link> | |||||
bcrUnsubmitted Not Done Inline ActionsInsert a line break after <link and indent the xlink: line. bcr: Insert a line break after <link and indent the xlink: line. | |||||
to set up a Phabricator account. If you already have a Phabricator | |||||
account with non-&os; email address, log into Phabricator and add | |||||
bcrUnsubmitted Not Done Inline Actionswith a non-&os; bcr: with **a** non-&os; | |||||
your @freebsd.org email address to your profile. This will require | |||||
you to verify your address, after which you can make your | |||||
@freebsd.org address your primary address. Mail<email>phabric-admin@freebsd.org</email> | |||||
bcrUnsubmitted Not Done Inline ActionsAdd a space after "Mail" bcr: Add a space after "Mail" | |||||
and ask that your username be changed to your @freebsd.org address. | |||||
Note that when your account type is changed, you will no longer be | |||||
able to log in with your non-&os; password but rather will need to | |||||
use <application>Keberos</application>. See <xref linkend="kerberos-ldap"/> | |||||
bcrUnsubmitted Not Done Inline Actionss/Keberos/Kerberos/ bcr: s/Keberos/Kerberos/ | |||||
for details.</para> | |||||
</step> | |||||
<step> | |||||
<title>Optional: Create a Wiki Account</title> | |||||
<para>A <link xlink:href="http://wiki.freebsd.org">wiki.freebsd.org</link> | |||||
account allows you to share projects and ideas that are not | |||||
suitable for the primary &os; documentation. wiki.freebsd.org | |||||
bcrUnsubmitted Not Done Inline ActionsAvoid using the links at beginning of sentences. "Event organization such as DevSummits is also done via the wiki." bcr: Avoid using the links at beginning of sentences. "Event organization such as DevSummits is also… | |||||
is also used for event organization such as DevSummits. Visit | |||||
<link xlink:href="http://wiki.freebsd.org/action/newaccount/FrontPage?action=newaccount">wiki.freebsd.org/action/newaccount/FrontPage?action=newaccount</link> | |||||
to create a new Wiki account.</para> | |||||
</step> | |||||
<step> | |||||
<title>Optional: Update Wiki Information</title> | |||||
<para>Some project members add entries to | |||||
<link xlink:href="http://wiki.freebsd.org/HowWeGotHere">How | |||||
bcrUnsubmitted Not Done Inline ActionsPull the <link parts up into the previous line in all the links here and indent the lines after it. bcr: Pull the <link parts up into the previous line in all the links here and indent the lines after… | |||||
We Got Here</link>, | |||||
<link xlink:href="http://wiki.freebsd.org/IrcNicks">Irc | |||||
Nicks</link>, and <link | |||||
xlink:href="http://wiki.freebsd.org/DogsOfFreeBSD">Dogs | |||||
of FreeBSD</link> pages.</para> | |||||
</step> | |||||
<step> | |||||
<title>Optional: Add Additional Personal Information</title> | |||||
<para>Some project members add entries for themselves to | |||||
<filename>ports/astro/xearth/files/freebsd.committers.markers</filename> | |||||
and | |||||
<filename>src/usr.bin/calendar/calendars/calendar.freebsd</filename> | |||||
to show where they are located or the date of their | |||||
birthday.</para> | |||||
</step> | |||||
<step> | |||||
<title>Optional: Prevent Duplicate Mailings</title> | |||||
<para>Subscribers to &a.svn-src-all.name;, | |||||
&a.svn-ports-all.name; or &a.svn-doc-all.name; might wish | |||||
to unsubscribe to avoid receiving duplicate copies of | |||||
commit messages and followups.</para> | |||||
</step> | |||||
</procedure> | |||||
</sect2> | |||||
<sect2 xml:id="conventions-everyone"> | |||||
<title>For Everyone</title> | |||||
<procedure xml:id="conventions-everyone-steps"> | |||||
<step> | |||||
<para>Introduce yourself to the other developers, otherwise | |||||
no one will have any idea who you are or what you are | |||||
working on. The introduction need not be a comprehensive | |||||
biography, just write a paragraph or two about who you | |||||
are, what you plan to be working on as a developer in | |||||
&os;, and who will be your mentor. Email this to the | |||||
&a.developers; and you will be on your way!</para> | |||||
</step> | |||||
<step> | |||||
<para>Log into <systemitem>freefall.freebsd.org</systemitem> | |||||
and create a | |||||
<filename>/var/forward/<replaceable>user</replaceable></filename> | |||||
bcrUnsubmitted Not Done Inline ActionsYou can also use your jru example user here. bcr: You can also use your jru example user here. | |||||
(where <replaceable>user</replaceable> is your username) | |||||
file containing the e-mail address where you want mail | |||||
addressed to | |||||
<replaceable>yourusername</replaceable>@freebsd.org to be | |||||
forwarded. This includes all of the commit messages as | |||||
well as any other mail addressed to the &a.committers; and | |||||
the &a.developers;. Really large mailboxes which have | |||||
taken up permanent residence on | |||||
<systemitem>freefall</systemitem> may get truncated | |||||
without warning if space needs to be freed, so forward it | |||||
or read it and you will not lose it.</para> | |||||
<para>Due to the severe load dealing with SPAM places on the | |||||
central mail servers that do the mailing list processing | |||||
the front-end server does do some basic checks and will | |||||
drop some messages based on these checks. At the moment | |||||
proper DNS information for the connecting host is the only | |||||
check in place but that may change. Some people blame | |||||
these checks for bouncing valid email. If you want these | |||||
checks turned off for your email you can place a file | |||||
named <filename>.spam_lover</filename> in your home | |||||
directory on <systemitem | |||||
class="fqdomainname">freefall.freebsd.org</systemitem> | |||||
to disable the checks for your email.</para> | |||||
</step> | |||||
</procedure> | |||||
<note> | |||||
<para>Those who are developers but not committers will | |||||
not be subscribed to the committers or developers mailing | |||||
lists. The subscriptions are derived from the access | |||||
rights.</para> | |||||
</note> | |||||
</sect2> | |||||
</sect1> | </sect1> | ||||
<sect1 xml:id="ssh.guide"> | |||||
<title>Open<acronym>SSH</acronym> Keys for &os;</title> | |||||
<para>Cryptographic keys conforming to the | |||||
Open<acronym>SSH</acronym> (<emphasis>Secure | |||||
Shell</emphasis>) standard are used by the &os; project to allow | |||||
access by committers to various &os; servers for source | |||||
commits, communication and project management.</para> | |||||
<sect2 xml:id="sshkeys-creating"> | |||||
<title>Creating an OpenSSH Key</title> | |||||
<para>Existing OpenSSH keys can be used, but only if they | |||||
comply with the <acronym>ECDSA</acronym>, | |||||
<acronym>Ed25519</acronym> or <acronym>RSA</acronym> standards. | |||||
</para> | |||||
<para>For those who do not yet have an | |||||
Open<acronym>SSH</acronym> key, or need a new key to meet | |||||
&os; security requirements.</para> | |||||
<procedure> | |||||
<step> | |||||
<para>Generate a key pair using &man.ssh-keygen.1;. The key | |||||
pair will be saved to your <filename>$HOME/.ssh/</filename> | |||||
directory.</para> | |||||
<important> | |||||
<para>Only <acronym>ECDSA</acronym>, | |||||
<acronym>Ed25519</acronym> or <acronym>RSA</acronym> keys | |||||
are supported.</para> | |||||
</important> | |||||
</step> | |||||
<step> | |||||
<screen>&prompt.user; <userinput>ssh-keygen</userinput> | |||||
Enter file in which to save the key (/home/jru/.ssh/id_rsa): | |||||
Enter passphrase (empty for no passphrase): | |||||
Enter same passphrase again: | |||||
Your identification has been saved in /home/jru/.ssh/id_rsa. | |||||
Your public key has been saved in /home/jru/.ssh/id_rsa.pub. | |||||
The key fingerprint is: | |||||
SHA256:E+w9UzR94MPczAeqt/IJbXYmj2/+L4wr38NofwhmDts jru@host | |||||
The key's randomart image is: | |||||
+---[RSA 2048]----+ | |||||
| +o.o.| | |||||
| . =.*.oo| | |||||
| o O.* o| | |||||
| . o * + + | | |||||
| S + o = +| | |||||
| ..o+* = | | |||||
| B *o..| | |||||
| o E.* o| | |||||
| +o.o++| | |||||
+----[SHA256]-----+ | |||||
</screen> | |||||
</step> | |||||
<step> | |||||
<para>Send your public key | |||||
(<filename>$HOME/.ssh/id_ecdsa.pub</filename>, | |||||
<filename>$HOME/.ssh/id_ed25519.pub</filename>, or | |||||
<filename>$HOME/.ssh/id_rsa.pub</filename>) | |||||
to the person setting you up as a committer so it can be put | |||||
into | |||||
<filename><replaceable>yourlogin</replaceable></filename> | |||||
in | |||||
<filename>/etc/ssh-keys/</filename> on | |||||
<systemitem>freefall</systemitem>.</para> | |||||
</step> | |||||
<step> | |||||
<para>If you do not wish to type your password in every time | |||||
editor_callfortesting.orgAuthorUnsubmitted Not Done Inline ActionsPerhaps an actual usage example rather than RTFM. editor_callfortesting.org: Perhaps an actual usage example rather than RTFM. | |||||
you use &man.ssh.1;, and you use keys to | |||||
authenticate, &man.ssh-agent.1; is there for your | |||||
convenience. If you want to use &man.ssh-agent.1;, make | |||||
sure that you run it before running other applications. X | |||||
users, for example, usually do this from their | |||||
<filename>.xsession</filename> or | |||||
<filename>.xinitrc</filename>. See &man.ssh-agent.1; for | |||||
details.</para> | |||||
</step> | |||||
</procedure> | |||||
</sect2> | |||||
<sect2 xml:id="sshkeys-keymaster"> | |||||
<title>OpenSSH Server-Side User Account Key Management</title> | |||||
<para>The &os; Cluster provides a self-serve service for public | |||||
OpenSSH key management at | |||||
<systemitem>keymaster.freebsd.org</systemitem>. This service | |||||
allows you to list, add and remove OpenSSH keys associated | |||||
with your @freebsd.org username.</para> | |||||
<screen>&prompt.user; <userinput>ssh keymaster.freebsd.org</userinput> | |||||
============================================================================ | |||||
READ ME CAREFULLY | |||||
============================================================================ | |||||
MAKE SURE you know how to use PGP and that your key in the handbook is | |||||
current. PGP signed email to accounts@ is your primary recovery option. | |||||
You may use the following commands: | |||||
LIST: -- show your current keys | |||||
ssh jru@keymaster.freebsd.org list | |||||
ADD: -- Add a SINGLE public key FROM SSH STANDARD INPUT | |||||
ssh jru@keymaster.freebsd.org add < ~/.ssh/id_ed25519.pub | |||||
Alternative: "ssh jru@keymaster.freebsd.org add" and cut/paste. | |||||
(Must pass basic santiy checks. ED25519, RSA>=2048, ECDSA allowed) | |||||
REMOVE: -- interactively select keys to remove from the list. | |||||
ssh jru@keymaster.freebsd.org remove | |||||
You will receive an email copy of any changes with cc: to admin folks. | |||||
If you need help for non-standard key configurations: accounts@freebsd.org | |||||
Any changes that you make will take approximately 10 minutes to go live. | |||||
============================================================================ | |||||
</screen> | |||||
</sect2> | |||||
<sect2 xml:id="sshkeys-management"> | |||||
<title>Local OpenSSH Key Management</title> | |||||
<para>Now you should be able to use &man.ssh-add.1; for | |||||
editor_callfortesting.orgAuthorUnsubmitted Not Done Inline ActionsConsider an example rather than RTFM. editor_callfortesting.org: Consider an example rather than RTFM. | |||||
authentication once per session. This will prompt you for | |||||
your private key's pass phrase, and then store it in your | |||||
bcrUnsubmitted Not Done Inline Actionss/pass phrase/passphrase/ bcr: s/pass phrase/passphrase/ | |||||
authentication agent (&man.ssh-agent.1;). If you no longer | |||||
wish to have your key stored in the agent, issuing | |||||
<command>ssh-add -d</command> will remove it.</para> | |||||
<para>Test by doing something such as <command>ssh | |||||
freefall.freebsd.org ls /usr</command>.</para> | |||||
bcrUnsubmitted Not Done Inline Actions/usr needs to be wrapped into <filename> tags. bcr: /usr needs to be wrapped into <filename> tags. | |||||
<para>For more information, see | |||||
<package>security/openssh</package>, | |||||
&man.ssh.1;, &man.ssh-add.1;, &man.ssh-agent.1;, | |||||
&man.ssh-keygen.1;, and &man.scp.1;.</para> | |||||
<para>For information on adding, changing, or removing | |||||
&man.ssh.1; keys, see <uri | |||||
xlink:href="https://wiki.freebsd.org/clusteradm/ssh-keys">this | |||||
article</uri>.</para> | |||||
</sect2> | |||||
</sect1> | |||||
<sect1 xml:id="pgpkeys"> | <sect1 xml:id="pgpkeys"> | ||||
<title>Open<acronym>PGP</acronym> Keys for &os;</title> | <title><acronym>PGP</acronym>/<acronym>GnuPG</acronym> Keys for | ||||
&os;</title> | |||||
<para>Cryptographic keys conforming to the | <para>Cryptographic keys conforming to the | ||||
Open<acronym>PGP</acronym> (<emphasis>Pretty Good | <acronym>PGP</acronym> (<emphasis>Pretty Good | ||||
Privacy</emphasis>) standard are used by the &os; project to | Privacy</emphasis>)/<acronym>GnuPG</acronym> standard are used | ||||
authenticate committers. Messages carrying important | by the &os; project to authenticate committers. Messages | ||||
information like public <acronym>SSH</acronym> keys can be | carrying important information like new public | ||||
signed with the Open<acronym>PGP</acronym> key to prove that | <acronym>PGP</acronym>/<acronym>GnuPG</acronym> can be signed | ||||
they are really from the committer. See | with the <acronym>PGP</acronym>/<acronym>GnuPG</acronym> key to | ||||
prove that they are really from the committer. See | |||||
<link xlink:href="http://www.nostarch.com/pgp_ml.htm">PGP & | <link xlink:href="http://www.nostarch.com/pgp_ml.htm">PGP & | ||||
GPG: Email for the Practical Paranoid by Michael Lucas</link> | GPG: Email for the Practical Paranoid by Michael Lucas</link> | ||||
and <link | and <link | ||||
xlink:href="http://en.wikipedia.org/wiki/Pretty_Good_Privacy"></link> | xlink:href="http://en.wikipedia.org/wiki/Pretty_Good_Privacy"></link> | ||||
for more information.</para> | for more information.</para> | ||||
<sect2 xml:id="pgpkeys-creating"> | <sect2 xml:id="pgpkeys-creating"> | ||||
<title>Creating a Key</title> | <title>Creating a <acronym>PGP</acronym>/<acronym>GnuPG</acronym> | ||||
Key</title> | |||||
<para>Existing keys can be used, but should be checked with | <para>Existing <acronym>PGP</acronym>/<acronym>GnuPG</acronym> | ||||
<filename>doc/head/share/pgpkeys/checkkey.sh</filename> | keys can be used, but should be checked with <filename>doc/head/share/pgpkeys/checkkey.sh</filename> | ||||
bcrUnsubmitted Not Done Inline Actionsyou need to break the line after "with" and keep the <filename> part on its own line. bcr: you need to break the line after "with" and keep the <filename> part on its own line. | |||||
first.</para> | first.</para> | ||||
<para>For those who do not yet have an | <para>For those who do not yet have an | ||||
Open<acronym>PGP</acronym> key, or need a new key to meet &os; | <acronym>PGP</acronym>/<acronym>GnuPG</acronym> key, or need a | ||||
security requirements, here we show how to generate | new key to meet &os; security requirements, here we show how | ||||
one.</para> | to generate one.</para> | ||||
<procedure xml:id="pgpkeys-create-steps"> | <procedure xml:id="pgpkeys-create-steps"> | ||||
<step> | <step> | ||||
<para>Install | <para>Install <filename | ||||
<filename role="package">security/gnupg</filename>. Enter | role="package">security/gnupg</filename>. Enter these | ||||
these lines in <filename>~/.gnupg/gpg.conf</filename> to | lines in <filename>~/.gnupg/gpg.conf</filename> to set | ||||
set minimum acceptable defaults:</para> | minimum acceptable defaults:</para> | ||||
<programlisting>fixed-list-mode | <programlisting>fixed-list-mode | ||||
keyid-format 0xlong | keyid-format 0xlong | ||||
personal-digest-preferences SHA512 SHA384 SHA256 SHA224 | personal-digest-preferences SHA512 SHA384 SHA256 SHA224 | ||||
default-preference-list SHA512 SHA384 SHA256 SHA224 AES256 AES192 AES CAST5 BZIP2 ZLIB ZIP Uncompressed | default-preference-list SHA512 SHA384 SHA256 SHA224 AES256 AES192 AES CAST5 BZIP2 ZLIB ZIP Uncompressed | ||||
use-agent | use-agent | ||||
verify-options show-uid-validity | verify-options show-uid-validity | ||||
list-options show-uid-validity | list-options show-uid-validity | ||||
sig-notation issuer-fpr@notations.openpgp.fifthhorseman.net=%g | sig-notation issuer-fpr@notations.openpgp.fifthhorseman.net=%g | ||||
cert-digest-algo SHA512</programlisting> | cert-digest-algo SHA512</programlisting> | ||||
</step> | </step> | ||||
<step> | <step> | ||||
<para>Generate a key:</para> | <para>Generate a key:</para> | ||||
<para>Note that you must have full control of the terminal | |||||
for GPG key generation to succeed. Using 'su' will fail.</para> | |||||
<screen>&prompt.user; <userinput>gpg --full-gen-key</userinput> | <screen>&prompt.user; <userinput>gpg --full-gen-key</userinput> | ||||
gpg (GnuPG) 2.1.8; Copyright (C) 2015 Free Software Foundation, Inc. | gpg (GnuPG) 2.1.8; Copyright (C) 2015 Free Software Foundation, Inc. | ||||
This is free software: you are free to change and redistribute it. | This is free software: you are free to change and redistribute it. | ||||
There is NO WARRANTY, to the extent permitted by law. | There is NO WARRANTY, to the extent permitted by law. | ||||
Warning: using insecure memory! | Warning: using insecure memory! | ||||
Please select what kind of key you want: | Please select what kind of key you want: | ||||
(1) RSA and RSA (default) | (1) RSA and RSA (default) | ||||
(2) DSA and Elgamal | (2) DSA and Elgamal | ||||
(3) DSA (sign only) | (3) DSA (sign only) | ||||
(4) RSA (sign only) | (4) RSA (sign only) | ||||
Your selection? <userinput>1</userinput> | Your selection? <userinput>1</userinput> | ||||
RSA keys may be between 1024 and 4096 bits long. | RSA keys may be between 1024 and 4096 bits long. | ||||
What keysize do you want? (2048) <userinput>2048</userinput> <co xml:id="co-pgp-bits"/> | What keysize do you want? (2048) <userinput>2048</userinput> <co xml:id="co-pgp-bits"/> | ||||
Requested keysize is 2048 bits | Requested keysize is 2048 bits | ||||
Please specify how long the key should be valid. | Please specify how long the key should be valid. | ||||
0 = key does not expire | 0 = key does not expire | ||||
<n> = key expires in n days | <n> = key expires in n days | ||||
<n>w = key expires in n weeks | <n>w = key expires in n weeks | ||||
<n>m = key expires in n months | <n>m = key expires in n months | ||||
<n>y = key expires in n years | <n>y = key expires in n years | ||||
Key is valid for? (0) <userinput>3y</userinput> <co xml:id="co-pgp-expire"/> | Key is valid for? (0) <userinput>3y</userinput> <co xml:id="co-pgp-expire"/> | ||||
Key expires at Wed Nov 4 17:20:20 2015 MST | Key expires at Wed Nov 4 17:20:20 2020 MST | ||||
Is this correct? (y/N) <userinput>y</userinput> | Is this correct? (y/N) <userinput>y</userinput> | ||||
GnuPG needs to construct a user ID to identify your key. | GnuPG needs to construct a user ID to identify your key. | ||||
Real name: <userinput><replaceable>Chucky Daemon</replaceable></userinput> <co xml:id="co-pgp-realname"/> | Real name: <userinput><replaceable>J. Random User</replaceable></userinput> <co xml:id="co-pgp-realname"/> | ||||
Email address: <userinput><replaceable>notreal@example.com</replaceable></userinput> | Email address: <userinput><replaceable>jru@freebsd.org</replaceable></userinput> | ||||
Comment: | Comment: | ||||
You selected this USER-ID: | You selected this USER-ID: | ||||
"<replaceable>Chucky Daemon <notreal@example.com></replaceable>" | "<replaceable>J. Random User <jru@freebsd.org></replaceable>" | ||||
Change (N)ame, (C)omment, (E)mail or (O)kay/(Q)uit? <userinput>o</userinput> | Change (N)ame, (C)omment, (E)mail or (O)kay/(Q)uit? <userinput>o</userinput> | ||||
You need a Passphrase to protect your secret key.</screen> | You need a Passphrase to protect your secret key.</screen> | ||||
<calloutlist> | <calloutlist> | ||||
<callout arearefs="co-pgp-bits"> | <callout arearefs="co-pgp-bits"> | ||||
<para>2048-bit keys with a three-year expiration provide | <para>2048-bit keys with a three-year expiration provide | ||||
adequate protection at present (2013-12). <link | adequate protection at present (2013-12). <link | ||||
Show All 28 Lines | <para>After the email address is entered, a passphrase is | ||||
<link | <link | ||||
xlink:href="http://en.wikipedia.org/wiki/Passphrase"></link>.</para> | xlink:href="http://en.wikipedia.org/wiki/Passphrase"></link>.</para> | ||||
</step> | </step> | ||||
</procedure> | </procedure> | ||||
<para>Protect your private key and passphrase. If either the | <para>Protect your private key and passphrase. If either the | ||||
private key or passphrase may have been compromised or | private key or passphrase may have been compromised or | ||||
disclosed, immediately notify | disclosed, immediately notify | ||||
<email>accounts@FreeBSD.org</email> and revoke the key.</para> | <email>accounts@freebsd.org</email> and revoke the key.</para> | ||||
<para>Committing the new key is shown in | <para>Committing the new key is shown in | ||||
<xref linkend="commit-steps"/>.</para> | <xref linkend="commit-steps"/>.</para> | ||||
</sect2> | </sect2> | ||||
</sect1> | </sect1> | ||||
<sect1 xml:id="kerberos-ldap"> | <sect1 xml:id="kerberos-ldap"> | ||||
<title>Kerberos and LDAP web Password for &os; Cluster</title> | <title>Kerberos and LDAP web Password for &os; Cluster</title> | ||||
<para>The &os; cluster requires a Kerberos password to access | <para>The &os; cluster requires a Kerberos password to access | ||||
certain services. The Kerberos password also serves as the | certain services. The Kerberos password also serves as the | ||||
LDAP web password, since LDAP is proxying to Kerberos in the | LDAP web password, since LDAP is proxying to Kerberos in the | ||||
cluster. Some of the services | cluster. Some of the services | ||||
which require this include:</para> | which require this include:</para> | ||||
<itemizedlist> | <itemizedlist> | ||||
<listitem> | <listitem> | ||||
<para><link | <para><link | ||||
xlink:href="https://bugs.freebsd.org/bugzilla">Bugzilla</link></para> | xlink:href="http://bugs.freebsd.org/bugzilla">Bugzilla</link></para> | ||||
</listitem> | </listitem> | ||||
<listitem> | <listitem> | ||||
<para><link | <para><link | ||||
xlink:href="https://jenkins.freebsd.org">Jenkins</link></para> | xlink:href="http://jenkins.freebsd.org">Jenkins</link></para> | ||||
</listitem> | </listitem> | ||||
</itemizedlist> | </itemizedlist> | ||||
<para>To create a new Kerberos account in the &os; cluster, or to | <para>To create a new Kerberos account in the &os; cluster, or to | ||||
reset a Kerberos password for an existing account using a random | reset a Kerberos password for an existing account using a random | ||||
password generator:</para> | password generator:</para> | ||||
<screen>&prompt.user; <userinput>ssh kpasswd.freebsd.org</userinput></screen> | <screen>&prompt.user; <userinput>ssh jru@kpasswd.freebsd.org</userinput> | ||||
FreeBSD 12.0-CURRENT (CLUSTER) #0 r306376: Tue Sep 27 19:02:08 UTC 2016 | |||||
Unauthorized access is strictly prohibited. | |||||
role=kpasswd build=amd64_12@306376 | |||||
Hi there, jru.. | |||||
Sanity checking.. | |||||
Creating initial instance for jru | |||||
=================================================================== | |||||
Generating a strong, evil random password.. | |||||
=================================================================== | |||||
Your new, ready to forget, password: Fop%o3wee3ei | |||||
=================================================================== | |||||
You can change it with kpasswd(1) on any machine in the cluster, | |||||
but please consider using a password manager instead. Things like | |||||
LastPass, 1Password etc work great. | |||||
Run this again to get a different random password. | |||||
Connection to kpasswd.freebsd.org closed. | |||||
</screen> | |||||
<note> | <note> | ||||
<para>This must be done from a machine outside of the &os;.org | <para>This must be done from a machine outside of the &os;.org | ||||
cluster.</para> | cluster.</para> | ||||
</note> | </note> | ||||
<para>A Kerberos password can also be set manually | <para>A Kerberos password can also be set manually | ||||
by logging into <systemitem | by logging into <systemitem | ||||
class="fqdomainname">freefall.FreeBSD.org</systemitem> and | class="fqdomainname">freefall.freebsd.org</systemitem> and | ||||
running:</para> | running:</para> | ||||
<screen>&prompt.user; <userinput>kpasswd</userinput></screen> | <screen>&prompt.user; <userinput>ssh jru@freefall.freebsd.org</userinput> | ||||
&prompt.user; <userinput>kpasswd</userinput> | |||||
jru@FREEBSD.ORG's Password: | |||||
editor_callfortesting.orgAuthorUnsubmitted Not Done Inline ActionsWhy caps in the script? editor_callfortesting.org: Why caps in the script? | |||||
kpasswd: krb5_get_init_creds: Preauthentication failed | |||||
jru@freefall:~ % kpasswd | |||||
editor_callfortesting.orgAuthorUnsubmitted Not Done Inline ActionsYou are welcome to go nuts on user input formatting. editor_callfortesting.org: You are welcome to go nuts on user input formatting. | |||||
jru@FREEBSD.ORG's Password: | |||||
New password: | |||||
Verifying - New password: | |||||
Success : Password changed | |||||
</screen> | |||||
<note> | <note> | ||||
<para>Unless you have used the Kerberos-authenticated services | <para>Unless you have used the Kerberos-authenticated services | ||||
of the &os;.org cluster previously, | of the &os;.org cluster previously, | ||||
<errorname>Client unknown</errorname> will be shown. This | <errorname>Client unknown</errorname> will be shown. This | ||||
error means that the | error means that the | ||||
<command>ssh kpasswd.freebsd.org</command> method shown above | <command>ssh kpasswd.freebsd.org</command> method shown above | ||||
must be used first to initialize your Kerberos account.</para> | must be used first to initialize your Kerberos account.</para> | ||||
</note> | </note> | ||||
</sect1> | </sect1> | ||||
<sect1 xml:id="committer.types"> | <sect1 xml:id="admin"> | ||||
<title>Commit Bit Types</title> | <title>Administrative Links</title> | ||||
<para>The &os; repository has a number of components which, when | <informaltable frame="none" orient="port" pgwide="1"> | ||||
combined, support the basic operating system source, | <tgroup cols="2"> | ||||
documentation, third party application ports infrastructure, and | <colspec colwidth="20*"/> | ||||
various maintained utilities. When &os; commit bits are | <colspec colwidth="80*"/> | ||||
allocated, the areas of the tree where the bit may be used are | |||||
specified. Generally, the areas associated with a bit reflect | |||||
who authorized the allocation of the commit bit. Additional | |||||
areas of authority may be added at a later date: when this | |||||
occurs, the committer should follow normal commit bit allocation | |||||
procedures for that area of the tree, seeking approval from the | |||||
appropriate entity and possibly getting a mentor for that area | |||||
for some period of time.</para> | |||||
<informaltable frame="none" pgwide="1"> | |||||
<tgroup cols="3"> | |||||
<tbody> | <tbody> | ||||
<row> | <row> | ||||
<entry><emphasis>Committer Type</emphasis></entry> | <entry><emphasis>Login Methods</emphasis></entry> | ||||
<entry><emphasis>Responsible</emphasis></entry> | <entry>&man.ssh.1;, protocol 2 only</entry> | ||||
<entry><emphasis>Tree Components</emphasis></entry> | |||||
</row> | </row> | ||||
<row> | <row> | ||||
<entry>src</entry> | <entry><emphasis>Main Shell Host</emphasis></entry> | ||||
<entry>core@</entry> | <entry><systemitem | ||||
<entry>src/, doc/ subject to appropriate review</entry> | class="fqdomainname">freefall.freebsd.org</systemitem></entry> | ||||
</row> | </row> | ||||
<row> | <row> | ||||
<entry>doc</entry> | <entry><emphasis><literal>src/</literal> Subversion | ||||
<entry>doceng@</entry> | Root</emphasis></entry> | ||||
<entry>doc/, ports/, src/ documentation</entry> | <entry><literal>svn+ssh://</literal><systemitem | ||||
class="fqdomainname">repo.freebsd.org</systemitem><filename>/base</filename> | |||||
(see also <xref | |||||
linkend="svn-getting-started-base-layout"/>).</entry> | |||||
</row> | </row> | ||||
<row> | <row> | ||||
<entry>ports</entry> | <entry><emphasis><literal>doc/</literal> Subversion | ||||
<entry>portmgr@</entry> | Root</emphasis></entry> | ||||
<entry>ports/</entry> | <entry><literal>svn+ssh://</literal><systemitem | ||||
class="fqdomainname">repo.freebsd.org</systemitem><filename>/doc</filename> | |||||
(see also <xref | |||||
linkend="svn-getting-started-doc-layout"/>).</entry> | |||||
</row> | </row> | ||||
<row> | |||||
<entry><emphasis><literal>ports/</literal> Subversion | |||||
Root</emphasis></entry> | |||||
<entry><literal>svn+ssh://</literal><systemitem | |||||
class="fqdomainname">repo.freebsd.org</systemitem><filename>/ports</filename> | |||||
(see also <xref | |||||
linkend="svn-getting-started-ports-layout"/>).</entry> | |||||
</row> | |||||
<row> | |||||
<entry><emphasis>Internal Mailing Lists</emphasis></entry> | |||||
<entry>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/<replaceable>repository-name</replaceable>-developers-archive</filename> | |||||
and | |||||
<filename>/local/mail/<replaceable>repository-name</replaceable>-committers-archive</filename> | |||||
on the <systemitem | |||||
class="fqdomainname">freebsd.org</systemitem> | |||||
cluster.)</entry> | |||||
</row> | |||||
<row> | |||||
<entry><emphasis>Core Team monthly | |||||
reports</emphasis></entry> | |||||
<entry><filename>/home/core/public/monthly-reports</filename> | |||||
on the <systemitem | |||||
class="fqdomainname">freebsd.org</systemitem> | |||||
cluster.</entry> | |||||
</row> | |||||
<row> | |||||
<entry><emphasis>Ports Management Team monthly | |||||
reports</emphasis></entry> | |||||
<entry><filename>/home/portmgr/public/monthly-reports</filename> | |||||
on the <systemitem | |||||
class="fqdomainname">freebsd.org</systemitem> | |||||
cluster.</entry> | |||||
</row> | |||||
<row> | |||||
<entry><emphasis>Noteworthy <literal>src/</literal> SVN | |||||
Branches</emphasis></entry> | |||||
<entry> | |||||
<literal>stable/10</literal> (10.X-STABLE), | |||||
<literal>stable/11</literal> (11.X-STABLE), | |||||
<literal>head</literal> (12-CURRENT)</entry> | |||||
</row> | |||||
</tbody> | </tbody> | ||||
</tgroup> | </tgroup> | ||||
</informaltable> | </informaltable> | ||||
<para>Commit bits allocated prior to the development of the notion | <para>&man.ssh.1; is required to connect to the project hosts. | ||||
of areas of authority may be appropriate for use in many parts | For more information, see <xref linkend="ssh.guide"/>.</para> | ||||
of the tree. 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.</para> | |||||
<para>Committers are encouraged to seek review for their work as | <para>Useful links:</para> | ||||
part of the normal development process, regardless of the area | |||||
of the tree where the work is occurring.</para> | |||||
<itemizedlist> | |||||
<listitem> | |||||
<para><link xlink:href="&url.base;/internal/">&os; | |||||
Project Internal Pages</link></para> | |||||
</listitem> | |||||
<listitem> | |||||
<para><link | |||||
xlink:href="&url.base;/internal/machines.html">&os; | |||||
Project Hosts</link></para> | |||||
</listitem> | |||||
</itemizedlist> | |||||
</sect1> | |||||
<sect1 xml:id="teams"> | |||||
editor_callfortesting.orgAuthorUnsubmitted Not Done Inline ActionsReduce list to teams for the commit bit the account types? Offer all as an orientation to the project? editor_callfortesting.org: Reduce list to teams for the commit bit the account types? Offer all as an orientation to the… | |||||
<title>FreeBSD Teams</title> | |||||
<para>The &os; project is organized into several teams that | |||||
share responsibility for various aspects of the project. | |||||
See <link xlink:href="&url.base;/administration.html">&os; | |||||
Project Administrative Groups</link> for a complete | |||||
list of the active &os; teams.</para> | |||||
<variablelist> | |||||
<varlistentry> | |||||
<term>&a.doceng;</term> | |||||
<listitem> | |||||
<para>doceng is the group responsible for the documentation | |||||
bcrUnsubmitted Not Done Inline ActionsTry starting this sentence with an uppercase letter by rephrasing it. bcr: Try starting this sentence with an uppercase letter by rephrasing it. | |||||
build infrastructure, approving new documentation | |||||
committers, and ensuring that the &os; website and | |||||
documentation on the FTP site is up to date with respect | |||||
to the <application>subversion</application> tree. It is | |||||
not a conflict resolution body. | |||||
The vast majority of documentation related discussion | |||||
takes place on the &a.doc;. More details regarding the | |||||
doceng team can be found in its <link | |||||
xlink:href="http://www.freebsd.org/internal/doceng.html">charter</link>. | |||||
Committers interested in contributing to the documentation | |||||
should familiarize themselves with the <link | |||||
xlink:href="&url.books.fdp-primer;/index.html">Documentation | |||||
Project Primer</link>.</para> | |||||
</listitem> | |||||
</varlistentry> | |||||
<!-- | |||||
<varlistentry> | |||||
<term>&a.bde.email;</term> | |||||
<listitem> | |||||
<para>Bruce is the Style Police-Meister. When you do a | |||||
commit that could have been done better, Bruce will be | |||||
there to tell you. Be thankful that someone is. Bruce is | |||||
also very knowledgeable on the various standards | |||||
applicable to &os;.</para> | |||||
</listitem> | |||||
</varlistentry> | |||||
--> | |||||
<varlistentry> | |||||
<term>&a.portmgr;</term> | |||||
<listitem> | |||||
<para>portmgr is the group responsible for maintenance | |||||
bcrUnsubmitted Not Done Inline ActionsSame as above, start with uppercase by rephrasing. bcr: Same as above, start with uppercase by rephrasing. | |||||
of the &os; Ports Collection, a repository of third | |||||
party software that is ported to &os;. Committers | |||||
interested in contributing to &os; Ports should | |||||
familiarize themselves with the <link | |||||
xlink:href="&url.books.porters-handbook;/index.html">Porter's | |||||
bcrUnsubmitted Not Done Inline Actionsyou need to indent this line. bcr: you need to indent this line. | |||||
Handbook</link>.</para> | |||||
</listitem> | |||||
</varlistentry> | |||||
<varlistentry> | |||||
<term>&a.re;</term> | |||||
<listitem> | |||||
<para>The &a.re; team is responsible for setting &os; | |||||
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. If there is something | |||||
you want merged from &os.current; to &os.stable; | |||||
(whatever values those may have at any given time), | |||||
these are the people to talk to about it.</para> | |||||
<!-- | |||||
<para>Hiroki is also the keeper of the release documentation | |||||
(<filename>src/release/doc/*</filename>). If you commit a | |||||
change that you think is worthy of mention in the release | |||||
notes, please make sure he knows about it. Better still, | |||||
send him a patch with your suggested commentary.</para> --> | |||||
</listitem> | |||||
</varlistentry> | |||||
<varlistentry> | |||||
<term>&a.security-officer;</term> | |||||
<listitem> | |||||
<para>The &a.security-officer; is responsible for overseeing | |||||
all security-related issues of the &os; project.</para> | |||||
</listitem> | |||||
</varlistentry> | |||||
<varlistentry> | |||||
<term>Cluster Admin</term> | |||||
editor_callfortesting.orgAuthorUnsubmitted Not Done Inline ActionsAdd Entity editor_callfortesting.org: Add Entity | |||||
<listitem> | |||||
<para>The Cluster Admin team is responsible for overseeing | |||||
the &os; project infrastructure.</para> | |||||
</listitem> | |||||
</varlistentry> | |||||
<!-- | |||||
<varlistentry> | |||||
<term>&a.wollman.email;</term> | |||||
<listitem> | |||||
<para>If you need advice on obscure network internals or | |||||
are not sure of some potential change to the networking | |||||
subsystem you have in mind, Garrett is someone to talk | |||||
to. Garrett is also very knowledgeable on the various | |||||
standards applicable to &os;.</para> | |||||
</listitem> | |||||
</varlistentry> | |||||
--> | |||||
</variablelist> | |||||
</sect1> | |||||
<sect1 xml:id="lists"> | |||||
<title>FreeBSD Mailing Lists</title> | |||||
<para>The &os; maintains several mailing lists to facilitate | |||||
communication within the project.</para> | |||||
<variablelist> | |||||
<varlistentry> | |||||
<term>&a.committers;</term> | |||||
<listitem> | |||||
<para>&a.svn-src-all.name;, &a.svn-ports-all.name; and | |||||
&a.svn-doc-all.name; are the mailing lists that the | |||||
version control system uses to send commit messages to. | |||||
You should <emphasis>never</emphasis> send email directly | |||||
to these lists. You should only send replies to this list | |||||
when they are short and are directly related to a | |||||
commit.</para> | |||||
</listitem> | |||||
</varlistentry> | |||||
<varlistentry> | |||||
<term>&a.developers;</term> | |||||
<listitem> | |||||
<para>All committers are subscribed to -developers. This | |||||
list was created to be a forum for the committers | |||||
<quote>community</quote> issues. Examples are Core | |||||
voting, announcements, etc.</para> | |||||
<para>The &a.developers; is for the exclusive use of &os; | |||||
committers. In order to develop &os;, committers must | |||||
have the ability to openly discuss matters that will be | |||||
resolved before they are publicly announced. Frank | |||||
discussions of work in progress are not suitable for open | |||||
publication and may harm &os;.</para> | |||||
<para>All &os; committers are expected not to | |||||
not publish or forward messages from the | |||||
&a.developers; outside the list membership without | |||||
permission of all of the authors. Violators will be | |||||
removed from the | |||||
&a.developers;, resulting in a suspension of commit | |||||
bcrUnsubmitted Not Done Inline Actionscheck the indentation in this <para>, &a.developers; would certainly fit in the line above. bcr: check the indentation in this <para>, &a.developers; would certainly fit in the line above. | |||||
privileges. Repeated or flagrant violations may result in | |||||
permanent revocation of commit privileges.</para> | |||||
<para>This list is <emphasis>not</emphasis> intended as a | |||||
place for code reviews or for any technical discussion. | |||||
In fact using it as such hurts the &os; Project as it | |||||
gives a sense of a closed list where general decisions | |||||
affecting all of the &os; using community are made without | |||||
being <quote>open</quote>. Last, but not least | |||||
<emphasis>never, never ever, email the &a.developers; and | |||||
CC:/BCC: another &os; list</emphasis>. Never, ever email | |||||
another &os; email list and CC:/BCC: the &a.developers;. | |||||
Doing so can greatly diminish the benefits of this | |||||
list.</para> | |||||
</listitem> | |||||
</varlistentry> | |||||
</variablelist> | |||||
</sect1> | |||||
<sect1 xml:id="rules"> | |||||
<title>&os; Community Rules</title> | |||||
<para>As members of the &os; project, you form the public face of | |||||
the project, and how you behave has a vital impact on the public | |||||
perception of it.</para> | |||||
<para><emphasis>&os; Code of Conduct</emphasis></para> | |||||
<para>The &os; | |||||
<link xlink:href="&url.base;/internal/code-of-conduct.html">Code | |||||
of Conduct</link> exists to provide a consistent policy on | |||||
unacceptable behavior by &os; community members.</para> | |||||
<para>The following expands on the parts of the <emphasis>Code of | |||||
Conduct</emphasis> specific to committers.</para> | |||||
<orderedlist> | |||||
<listitem> | |||||
<para>Respect other committers.</para> | |||||
</listitem> | |||||
<listitem> | |||||
<para>Respect other contributors.</para> | |||||
</listitem> | |||||
<listitem> | |||||
<para>Discuss any significant change | |||||
<emphasis>before</emphasis> committing.</para> | |||||
</listitem> | |||||
<listitem> | |||||
<para>Respect existing maintainers (if listed in the | |||||
<varname>MAINTAINER</varname> field in | |||||
<filename>Makefile</filename> or in | |||||
<filename>MAINTAINER</filename> in the top-level | |||||
directory).</para> | |||||
</listitem> | |||||
<listitem> | |||||
<para>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.</para> | |||||
</listitem> | |||||
<listitem> | |||||
<para>Changes go to &os.current; before &os.stable; unless | |||||
specifically permitted by the release engineer or unless | |||||
they are not applicable to &os.current;. Any non-trivial or | |||||
non-urgent change which is applicable should also be allowed | |||||
to sit in &os.current; for at least 3 days before merging so | |||||
that it can be given sufficient testing. The release | |||||
engineer has the same authority over the &os.stable; branch | |||||
as outlined for the maintainer in rule #5.</para> | |||||
</listitem> | |||||
<listitem> | |||||
<para>Do not fight in public with other committers; it looks | |||||
bad.</para> | |||||
</listitem> | |||||
<listitem> | |||||
<para>Respect all code freezes and read the | |||||
<literal>committers</literal> and | |||||
<literal>developers</literal> mailing lists in a timely | |||||
manner so you know when a code freeze is in effect.</para> | |||||
</listitem> | |||||
<listitem> | |||||
<para>When in doubt on any procedure, ask first!</para> | |||||
</listitem> | |||||
<listitem> | |||||
<para>Test your changes before committing them.</para> | |||||
</listitem> | |||||
<listitem> | |||||
<para>Do not commit to anything under the | |||||
<filename>src/contrib</filename>, | |||||
<filename>src/crypto</filename>, or | |||||
<filename>src/sys/contrib</filename> trees without | |||||
<emphasis>explicit</emphasis> approval from the respective | |||||
maintainer(s).</para> | |||||
</listitem> | |||||
</orderedlist> | |||||
<para>As noted, breaking some of these rules can be grounds for | |||||
suspension or, upon repeated offense, permanent removal of | |||||
commit privileges. Individual members of core have the power to | |||||
temporarily suspend commit privileges until core as a whole has | |||||
the chance to review the issue. In case of an | |||||
<quote>emergency</quote> (a committer doing damage to the | |||||
repository), a temporary suspension may also be done by the | |||||
repository meisters. Only a 2/3 majority of core has the | |||||
authority to suspend commit privileges for longer than a week or | |||||
to remove them permanently. This rule does not exist to set | |||||
core up as a bunch of cruel dictators who can dispose of | |||||
committers as casually as empty soda cans, but to give the | |||||
project a kind of safety fuse. If someone is out of control, it | |||||
is important to be able to deal with this immediately rather | |||||
than be paralyzed by debate. In all cases, a committer whose | |||||
privileges are suspended or revoked is entitled to a | |||||
<quote>hearing</quote> by core, the total duration of the | |||||
suspension being determined at that time. A committer whose | |||||
privileges are suspended may also request a review of the | |||||
decision after 30 days and every 30 days thereafter (unless the | |||||
total suspension period is less than 30 days). A committer | |||||
whose privileges have been revoked entirely may request a review | |||||
after a period of 6 months has elapsed. This review policy is | |||||
<emphasis>strictly informal</emphasis> and, in all cases, core | |||||
reserves the right to either act on or disregard requests for | |||||
review if they feel their original decision to be the right | |||||
one.</para> | |||||
<para>In all other aspects of project operation, core is a subset | |||||
of committers and is bound by the | |||||
<emphasis>same rules</emphasis>. Just because someone is in | |||||
core this does not mean that they have special dispensation to | |||||
step outside any of the lines painted here; core's | |||||
<quote>special powers</quote> only kick in when it acts as a | |||||
group, not on an individual basis. As individuals, the core | |||||
team members are all committers first and core second.</para> | |||||
<sect2> | <sect2> | ||||
<title>Policy for Committer Activity in Other Trees</title> | <title>Details</title> | ||||
<itemizedlist> | <orderedlist> | ||||
<listitem xml:id="respect"> | |||||
<para>Respect other committers.</para> | |||||
<para>This means that you need to treat other committers as | |||||
the peer-group developers that they are. Despite our | |||||
occasional attempts to prove the contrary, one does not | |||||
get to be a committer by being stupid and nothing rankles | |||||
more than being treated that way by one of your peers. | |||||
Whether we always feel respect for one another or not (and | |||||
everyone has off days), we still have to | |||||
<emphasis>treat</emphasis> other committers with respect | |||||
at all times, on public forums and in private | |||||
email.</para> | |||||
<para>Being able to work together long term is this | |||||
project's greatest asset, one far more important than any | |||||
set of changes to the code, and turning arguments about | |||||
code into issues that affect our long-term ability to work | |||||
harmoniously together is just not worth the trade-off by | |||||
any conceivable stretch of the imagination.</para> | |||||
<para>To comply with this rule, do not send email when you | |||||
are angry or otherwise behave in a manner which is likely | |||||
to strike others as needlessly confrontational. First | |||||
calm down, then think about how to communicate in the most | |||||
effective fashion for convincing the other person(s) that | |||||
your side of the argument is correct, do not just blow off | |||||
some steam so you can feel better in the short term at the | |||||
cost of a long-term flame war. Not only is this very bad | |||||
<quote>energy economics</quote>, but repeated displays of | |||||
public aggression which impair our ability to work well | |||||
together will be dealt with severely by the project | |||||
leadership and may result in suspension or termination of | |||||
your commit privileges. The project leadership will take | |||||
into account both public and private communications | |||||
brought before it. It will not seek the disclosure of | |||||
private communications, but it will take it into account | |||||
if it is volunteered by the committers involved in the | |||||
complaint.</para> | |||||
<para>All of this is never an option which the project's | |||||
leadership enjoys in the slightest, but unity comes first. | |||||
No amount of code or good advice is worth trading that | |||||
away.</para> | |||||
</listitem> | |||||
<listitem> | <listitem> | ||||
<para>All committers may modify | <para>Respect other contributors.</para> | ||||
<filename>base/head/share/misc/committers-*.dot</filename>, | |||||
<filename>base/head/usr.bin/calendar/calendars/calendar.freebsd</filename>, | <para>You were not always a committer. At one time you were | ||||
and | a contributor. Remember that at all times. Remember what | ||||
<filename>ports/head/astro/xearth/files</filename>.</para> | it was like trying to get help and attention. Do not | ||||
forget that your work as a contributor was very important | |||||
to you. Remember what it was like. Do not discourage, | |||||
belittle, or demean contributors. Treat them with | |||||
respect. They are our committers in waiting. They are | |||||
every bit as important to the project as committers. | |||||
Their contributions are as valid and as important as your | |||||
own. After all, you made many contributions before you | |||||
became a committer. Always remember that.</para> | |||||
<para>Consider the points raised under | |||||
<xref linkend="respect"/> and apply them also to | |||||
contributors.</para> | |||||
</listitem> | </listitem> | ||||
<listitem> | <listitem> | ||||
<para>doc committers may commit | <para>Discuss any significant change | ||||
documentation changes to <filename>src</filename> | <emphasis>before</emphasis> committing.</para> | ||||
files, such as man pages, READMEs, fortune databases, | |||||
calendar files, and comment fixes without approval from a | <para>The repository is not where changes should be | ||||
src committer, subject to the normal care and tending of | initially submitted for correctness or argued over, that | ||||
commits.</para> | should happen first in the mailing lists or by use of the | ||||
Phabricator service and the commit should only happen once | |||||
something resembling consensus has been reached. This | |||||
does not mean that you have to ask permission before | |||||
correcting every obvious syntax error or manual page | |||||
misspelling, simply that you should try to develop a feel | |||||
for when a proposed change is not quite such a no-brainer | |||||
and requires some feedback first. People really do not | |||||
mind sweeping changes if the result is something clearly | |||||
better than what they had before, they just do not like | |||||
being <emphasis>surprised</emphasis> by those changes. | |||||
The very best way of making sure that you are on the right | |||||
track is to have your code reviewed by one or more other | |||||
committers.</para> | |||||
<para>When in doubt, ask for review!</para> | |||||
</listitem> | </listitem> | ||||
<listitem> | <listitem> | ||||
<para>Any committer may make changes to any other tree | <para>Respect existing maintainers if listed.</para> | ||||
with an "Approved by" from a non-mentored committer with | |||||
the appropriate bit.</para> | <para>Many parts of &os; are not <quote>owned</quote> in | ||||
the sense that any specific individual will jump up and | |||||
yell if you commit a change to <quote>their</quote> area, | |||||
but it still pays to check first. One convention we use | |||||
is to put a maintainer line in the | |||||
<filename>Makefile</filename> for any package or subtree | |||||
which is being actively maintained by one or more people; | |||||
see <link | |||||
xlink:href="&url.books.developers-handbook;/policies.html">http://www.freebsd.org/doc/en_US.ISO8859-1/books/developers-handbook/policies.html</link> | |||||
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. In cases where the | |||||
<quote>maintainer-ship</quote> of something is not clear, | |||||
you can also look at the repository logs for the file(s) | |||||
in question and see if someone has been working recently | |||||
or predominantly in that area.</para> | |||||
<para>Other areas of &os; fall under the control of someone | |||||
who manages an overall category of &os; evolution, such as | |||||
internationalization or networking. See <link | |||||
xlink:href="&url.base;/administration.html">http://www.freebsd.org/administration.html</link> | |||||
for more information on this.</para> | |||||
</listitem> | </listitem> | ||||
<listitem> | <listitem> | ||||
<para>Committers can aquire an additional bit by the usual | <para>Any disputed change must be backed out pending | ||||
process of finding a mentor who will propose them to core, | resolution of the dispute if requested by a maintainer. | ||||
doceng, or portmgr, as appropriate. When approved, they | Security related changes may override a maintainer's | ||||
will be added to 'access' and the normal mentoring period | wishes at the Security Officer's discretion.</para> | ||||
will ensue, which will involve a continuing of | |||||
<quote>Approved by</quote> for some period.</para> | <para>This may be hard to swallow in times of conflict (when | ||||
each side is convinced that they are in the right, of | |||||
course) but a version control system makes it unnecessary | |||||
to have an ongoing dispute raging when it is far easier to | |||||
simply reverse the disputed change, get everyone calmed | |||||
down again and then try to figure out what is the best way | |||||
to proceed. If the change turns out to be the best thing | |||||
after all, it can be easily brought back. If it turns out | |||||
not to be, then the users did not have to live with the | |||||
bogus change in the tree while everyone was busily | |||||
debating its merits. People <emphasis>very</emphasis> | |||||
rarely call for back-outs in the repository since | |||||
discussion generally exposes bad or controversial changes | |||||
before the commit even happens, but on such rare occasions | |||||
the back-out should be done without argument so that we | |||||
can get immediately on to the topic of figuring out | |||||
whether it was bogus or not.</para> | |||||
</listitem> | </listitem> | ||||
<listitem> | <listitem> | ||||
<para>"Approved by" is only acceptable from non-mentored src | <para>Changes go to &os.current; before &os.stable; unless | ||||
committers -- mentored committers can provide a "Reviewed | specifically permitted by the release engineer or unless | ||||
by" but not an "Approved by".</para> | they are not applicable to &os.current;. Any non-trivial | ||||
or non-urgent change which is applicable should also be | |||||
allowed to sit in &os.current; for at least 3 days before | |||||
merging so that it can be given sufficient testing. The | |||||
release engineer has the same authority over the | |||||
&os.stable; branch as outlined in rule #5.</para> | |||||
<para>This is another <quote>do not argue about it</quote> | |||||
issue since it is the release engineer who is ultimately | |||||
responsible (and gets beaten up) if a change turns out to | |||||
be bad. Please respect this and give the release engineer | |||||
your full cooperation when it comes to the &os.stable; | |||||
branch. The management of &os.stable; may frequently seem | |||||
to be overly conservative to the casual observer, but also | |||||
bear in mind the fact that conservatism is supposed to be | |||||
the hallmark of &os.stable; and different rules apply | |||||
there than in &os.current;. There is also really no point | |||||
in having &os.current; be a testing ground if changes are | |||||
merged over to &os.stable; immediately. Changes need a | |||||
chance to be tested by the &os.current; developers, so | |||||
allow some time to elapse before merging unless the | |||||
&os.stable; fix is critical, time sensitive or so obvious | |||||
as to make further testing unnecessary (spelling fixes to | |||||
manual pages, obvious bug/typo fixes, etc.) In other | |||||
words, apply common sense.</para> | |||||
<para>Changes to the security branches (for example, | |||||
<literal>releng/9.3</literal>) must be approved by a | |||||
member of the &a.security-officer;, or in some cases, by a | |||||
member of the &a.re;.</para> | |||||
</listitem> | </listitem> | ||||
<listitem> | |||||
<para>Do not fight in public with other committers; it looks | |||||
bad.</para> | |||||
<para>This project has a public image to uphold and that | |||||
image is very important to all of us, especially if we are | |||||
to continue to attract new members. There will be | |||||
occasions when, despite everyone's very best attempts at | |||||
self-control, tempers are lost and angry words are | |||||
exchanged. The best thing that can be done in such cases | |||||
is to minimize the effects of this until everyone has | |||||
cooled back down. That means that you should not air your | |||||
angry words in public and you should not forward private | |||||
correspondence or other private communications to public | |||||
mailing lists, mail aliases, instant messaging channels or | |||||
social media sites. What people say one-to-one is often | |||||
much less sugar-coated than what they would say in public, | |||||
and such communications therefore have no place there - | |||||
they only serve to inflame an already bad situation. If | |||||
the person sending you a flame-o-gram at least had the | |||||
grace to send it privately, then have the grace to keep it | |||||
private yourself. If you feel you are being unfairly | |||||
treated by another developer, and it is causing you | |||||
anguish, bring the matter up with core rather than taking | |||||
it public. Core will do its best to play peace makers and | |||||
get things back to sanity. In cases where the dispute | |||||
involves a change to the codebase and the participants do | |||||
not appear to be reaching an amicable agreement, core may | |||||
appoint a mutually-agreeable third party to resolve the | |||||
dispute. All parties involved must then agree to be bound | |||||
by the decision reached by this third party.</para> | |||||
</listitem> | |||||
<listitem> | |||||
<para>Respect all code freezes and read the | |||||
<literal>committers</literal> and | |||||
<literal>developers</literal> mailing list on a timely | |||||
basis so you know when a code freeze is in effect.</para> | |||||
<para>Committing unapproved changes during a code freeze is | |||||
a really big mistake and committers are expected to keep | |||||
up-to-date on what is going on before jumping in after a | |||||
long absence and committing 10 megabytes worth of | |||||
accumulated stuff. People who abuse this on a regular | |||||
basis will have their commit privileges suspended until | |||||
they get back from the &os; Happy Reeducation Camp we | |||||
run in Greenland.</para> | |||||
</listitem> | |||||
<listitem> | |||||
<para>When in doubt on any procedure, ask first!</para> | |||||
<para>Many mistakes are made because someone is in a hurry | |||||
and just assumes they know the right way of doing | |||||
something. If you have not done it before, chances are | |||||
good that you do not actually know the way we do things | |||||
and really need to ask first or you are going to | |||||
completely embarrass yourself in public. There is no | |||||
shame in asking | |||||
<quote>how in the heck do I do this?</quote> We already | |||||
know you are an intelligent person; otherwise, you would | |||||
not be a committer.</para> | |||||
</listitem> | |||||
<listitem> | |||||
<para>Test your changes before committing them.</para> | |||||
<!-- XXX Needs update re sparc64 + pc98 | |||||
Also, needs more details on which machines are available for testing | |||||
--> | |||||
<para>This may sound obvious, but if it really were so | |||||
obvious then we probably would not see so many cases of | |||||
people clearly not doing this. If your changes are to the | |||||
kernel, make sure you can still compile both GENERIC and | |||||
LINT. If your changes are anywhere else, make sure you | |||||
can still make world. If your changes are to a branch, | |||||
make sure your testing occurs with a machine which is | |||||
running that code. If you have a change which also may | |||||
break another architecture, be sure and test on all | |||||
supported architectures. Please refer to the | |||||
<link xlink:href="http://www.freebsd.org/internal/">&os; | |||||
Internal Page</link> for a list of available resources. | |||||
As other architectures are added to the &os; supported | |||||
platforms list, the appropriate shared testing resources | |||||
will be made available.</para> | |||||
</listitem> | |||||
<listitem> | |||||
<para>Do not commit to anything under the | |||||
<filename>src/contrib</filename>, | |||||
<filename>src/crypto</filename>, and | |||||
<filename>src/sys/contrib</filename> trees without | |||||
<emphasis>explicit</emphasis> approval from the respective | |||||
maintainer(s).</para> | |||||
<para>The trees mentioned above are for contributed software | |||||
usually imported onto a vendor branch. Committing | |||||
something there, even if it does not take the file off the | |||||
vendor branch, may cause unnecessary headaches for those | |||||
responsible for maintaining that particular piece of | |||||
software. Thus, unless you have | |||||
<emphasis>explicit</emphasis> approval from the maintainer | |||||
(or you are the maintainer), do <emphasis>not</emphasis> | |||||
commit there!</para> | |||||
<para>Please note that this does not mean you should not try | |||||
to improve the software in question; you are still more | |||||
than welcome to do so. Ideally, you should submit your | |||||
patches to the vendor. If your changes are | |||||
&os;-specific, talk to the maintainer; they may be | |||||
willing to apply them locally. But whatever you do, do | |||||
<emphasis>not</emphasis> commit there by yourself!</para> | |||||
<para>Contact the &a.core; if you wish to take up | |||||
maintainership of an unmaintained part of the tree.</para> | |||||
</listitem> | |||||
</orderedlist> | |||||
</sect2> | |||||
<sect2> | |||||
<title>Other Suggestions</title> | |||||
<para>When committing documentation changes, use a spell checker | |||||
before committing. For all XML docs, verify that the | |||||
formatting directives are correct by running | |||||
<command>make lint</command> and | |||||
<package>textproc/igor</package>.</para> | |||||
<para>For manual pages, run <package>sysutils/manck</package> | |||||
bcrUnsubmitted Not Done Inline ActionsNowadays, running mandoc -Tlint is recommended to catch bugs in man pages. bcr: Nowadays, running `mandoc -Tlint` is recommended to catch bugs in man pages. | |||||
and <package>textproc/igor</package> | |||||
over the manual page to verify all of the cross | |||||
references and file references are correct and that the man | |||||
page has all of the appropriate <varname>MLINK</varname>s | |||||
installed.</para> | |||||
<para>Do not mix style fixes with new functionality. A style | |||||
fix is any change which does not modify the functionality of | |||||
the code. Mixing the changes obfuscates the functionality | |||||
change when asking for differences between revisions, which | |||||
can hide any new bugs. Do not include whitespace changes with | |||||
bcrUnsubmitted Not Done Inline ActionsMixing whitespace with content changes is less of a problem now that we have the PO system for translators. bcr: Mixing whitespace with content changes is less of a problem now that we have the PO system for… | |||||
content changes in commits to <filename>doc/</filename> . | |||||
bcrUnsubmitted Not Done Inline ActionsSuperfluous space before sentence stop. bcr: Superfluous space before sentence stop. | |||||
The extra clutter in the diffs | |||||
makes the translators' job much more difficult. Instead, make | |||||
any style or whitespace changes in separate commits that are | |||||
clearly labeled as such in the commit message.</para> | |||||
</sect2> | |||||
<sect2> | |||||
<title>Deprecating Features</title> | |||||
<para>When it is necessary to remove functionality from software | |||||
in the base system the following guidelines should be followed | |||||
whenever possible:</para> | |||||
<orderedlist> | |||||
<listitem> | |||||
<para>Mention is made in the manual page and possibly the | |||||
release notes that the option, utility, or interface is | |||||
deprecated. Use of the deprecated feature generates a | |||||
warning.</para> | |||||
</listitem> | |||||
<listitem> | |||||
<para>The option, utility, or interface is preserved until | |||||
the next major (point zero) release.</para> | |||||
</listitem> | |||||
<listitem> | |||||
<para>The option, utility, or interface is removed and no | |||||
longer documented. It is now obsolete. It is also | |||||
generally a good idea to note its removal in the release | |||||
notes.</para> | |||||
</listitem> | |||||
</orderedlist> | |||||
</sect2> | |||||
<sect2> | |||||
<title>Privacy and Confidentiality</title> | |||||
<orderedlist> | |||||
<listitem> | |||||
<para>Most &os; business is done in public.</para> | |||||
<para>&os; is an <emphasis>open</emphasis> project. Which | |||||
means that not only can anyone use the source code, but | |||||
that most of the development process is open to public | |||||
scrutiny.</para> | |||||
</listitem> | |||||
<listitem> | |||||
<para>Certain sensitive matters must remain private or | |||||
held under embargo.</para> | |||||
<para>There unfortunately cannot be complete transparency. | |||||
As a &os; developer you will have a certain degree of | |||||
privileged access to information. Consequently you are | |||||
expected to respect certain requirements for | |||||
confidentiality. Sometimes the need for confidentiality | |||||
comes from external collaborators or has a specific time | |||||
limit. Mostly though, it is a matter of not releasing | |||||
private communications.</para> | |||||
</listitem> | |||||
<listitem> | |||||
<para>The Security Officer has sole control over the | |||||
release of security advisories.</para> | |||||
<para>Where there are security problems that affect many | |||||
different operating systems, &os; frequently depends on | |||||
early access in order to be able to prepare advisories for | |||||
coordinated release. Unless &os; developers can be | |||||
trusted to maintain security, such early access will not | |||||
be made available. The Security Officer is responsible | |||||
for controlling pre-release access to information about | |||||
vulnerabilities, and for timing the release of all | |||||
advisories. He may request help under condition of | |||||
confidentiality from any developer with relevant knowledge | |||||
in order to prepare security fixes.</para> | |||||
</listitem> | |||||
<listitem> | |||||
<para>Communications with Core are kept confidential for as | |||||
long as necessary.</para> | |||||
<para>Communications to core will initially be treated as | |||||
confidential. Eventually however, most of Core's business | |||||
will be summarized into the monthly or quarterly core | |||||
reports. Care will be taken to avoid publicising any | |||||
sensitive details. Records of some particularly sensitive | |||||
subjects may not be reported on at all and will be | |||||
retained only in Core's private archives.</para> | |||||
</listitem> | |||||
<listitem> | |||||
<para>Non-disclosure Agreements may be required for access | |||||
to certain commercially sensitive data.</para> | |||||
<para>Access to certain commercially sensitive data may | |||||
only be available under a Non-Disclosure Agreement. The | |||||
FreeBSD Foundation legal staff must be consulted before | |||||
any binding agreements are entered into.</para> | |||||
</listitem> | |||||
<listitem> | |||||
<para>Private communications should not be made | |||||
public without permission.</para> | |||||
<para>Beyond the specific requirements above there is a | |||||
general expectation not to publish private communications | |||||
between developers without the consent of all parties | |||||
involved. Ask permission before forwarding a message onto | |||||
a public mailing list, or posting it to a forum or website | |||||
that can be accessed by other than the original | |||||
correspondents.</para> | |||||
</listitem> | |||||
<listitem> | |||||
<para>Communications on project-only or restricted access | |||||
channels should be treated as private.</para> | |||||
<para>Similarly to personal communications, certain | |||||
internal communications channels, including &os; Committer | |||||
only mailing lists and restricted access IRC channels | |||||
should be considered as private communications. You need | |||||
permission in order to publish material from these | |||||
sources.</para> | |||||
</listitem> | |||||
<listitem> | |||||
<para>Core may approve publication.</para> | |||||
<para>Where it is impractical to obtain permission due to | |||||
the number of correspondents or where permission to | |||||
publish is unreasonably withheld, Core may approve release | |||||
of such private matters that merit more general | |||||
publication.</para> | |||||
</listitem> | |||||
</orderedlist> | |||||
</sect2> | |||||
</sect1> | |||||
<sect1 xml:id="developer.relations"> | |||||
<title>Developer Relations</title> | |||||
<para>If you are 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. If you see 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. If, however, you are | |||||
about to modify something which is clearly being actively | |||||
maintained by someone else (and it is only by watching the | |||||
<literal><replaceable>repository</replaceable>-committers</literal> | |||||
mailing list that you can really get a feel for just what is and | |||||
is not) then consider sending the change to them instead, just | |||||
as you would have before becoming a committer. For ports, you | |||||
should contact the listed <varname>MAINTAINER</varname> in the | |||||
<filename>Makefile</filename>. For other parts of the | |||||
repository, if you are unsure who the active maintainer might | |||||
be, it may help to 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 <systemitem>freefall</systemitem> at | |||||
<filename>~eadler/bin/whodid</filename>. If your queries go | |||||
unanswered or the committer otherwise indicates a lack of | |||||
interest in the area affected, go ahead and commit it.</para> | |||||
<note> | |||||
<para>Avoid sending private emails to maintainers. Other people | |||||
might be interested in the conversation, not just the final | |||||
output.</para> | |||||
</note> | |||||
<para>If you are unsure about a commit for any reason at all, have | |||||
it reviewed by <literal>-hackers</literal> before committing. | |||||
Better to have it flamed then and there rather than when it is | |||||
part of the repository. If you do happen to commit something | |||||
which results in controversy erupting, you may also wish to | |||||
consider backing the change out again until the matter is | |||||
settled. Remember – with a version control system we can | |||||
always change it back.</para> | |||||
<para>Do not impugn the intentions of someone you disagree with. | |||||
If they see a different solution to a problem than you, or even | |||||
a different problem, it is not because they are stupid, because | |||||
they have questionable parentage, or because they are trying to | |||||
destroy your hard work, personal image, or &os;, but simply | |||||
because they have a different outlook on the world. Different | |||||
is good.</para> | |||||
<para>Disagree honestly. Argue your position from its merits, | |||||
be honest about any shortcomings it may have, and be open to | |||||
seeing their solution, or even their vision of the problem, | |||||
with an open mind.</para> | |||||
<para>Accept correction. We are all fallible. When you have made | |||||
a mistake, apologize and get on with life. Do not beat up | |||||
yourself, and certainly do not beat up others for your mistake. | |||||
Do not waste time on embarrassment or recrimination, just fix | |||||
the problem and move on.</para> | |||||
<para>Ask for help. Seek out (and give) peer reviews. One of | |||||
the ways open source software is supposed to excel is in the | |||||
number of eyeballs applied to it; this does not apply if nobody | |||||
will review code.</para> | |||||
</sect1> | |||||
<sect1 xml:id="if-in-doubt"> | |||||
<title>If in Doubt...</title> | |||||
<para>When you are not sure about something, whether it be a | |||||
technical issue or a project convention be sure to ask. If you | |||||
stay silent you will never make progress.</para> | |||||
<para>If it relates to a technical issue ask on the public | |||||
mailing lists. Avoid the temptation to email the individual | |||||
person that knows the answer. This way everyone will be able to | |||||
learn from the question and the answer.</para> | |||||
<para>For project specific or administrative questions you should | |||||
ask, in order:</para> | |||||
<itemizedlist> | |||||
<listitem> | |||||
<para>Your mentor or former mentor.</para> | |||||
</listitem> | |||||
<listitem> | |||||
<para>An experienced committer on IRC, email, etc.</para> | |||||
</listitem> | |||||
<listitem> | |||||
<para>Any team with a "hat", as they should give you a | |||||
definitive answer.</para> | |||||
</listitem> | |||||
<listitem> | |||||
<para>If still not sure, ask on &a.developers;.</para> | |||||
</listitem> | |||||
</itemizedlist> | </itemizedlist> | ||||
<para>Once your question is answered, if no one pointed you to | |||||
documentation that spelled out the answer to your question, | |||||
document it, as others will have the same question.</para> | |||||
</sect1> | |||||
<sect1 xml:id="archs"> | |||||
<title>Support for Multiple Architectures</title> | |||||
<para>&os; is a highly portable operating system intended to | |||||
function on many different types of hardware architectures. | |||||
Maintaining clean separation of Machine Dependent (MD) and | |||||
Machine Independent (MI) code, as well as minimizing MD code, is | |||||
an important part of our strategy to remain agile with regards | |||||
to current hardware trends. Each new hardware architecture | |||||
supported by &os; adds substantially to the cost of code | |||||
maintenance, toolchain support, and release engineering. It | |||||
also dramatically increases the cost of effective testing of | |||||
kernel changes. As such, there is strong motivation to | |||||
differentiate between classes of support for various | |||||
architectures while remaining strong in a few key architectures | |||||
that are seen as the &os; <quote>target audience</quote>.</para> | |||||
<sect2> | |||||
<title>Policy on Multiple Architectures</title> | |||||
<para>&os; has added several new architecture ports during | |||||
recent release cycles and is truly no longer an &i386; centric | |||||
operating system. In an effort to make it easier to keep | |||||
&os; portable across the platforms we support, core has | |||||
developed the following mandate:</para> | |||||
<blockquote> | |||||
<para>Our 32-bit reference platform is &arch.i386;, and our | |||||
64-bit reference platform is &arch.amd64;. Major design | |||||
work (including major API and ABI changes) must prove | |||||
itself on at least one 32-bit and at least one 64-bit | |||||
platform, preferably the primary reference platforms, | |||||
before it may be committed to the source tree.</para> | |||||
</blockquote> | |||||
<para>The &arch.i386; and &arch.amd64; platforms were chosen | |||||
due to being more readily available to developers and as | |||||
representatives of more diverse processor and system designs - | |||||
big versus little endian, register file versus register stack, | |||||
different DMA and cache implementations, hardware page tables | |||||
versus software TLB management etc.</para> | |||||
<para>We will continue to re-evaluate this policy as cost and | |||||
availability of the 64-bit platforms change.</para> | |||||
<para>Developers should also be aware of our Tier Policy for | |||||
the long term support of hardware architectures. The rules | |||||
here are intended to provide guidance during the development | |||||
process, and are distinct from the requirements for features | |||||
and architectures listed in that section. The Tier rules for | |||||
feature support on architectures at release-time are more | |||||
strict than the rules for changes during the development | |||||
process.</para> | |||||
</sect2> | </sect2> | ||||
<sect2> | |||||
<title>Statement of General Intent</title> | |||||
<para>The &os; Project targets "production quality commercial | |||||
off-the-shelf (COTS) workstation, server, and high-end | |||||
embedded systems". By retaining a focus on a narrow set of | |||||
architectures of interest in these environments, the &os; | |||||
Project is able to maintain high levels of quality, stability, | |||||
and performance, as well as minimize the load on various | |||||
support teams on the project, such as the ports team, | |||||
documentation team, security officer, and release engineering | |||||
teams. Diversity in hardware support broadens the options for | |||||
&os; consumers by offering new features and usage | |||||
opportunities (such as support for 64-bit CPUs, use in | |||||
embedded environments, etc.), but these benefits must always | |||||
be carefully considered in terms of the real-world maintenance | |||||
cost associated with additional platform support.</para> | |||||
<para>The &os; Project differentiates platform targets into | |||||
four tiers. Each tier includes a specification of the | |||||
requirements for an architecture to be in that tier, | |||||
as well as specifying the obligations of developers with | |||||
regards to the platform. In addition, a policy is defined | |||||
regarding the circumstances required to change the tier | |||||
of an architecture.</para> | |||||
</sect2> | |||||
<sect2> | |||||
<title>Tier 1: Fully Supported Architectures</title> | |||||
<para>Tier 1 platforms are fully supported by the security | |||||
officer, release engineering, and toolchain maintenance staff. | |||||
New features added to the operating system must be fully | |||||
functional across all Tier 1 architectures for every release | |||||
(features which are inherently architecture-specific, such as | |||||
support for hardware device drivers, may be exempt from this | |||||
requirement). In general, all Tier 1 platforms must have | |||||
build and Tinderbox support either in the FreeBSD.org cluster, | |||||
or be easily available for all developers. Embedded platforms | |||||
may substitute an emulator available in the &os; cluster | |||||
for actual hardware.</para> | |||||
<para>Tier 1 architectures are expected to be Production Quality | |||||
with respects to all aspects of the &os; operating system, | |||||
including installation and development environments.</para> | |||||
<para>Tier 1 architectures are expected to be completely | |||||
integrated into the source tree and have all features | |||||
necessary to produce an entire system relevant for that target | |||||
architecture. Tier 1 architectures generally have at least 6 | |||||
active developers.</para> | |||||
<para>Tier 1 architectures are expected to be fully supported by | |||||
the ports system. All the ports should build on a Tier 1 | |||||
platform, or have the appropriate filters to prevent the | |||||
inappropriate ones from building there. The packaging system | |||||
must support all Tier 1 architectures. To ensure an | |||||
architecture's Tier 1 status, proponents of that architecture | |||||
must show that all relevant packages can be built on that | |||||
platform.</para> | |||||
<para>Tier 1 embedded architectures must be able to cross-build | |||||
packages on at least one other Tier 1 architecture. The | |||||
packages must be the most relevant for the platform, but may | |||||
be a non-empty subset of those that build natively.</para> | |||||
<para>Tier 1 architectures must be fully documented. All basic | |||||
operations need to be covered by the handbook or other | |||||
documents. All relevant integration documentation must also | |||||
be integrated into the tree, or readily available.</para> | |||||
<para>Current Tier 1 platforms are &arch.i386; and | |||||
&arch.amd64;.</para> | |||||
</sect2> | |||||
<sect2> | |||||
<title>Tier 2: Developmental Architectures</title> | |||||
<para>Tier 2 platforms are not supported by the security officer | |||||
and release engineering teams. Platform maintainers are | |||||
responsible for toolchain support in the tree. The toolchain | |||||
maintainers are expected to work with the platform maintainers | |||||
to refine these changes. Major new toolchain components are | |||||
allowed to break support for Tier 2 architectures if the | |||||
&os;-local changes have not been incorporated upstream. | |||||
The toolchain maintainers are expected to provide prompt | |||||
review of any proposed changes and cannot block, through their | |||||
inaction, changes going into the tree. New features added to | |||||
&os; should be feasible to implement on these platforms, | |||||
but an implementation is not required before the feature may | |||||
be added to the &os; source tree. New features that may be | |||||
difficult to implement on Tier 2 architectures should provide | |||||
a means of disabling them on those architectures. The | |||||
implementation of a Tier 2 architecture may be committed to | |||||
the main &os; tree as long as it does not interfere with | |||||
production work on Tier 1 platforms, or substantially with | |||||
other Tier 2 platforms. Before a Tier 2 platform can be added | |||||
to the &os; base source tree, the platform must be able to | |||||
boot multi-user on actual hardware. Generally, there must be | |||||
at least three active developers working on the | |||||
platform.</para> | |||||
<para>Tier 2 architectures are usually systems targeted at Tier | |||||
1 support, but that are still under development. | |||||
Architectures reaching end of life may also be moved from Tier | |||||
1 status to Tier 2 status as the availability of resources to | |||||
continue to maintain the system in a Production Quality state | |||||
diminishes. Well supported niche architectures may also be | |||||
Tier 2.</para> | |||||
<para>Tier 2 architectures have basic support for them | |||||
integrated into the ports infrastructure. They may have cross | |||||
compilation support added, at the discretion of portmgr. Some | |||||
ports must built natively into packages if the package system | |||||
supports that architecture. If not integrated into the base | |||||
system, some external patches for the architecture for ports | |||||
must be available.</para> | |||||
<para>Tier 2 architectures can be integrated into the &os; | |||||
handbook. The basics for how to get a system running must be | |||||
documented, although not necessarily for every single board or | |||||
system a Tier 2 architecture supports. The supported hardware | |||||
list must exist and should be relatively recent. It should be | |||||
integrated into the &os; documentation.</para> | |||||
<para>Current Tier 2 platforms are &arch.arm;, &arch.arm64;, | |||||
&arch.ia64; (through &os; 10), | |||||
&arch.pc98;, &arch.powerpc;, and &arch.sparc64;.</para> | |||||
</sect2> | |||||
<sect2> | |||||
<title>Tier 3: Experimental Architectures</title> | |||||
<para>Tier 3 platforms are not supported by the security officer | |||||
and release engineering teams. At the discretion of the | |||||
toolchain maintainers, they may be supported in the toolchain. | |||||
Tier 3 platforms are architectures in the early stages of | |||||
development, for non-mainstream hardware platforms, or which | |||||
are considered legacy systems unlikely to see broad future | |||||
use. Initial support for Tier 3 platforms should be worked on | |||||
in external SCM repositories. | |||||
The transition to &os;'s subversion should take place after | |||||
the platform boots multi-user on hardware; sharing via | |||||
subversion is needed for wider exposure; and multiple | |||||
developers are actively working on the platform. | |||||
Platforms that transition to Tier 3 status may be | |||||
removed from the tree if they are no longer actively supported | |||||
by the &os; developer community at the discretion of the | |||||
release engineer.</para> | |||||
<para>Tier 3 platforms may have ports support, either integrated | |||||
or external, but do not require it.</para> | |||||
<para>Tier 3 platforms must have the basics documented for how | |||||
to build a kernel and how to boot it on at least one target | |||||
hardware or emulation environment. This documentation need | |||||
not be integrated into the &os; tree.</para> | |||||
<para>Current Tier 3 platforms are &arch.mips;, and | |||||
&arch.riscv;.</para> | |||||
</sect2> | |||||
<sect2> | |||||
<title>Tier 4: Unsupported Architectures</title> | |||||
editor_callfortesting.orgAuthorUnsubmitted Not Done Inline ActionsAll of this "architecture" talk is a bit odd. Move? editor_callfortesting.org: All of this "architecture" talk is a bit odd. Move? | |||||
bcrUnsubmitted Not Done Inline ActionsYes, the developers handbook might be a better place for it, as it is more relevant for people with src bits. bcr: Yes, the developers handbook might be a better place for it, as it is more relevant for people… | |||||
<para>Tier 4 systems are not supported in any form by the | |||||
project.</para> | |||||
<para>All systems not otherwise classified into a support tier | |||||
are Tier 4 systems. The &arch.ia64; platform is transitioning | |||||
to Tier 4 status in &os; 11.</para> | |||||
</sect2> | |||||
<sect2> | |||||
<title>Policy on Changing the Tier of an Architecture</title> | |||||
<para>Systems may only be moved from one tier to another by | |||||
approval of the &os; Core Team, which shall make that | |||||
decision in collaboration with the Security Officer, Release | |||||
Engineering, and toolchain maintenance teams.</para> | |||||
</sect2> | |||||
</sect1> | </sect1> | ||||
<sect1 xml:id="subversion-primer"> | <sect1 xml:id="subversion-primer"> | ||||
<title>Subversion Primer</title> | <title>Subversion Primer</title> | ||||
editor_callfortesting.orgAuthorUnsubmitted Not Done Inline ActionsExtract and centralize elsewhere? editor_callfortesting.org: Extract and centralize elsewhere? | |||||
<para>It is assumed that you are already familiar with the basic | <para>It is assumed that you are already familiar with the basic | ||||
operation of Subversion. If not, start by reading the | operation of Subversion. If not, start by reading the | ||||
<link xlink:href="http://svnbook.red-bean.com/">Subversion | <link xlink:href="http://svnbook.red-bean.com/">Subversion | ||||
Book</link>.</para> | Book</link>.</para> | ||||
<sect2 xml:id="svn-intro"> | <sect2 xml:id="svn-intro"> | ||||
<title>Introduction</title> | <title>Introduction</title> | ||||
<para>The &os; source repository switched from | <para>The &os; source repository switched from | ||||
<acronym>CVS</acronym> to Subversion on May 31st, 2008. The | <acronym>CVS</acronym> to Subversion on May 31st, 2008. The | ||||
first real <acronym>SVN</acronym> commit is | first real <acronym>SVN</acronym> commit is | ||||
<emphasis>r179447</emphasis>.</para> | <emphasis>r179447</emphasis>.</para> | ||||
<para>The &os; <literal>doc/www</literal> repository switched | <para>The &os; <literal>doc/www</literal> repository switched | ||||
from <acronym>CVS</acronym> to Subversion on May 19th, 2012. | from <acronym>CVS</acronym> to Subversion on May 19th, 2012. | ||||
The first real <acronym>SVN</acronym> commit is | The first real <acronym>SVN</acronym> commit is | ||||
<emphasis>r38821</emphasis>.</para> | <emphasis>r38821</emphasis>.</para> | ||||
<para>The &os; <literal>ports</literal> repository switched | <para>The &os; <literal>ports</literal> repository switched | ||||
from <acronym>CVS</acronym> to Subversion on July 14th, 2012. | from <acronym>CVS</acronym> to Subversion on July 14th, 2012. | ||||
The first real <acronym>SVN</acronym> commit is | The first real <acronym>SVN</acronym> commit is | ||||
<emphasis>r300894</emphasis>.</para> | <emphasis>r300894</emphasis>.</para> | ||||
<para>Subversion can be installed from the &os; Ports | <para>Subversion can be installed from the &os; Ports | ||||
Collection by issuing these commands:</para> | Collection by issuing these commands:</para> | ||||
<screen>&prompt.root; <userinput>pkg install subversion</userinput></screen> | <screen>&prompt.root; <userinput>pkg install subversion</userinput></screen> | ||||
</sect2> | </sect2> | ||||
<sect2 xml:id="svn-getting-started"> | <sect2 xml:id="svn-getting-started"> | ||||
<title>Getting Started</title> | <title>Getting Started</title> | ||||
<para>There are a few ways to obtain a working copy of the tree | <para>There are a few ways to obtain a working copy of the tree | ||||
from Subversion. This section will explain them.</para> | from Subversion. This section will explain them.</para> | ||||
<sect3 xml:id="svn-getting-started-direct-checkout"> | <sect3 xml:id="svn-getting-started-direct-checkout"> | ||||
<title>Direct Checkout</title> | <title>Direct Checkout</title> | ||||
<para>The first is to check out directly from the main | <para>The first is to check out directly from the main | ||||
repository. For the <literal>src</literal> tree, | repository. For the <literal>src</literal> tree, | ||||
use:</para> | use:</para> | ||||
<screen>&prompt.user; <userinput>svn checkout svn+ssh://repo.freebsd.org/base/head /usr/src</userinput></screen> | <screen>&prompt.user; <userinput>svn checkout svn+ssh://repo.freebsd.org/base/head /usr/src</userinput></screen> | ||||
<para>For the <literal>doc</literal> tree, use:</para> | <para>For the <literal>doc</literal> tree, use:</para> | ||||
<screen>&prompt.user; <userinput>svn checkout svn+ssh://repo.freebsd.org/doc/head /usr/doc</userinput></screen> | <screen>&prompt.user; <userinput>svn checkout svn+ssh://repo.freebsd.org/doc/head /usr/doc</userinput></screen> | ||||
<para>For the <literal>ports</literal> tree, use:</para> | <para>For the <literal>ports</literal> tree, use:</para> | ||||
<screen>&prompt.user; <userinput>svn checkout svn+ssh://repo.freebsd.org/ports/head /usr/ports</userinput></screen> | <screen>&prompt.user; <userinput>svn checkout svn+ssh://repo.freebsd.org/ports/head /usr/ports</userinput></screen> | ||||
<note> | <note> | ||||
<para>Though the remaining examples in this document are | <para>Though the remaining examples in this document are | ||||
written with the workflow of working with the | written with the workflow of working with the | ||||
<literal>src</literal> tree in mind, the underlying | <literal>src</literal> tree in mind, the underlying | ||||
concepts are the same for working with the | concepts are the same for working with the | ||||
<literal>doc</literal> and the <literal>ports</literal> | <literal>doc</literal> and the <literal>ports</literal> | ||||
tree. | tree. | ||||
Ports related Subversion operations are listed in | Ports related Subversion operations are listed in | ||||
<xref linkend="ports"/>.</para> | <xref linkend="ports"/>.</para> | ||||
</note> | </note> | ||||
<para>The above command will check out a | <para>The above command will check out a | ||||
<literal>CURRENT</literal> source tree as | <literal>CURRENT</literal> source tree as | ||||
<filename><replaceable>/usr/src/</replaceable></filename>, | <filename><replaceable>/usr/src/</replaceable></filename>, | ||||
which can be any target directory on the local filesystem. | which can be any target directory on the local filesystem. | ||||
Omitting the final argument of that command causes the | Omitting the final argument of that command causes the | ||||
working copy, in this case, to be named <quote>head</quote>, | working copy, in this case, to be named <quote>head</quote>, | ||||
but that can be renamed safely.</para> | but that can be renamed safely.</para> | ||||
<para><literal>svn+ssh</literal> means the | <para><literal>svn+ssh</literal> means the | ||||
<acronym>SVN</acronym> protocol tunnelled over | <acronym>SVN</acronym> protocol tunnelled over | ||||
<acronym>SSH</acronym>. The name of the server is | <acronym>SSH</acronym>. The name of the server is | ||||
<literal>repo.freebsd.org</literal>, <literal>base</literal> | <literal>repo.freebsd.org</literal>, <literal>base</literal> | ||||
is the path to the repository, and <literal>head</literal> | is the path to the repository, and <literal>head</literal> | ||||
is the subdirectory within the repository.</para> | is the subdirectory within the repository.</para> | ||||
<para>If your &os; login name is different from your login | <para>If your &os; login name is different from your login | ||||
name on your local machine, you must either include it in | name on your local machine, you must either include it in | ||||
the <acronym>URL</acronym> (for example | the <acronym>URL</acronym> (for example | ||||
<literal>svn+ssh://jarjar@repo.freebsd.org/base/head</literal>), | <literal>svn+ssh://jarjar@repo.freebsd.org/base/head</literal>), | ||||
or add an entry to your <filename>~/.ssh/config</filename> | or add an entry to your <filename>~/.ssh/config</filename> | ||||
in the form:</para> | in the form:</para> | ||||
<programlisting>Host repo.freebsd.org | <programlisting>Host repo.freebsd.org | ||||
User jarjar</programlisting> | User jarjar</programlisting> | ||||
<para>This is the simplest method, but it is hard to tell just | <para>This is the simplest method, but it is hard to tell just | ||||
yet how much load it will place on the repository.</para> | yet how much load it will place on the repository.</para> | ||||
<note> | <note> | ||||
<para>The <command>svn diff</command> does not require | <para>The <command>svn diff</command> does not require | ||||
access to the server as <acronym>SVN</acronym> stores a | access to the server as <acronym>SVN</acronym> stores a | ||||
reference copy of every file in the working copy. This, | reference copy of every file in the working copy. This, | ||||
however, means that Subversion working copies are very | however, means that Subversion working copies are very | ||||
large in size.</para> | large in size.</para> | ||||
</note> | </note> | ||||
▲ Show 20 Lines • Show All 249 Lines • ▼ Show 20 Lines | &prompt.user; <userinput>svn up --set-depth=infinity base/stable/7</userinput></screen> | ||||
<title>Anonymous Checkout</title> | <title>Anonymous Checkout</title> | ||||
<para>It is possible to anonymously check out the &os; | <para>It is possible to anonymously check out the &os; | ||||
repository with Subversion. This will give access to a | repository with Subversion. This will give access to a | ||||
read-only tree that can be updated, but not committed back | read-only tree that can be updated, but not committed back | ||||
to the main repository. To do this, use the following | to the main repository. To do this, use the following | ||||
command:</para> | command:</para> | ||||
<screen>&prompt.user; <userinput>svn co https://svn.FreeBSD.org/base/head /usr/src</userinput></screen> | <screen>&prompt.user; <userinput>svn co http://svn.freebsd.org/base/head /usr/src</userinput></screen> | ||||
<para>More details on using Subversion this way can be found | <para>More details on using Subversion this way can be found | ||||
editor_callfortesting.orgAuthorUnsubmitted Not Done Inline ActionsThere are MORE? editor_callfortesting.org: There are MORE? | |||||
in <link xlink:href="&url.books.handbook;/svn.html">Using | in <link xlink:href="&url.books.handbook;/svn.html">Using | ||||
Subversion</link>.</para> | Subversion</link>.</para> | ||||
</sect3> | </sect3> | ||||
<sect3 xml:id="svn-daily-use-updating-the-tree"> | <sect3 xml:id="svn-daily-use-updating-the-tree"> | ||||
<title>Updating the Tree</title> | <title>Updating the Tree</title> | ||||
<para>To update a working copy to either the latest revision, | <para>To update a working copy to either the latest revision, | ||||
▲ Show 20 Lines • Show All 1,340 Lines • ▼ Show 20 Lines | &prompt.user; <userinput>svn revert -R .</userinput></screen> | ||||
<filename>~/.subversion/config</filename> configuration file. | <filename>~/.subversion/config</filename> configuration file. | ||||
For example:</para> | For example:</para> | ||||
<programlisting>freebsd-sponsored-by = The FreeBSD Foundation | <programlisting>freebsd-sponsored-by = The FreeBSD Foundation | ||||
freebsd-mfc-after = 2 weeks</programlisting> | freebsd-mfc-after = 2 weeks</programlisting> | ||||
</sect2> | </sect2> | ||||
</sect1> | </sect1> | ||||
<sect1 xml:id="conventions"> | |||||
<title>Setup, Conventions, and Traditions</title> | |||||
<para>There are a number of things to do as a new developer. | |||||
The first set of steps is specific to committers only. These | |||||
steps must be done by a mentor for those who are not | |||||
committers.</para> | |||||
<sect2 xml:id="conventions-committers"> | |||||
<title>For New Committers</title> | |||||
<para>Those who have been given commit rights to the &os; | |||||
repositories must follow these steps.</para> | |||||
<itemizedlist xml:id="commit-notes"> | |||||
<listitem> | |||||
<para>Get mentor approval before committing each of these | |||||
changes!</para> | |||||
</listitem> | |||||
<listitem> | |||||
<para>The <filename>.ent</filename> and | |||||
<filename>.xml</filename> files mentioned below exist in | |||||
the &os; Documentation Project SVN repository at <link | |||||
xlink:href="svn.FreeBSD.org/doc/"><literal>svn.FreeBSD.org/doc/</literal></link>.</para> | |||||
</listitem> | |||||
<listitem> | |||||
<para>New files that do not have the | |||||
<literal>FreeBSD=%H</literal> | |||||
<command>svn:keywords</command> property will be rejected | |||||
when attempting to commit them to the repository. Be sure | |||||
to read | |||||
<xref linkend="svn-daily-use-adding-and-removing"/> | |||||
regarding adding and removing files. Verify that | |||||
<filename>~/.subversion/config</filename> contains the | |||||
necessary <quote>auto-props</quote> entries from | |||||
<filename>auto-props.txt</filename> mentioned | |||||
there.</para> | |||||
</listitem> | |||||
<listitem> | |||||
<para>All <filename>src</filename> commits should go to | |||||
&os.current; first before being merged to &os.stable;. | |||||
The &os.stable; branch must maintain | |||||
<acronym>ABI</acronym> and <acronym>API</acronym> | |||||
compatibility with earlier versions of that branch. Do | |||||
not merge changes that break this compatibility.</para> | |||||
</listitem> | |||||
</itemizedlist> | |||||
<procedure xml:id="commit-steps"> | |||||
<title>Steps for New Committers</title> | |||||
<step> | |||||
<title>Add an Author Entity</title> | |||||
<para><filename>doc/head/share/xml/authors.ent</filename> | |||||
— Add an author entity. Later steps depend on this | |||||
entity, and missing this step will cause the | |||||
<filename>doc/</filename> build to fail. This is a | |||||
relatively easy task, but remains a good first test of | |||||
version control skills.</para> | |||||
</step> | |||||
<step> | |||||
<title>Update the List of Developers and | |||||
Contributors</title> | |||||
<para><filename>doc/head/en_US.ISO8859-1/articles/contributors/contrib.committers.xml</filename> | |||||
— | |||||
Add an entry to the <quote>Developers</quote> section | |||||
of the <link | |||||
xlink:href="&url.articles.contributors;/staff-committers.html">Contributors | |||||
List</link>. Entries are sorted by last name.</para> | |||||
<para><filename>doc/head/en_US.ISO8859-1/articles/contributors/contrib.additional.xml</filename> | |||||
— Remove the entry from the | |||||
<quote>Additional Contributors</quote> section. Entries | |||||
are sorted by first name.</para> | |||||
</step> | |||||
<step> | |||||
<title>Add a News Item</title> | |||||
<para><filename>doc/head/share/xml/news.xml</filename> | |||||
— Add an entry. Look for the other entries that | |||||
announce new committers and follow the format. Use the | |||||
date from the commit bit approval email from | |||||
<email>core@FreeBSD.org</email>.</para> | |||||
</step> | |||||
<step> | |||||
<title>Add a <acronym>PGP</acronym> Key</title> | |||||
<para><filename>doc/head/share/pgpkeys/pgpkeys.ent</filename> | |||||
and | |||||
<filename>doc/head/share/pgpkeys/pgpkeys-developers.xml</filename> | |||||
- Add your <acronym>PGP</acronym> or | |||||
Gnu<acronym>PG</acronym> key. Those who do not yet have a | |||||
key should see <xref linkend="pgpkeys-creating"/>.</para> | |||||
<para>&a.des.email; has written a shell script | |||||
(<filename>doc/head/share/pgpkeys/addkey.sh</filename>) to | |||||
make this easier. See the <link | |||||
xlink:href="http://svnweb.FreeBSD.org/doc/head/share/pgpkeys/README">README</link> | |||||
file for more information.</para> | |||||
<para>Use | |||||
<filename>doc/head/share/pgpkeys/checkkey.sh</filename> to | |||||
verify that keys meet minimal best-practices | |||||
standards.</para> | |||||
<para>After adding and checking a key, add both updated | |||||
files to source control and then commit them. Entries in | |||||
this file are sorted by last name.</para> | |||||
<note> | |||||
<para>It is very important to have a current | |||||
<acronym>PGP</acronym>/Gnu<acronym>PG</acronym> key in | |||||
the repository. The key may be required for positive | |||||
identification of a committer. For example, the | |||||
&a.admins; might need it for account recovery. A | |||||
complete keyring of <systemitem | |||||
class="fqdomainname">FreeBSD.org</systemitem> users is | |||||
available for download from <link | |||||
xlink:href="&url.base;/doc/pgpkeyring.txt">http://www.FreeBSD.org/doc/pgpkeyring.txt</link>.</para> | |||||
</note> | |||||
</step> | |||||
<step> | |||||
<title>Update Mentor and Mentee Information</title> | |||||
<para><filename>base/head/share/misc/committers-<replaceable>repository</replaceable>.dot</filename> | |||||
— Add an entry to the current committers section, | |||||
where <replaceable>repository</replaceable> is | |||||
<literal>doc</literal>, <literal>ports</literal>, or | |||||
<literal>src</literal>, depending on the commit privileges | |||||
granted.</para> | |||||
<para>Add an entry for each additional mentor/mentee | |||||
relationship in the bottom section.</para> | |||||
</step> | |||||
<step> | |||||
<title>Generate a <application>Kerberos</application> | |||||
Password</title> | |||||
<para>See <xref linkend="kerberos-ldap"/> to generate or | |||||
set a <application>Kerberos</application> for use with | |||||
other &os; services like the bug tracking database.</para> | |||||
</step> | |||||
<step> | |||||
<title>Optional: Enable Wiki Account</title> | |||||
<para><link xlink:href="http://wiki.freebsd.org">&os; | |||||
Wiki</link> Account — A wiki account allows | |||||
sharing projects and ideas. Those who do not yet have an | |||||
account can contact <email>clusteradm@FreeBSD.org</email> | |||||
to obtain one.</para> | |||||
</step> | |||||
<step> | |||||
<title>Optional: Update Wiki Information</title> | |||||
<para>Wiki Information - After gaining access to the wiki, | |||||
some people add entries to the <link | |||||
xlink:href="http://wiki.freebsd.org/HowWeGotHere">How We | |||||
Got Here</link>, | |||||
<link xlink:href="http://wiki.freebsd.org/IrcNicks">Irc | |||||
Nicks</link>, and <link | |||||
xlink:href="https://wiki.freebsd.org/DogsOfFreeBSD">Dogs | |||||
of FreeBSD</link> pages.</para> | |||||
</step> | |||||
<step> | |||||
<title>Optional: Update Ports with Personal | |||||
Information</title> | |||||
<para><filename>ports/astro/xearth/files/freebsd.committers.markers</filename> | |||||
and | |||||
<filename>src/usr.bin/calendar/calendars/calendar.freebsd</filename> | |||||
- Some people add entries for themselves to these files to | |||||
show where they are located or the date of their | |||||
birthday.</para> | |||||
</step> | |||||
<step> | |||||
<title>Optional: Prevent Duplicate Mailings</title> | |||||
<para>Subscribers to &a.svn-src-all.name;, | |||||
&a.svn-ports-all.name; or &a.svn-doc-all.name; might wish | |||||
to unsubscribe to avoid receiving duplicate copies of | |||||
commit messages and followups.</para> | |||||
</step> | |||||
</procedure> | |||||
</sect2> | |||||
<sect2 xml:id="conventions-everyone"> | |||||
<title>For Everyone</title> | |||||
<procedure xml:id="conventions-everyone-steps"> | |||||
<step> | |||||
<para>Introduce yourself to the other developers, otherwise | |||||
no one will have any idea who you are or what you are | |||||
working on. The introduction need not be a comprehensive | |||||
biography, just write a paragraph or two about who you | |||||
are, what you plan to be working on as a developer in | |||||
&os;, and who will be your mentor. Email this to the | |||||
&a.developers; and you will be on your way!</para> | |||||
</step> | |||||
<step> | |||||
<para>Log into <systemitem>freefall.FreeBSD.org</systemitem> | |||||
and create a | |||||
<filename>/var/forward/<replaceable>user</replaceable></filename> | |||||
(where <replaceable>user</replaceable> is your username) | |||||
file containing the e-mail address where you want mail | |||||
addressed to | |||||
<replaceable>yourusername</replaceable>@FreeBSD.org to be | |||||
forwarded. This includes all of the commit messages as | |||||
well as any other mail addressed to the &a.committers; and | |||||
the &a.developers;. Really large mailboxes which have | |||||
taken up permanent residence on | |||||
<systemitem>freefall</systemitem> may get truncated | |||||
without warning if space needs to be freed, so forward it | |||||
or read it and you will not lose it.</para> | |||||
<para>Due to the severe load dealing with SPAM places on the | |||||
central mail servers that do the mailing list processing | |||||
the front-end server does do some basic checks and will | |||||
drop some messages based on these checks. At the moment | |||||
proper DNS information for the connecting host is the only | |||||
check in place but that may change. Some people blame | |||||
these checks for bouncing valid email. If you want these | |||||
checks turned off for your email you can place a file | |||||
named <filename>.spam_lover</filename> in your home | |||||
directory on <systemitem | |||||
class="fqdomainname">freefall.FreeBSD.org</systemitem> | |||||
to disable the checks for your email.</para> | |||||
</step> | |||||
</procedure> | |||||
<note> | |||||
<para>Those who are developers but not committers will | |||||
not be subscribed to the committers or developers mailing | |||||
lists. The subscriptions are derived from the access | |||||
rights.</para> | |||||
</note> | |||||
</sect2> | |||||
<sect2 xml:id="mentors"> | |||||
<title>Mentors</title> | |||||
<para>All new developers have a mentor assigned to them for | |||||
the first few months. A mentor is responsible for teaching | |||||
the mentee the rules and conventions of the project and | |||||
guiding their first steps in the developer community. The | |||||
mentor is also personally responsible for the mentee's actions | |||||
during this initial period.</para> | |||||
<para>For committers: do not commit anything without first | |||||
getting mentor approval. Document that approval with an | |||||
<literal>Approved by:</literal> line in the commit | |||||
message.</para> | |||||
<para>When the mentor decides that a mentee has learned the | |||||
ropes and is ready to commit on their own, the mentor | |||||
announces it with a commit to | |||||
<filename>conf/mentors</filename>. This file is in the | |||||
<filename>svnadmin</filename> branch of each | |||||
repository:</para> | |||||
<informaltable frame="none"> | |||||
<tgroup cols="2"> | |||||
<tbody> | |||||
<row> | |||||
<entry><literal>src</literal></entry> | |||||
<entry><filename>base/svnadmin/conf/mentors</filename></entry> | |||||
</row> | |||||
<row> | |||||
<entry><literal>doc</literal></entry> | |||||
<entry><filename>doc/svnadmin/conf/mentors</filename></entry> | |||||
</row> | |||||
<row> | |||||
<entry><literal>ports</literal></entry> | |||||
<entry><filename>ports/svnadmin/conf/mentors</filename></entry> | |||||
</row> | |||||
</tbody> | |||||
</tgroup> | |||||
</informaltable> | |||||
</sect2> | |||||
</sect1> | |||||
<sect1 xml:id="commit-log-message"> | <sect1 xml:id="commit-log-message"> | ||||
<title>Commit Log Messages</title> | <title>Commit Log Messages</title> | ||||
<para>This section contains some suggestions and traditions for | <para>This section contains some suggestions and traditions for | ||||
how commit logs are formatted.</para> | how commit logs are formatted.</para> | ||||
emasteUnsubmitted Not Done Inline ActionsThere have been some changes to this content recently that will need to be merged in, although looking at a broader scope I wonder if we shouldn't move this out to a separate document, and just reference it from here? There are FreeBSD consumers (e.g. downstream projects and contributors) who are not committers, but who still have an interest in the meaning of the tags. Or it might just be that we should make sure they're aware of the content in this guide. emaste: There have been some changes to this content recently that will need to be merged in, although… | |||||
<para>As well as including an informative message with each | <para>As well as including an informative message with each | ||||
commit you may need to include some additional | commit you may need to include some additional | ||||
information.</para> | information.</para> | ||||
<para>This information consists of one or more lines | <para>This information consists of one or more lines | ||||
containing the key word or phrase, a colon, tabs for formatting, | containing the key word or phrase, a colon, tabs for formatting, | ||||
and then the additional information.</para> | and then the additional information.</para> | ||||
▲ Show 20 Lines • Show All 92 Lines • ▼ Show 20 Lines | <row> | ||||
references or a description of the issue. If possible, | references or a description of the issue. If possible, | ||||
include a VuXML URL or a CVE ID.</entry> | include a VuXML URL or a CVE ID.</entry> | ||||
</row> | </row> | ||||
<row> | <row> | ||||
<entry><literal>Differential Revision:</literal></entry> | <entry><literal>Differential Revision:</literal></entry> | ||||
<entry>The full URL of the Phabricator review. This line | <entry>The full URL of the Phabricator review. This line | ||||
<emphasis>must be the last line</emphasis>. For example: | <emphasis>must be the last line</emphasis>. For example: | ||||
<literal>https://reviews.freebsd.org/D1708</literal>.</entry> | <literal>http://reviews.freebsd.org/D1708</literal>.</entry> | ||||
</row> | </row> | ||||
</tbody> | </tbody> | ||||
</tgroup> | </tgroup> | ||||
</informaltable> | </informaltable> | ||||
<example> | <example> | ||||
<title>Commit Log for a Commit Based on a PR</title> | <title>Commit Log for a Commit Based on a PR</title> | ||||
▲ Show 20 Lines • Show All 216 Lines • ▼ Show 20 Lines | <para>Once the &a.core; is satisfied that all the necessary | ||||
serve as our permanent record of the license grant.</para> | serve as our permanent record of the license grant.</para> | ||||
<para>The license archive should contain only details of license | <para>The license archive should contain only details of license | ||||
grants; this is not the place for any discussions around | grants; this is not the place for any discussions around | ||||
licensing or other subjects. Access to data within the license | licensing or other subjects. Access to data within the license | ||||
archive will be available on request to the &a.core;.</para> | archive will be available on request to the &a.core;.</para> | ||||
</sect1> | </sect1> | ||||
<sect1 xml:id="developer.relations"> | |||||
<title>Developer Relations</title> | |||||
<para>If you are 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. If you see 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. If, however, you are | |||||
about to modify something which is clearly being actively | |||||
maintained by someone else (and it is only by watching the | |||||
<literal><replaceable>repository</replaceable>-committers</literal> | |||||
mailing list that you can really get a feel for just what is and | |||||
is not) then consider sending the change to them instead, just | |||||
as you would have before becoming a committer. For ports, you | |||||
should contact the listed <varname>MAINTAINER</varname> in the | |||||
<filename>Makefile</filename>. For other parts of the | |||||
repository, if you are unsure who the active maintainer might | |||||
be, it may help to 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 <systemitem>freefall</systemitem> at | |||||
<filename>~eadler/bin/whodid</filename>. If your queries go | |||||
unanswered or the committer otherwise indicates a lack of | |||||
interest in the area affected, go ahead and commit it.</para> | |||||
<note> | |||||
<para>Avoid sending private emails to maintainers. Other people | |||||
might be interested in the conversation, not just the final | |||||
output.</para> | |||||
</note> | |||||
<para>If you are unsure about a commit for any reason at all, have | |||||
it reviewed by <literal>-hackers</literal> before committing. | |||||
Better to have it flamed then and there rather than when it is | |||||
part of the repository. If you do happen to commit something | |||||
which results in controversy erupting, you may also wish to | |||||
consider backing the change out again until the matter is | |||||
settled. Remember – with a version control system we can | |||||
always change it back.</para> | |||||
<para>Do not impugn the intentions of someone you disagree with. | |||||
If they see a different solution to a problem than you, or even | |||||
a different problem, it is not because they are stupid, because | |||||
they have questionable parentage, or because they are trying to | |||||
destroy your hard work, personal image, or &os;, but simply | |||||
because they have a different outlook on the world. Different | |||||
is good.</para> | |||||
<para>Disagree honestly. Argue your position from its merits, | |||||
be honest about any shortcomings it may have, and be open to | |||||
seeing their solution, or even their vision of the problem, | |||||
with an open mind.</para> | |||||
<para>Accept correction. We are all fallible. When you have made | |||||
a mistake, apologize and get on with life. Do not beat up | |||||
yourself, and certainly do not beat up others for your mistake. | |||||
Do not waste time on embarrassment or recrimination, just fix | |||||
the problem and move on.</para> | |||||
<para>Ask for help. Seek out (and give) peer reviews. One of | |||||
the ways open source software is supposed to excel is in the | |||||
number of eyeballs applied to it; this does not apply if nobody | |||||
will review code.</para> | |||||
</sect1> | |||||
<sect1 xml:id="if-in-doubt"> | |||||
<title>If in Doubt...</title> | |||||
<para>When you are not sure about something, whether it be a | |||||
technical issue or a project convention be sure to ask. If you | |||||
stay silent you will never make progress.</para> | |||||
<para>If it relates to a technical issue ask on the public | |||||
mailing lists. Avoid the temptation to email the individual | |||||
person that knows the answer. This way everyone will be able to | |||||
learn from the question and the answer.</para> | |||||
<para>For project specific or administrative questions you should | |||||
ask, in order:</para> | |||||
<itemizedlist> | |||||
<listitem> | |||||
<para>Your mentor or former mentor.</para> | |||||
</listitem> | |||||
<listitem> | |||||
<para>An experienced committer on IRC, email, etc.</para> | |||||
</listitem> | |||||
<listitem> | |||||
<para>Any team with a "hat", as they should give you a | |||||
definitive answer.</para> | |||||
</listitem> | |||||
<listitem> | |||||
<para>If still not sure, ask on &a.developers;.</para> | |||||
</listitem> | |||||
</itemizedlist> | |||||
<para>Once your question is answered, if no one pointed you to | |||||
documentation that spelled out the answer to your question, | |||||
document it, as others will have the same question.</para> | |||||
</sect1> | |||||
<sect1 xml:id="bugzilla"> | <sect1 xml:id="bugzilla"> | ||||
<title>Bugzilla</title> | <title>Bugzilla</title> | ||||
<para>The &os; Project utilizes | <para>The &os; Project utilizes | ||||
editor_callfortesting.orgAuthorUnsubmitted Not Done Inline ActionsMove up to account setup. editor_callfortesting.org: Move up to account setup. | |||||
<application>Bugzilla</application> for tracking bugs and change | <application>Bugzilla</application> for tracking bugs and change | ||||
requests. Be sure that if you commit a fix or suggestion found | requests. Be sure that if you commit a fix or suggestion found | ||||
in the PR database to close it. It is also considered nice if | in the PR database to close it. It is also considered nice if | ||||
you take time to close any PRs associated with your commits, if | you take time to close any PRs associated with your commits, if | ||||
appropriate.</para> | appropriate.</para> | ||||
<para>Committers with | <para>Committers with | ||||
non-<systemitem class="domainname">&os;.org</systemitem> | non-<systemitem class="domainname">&os;.org</systemitem> | ||||
Show All 10 Lines | <itemizedlist> | ||||
<listitem> | <listitem> | ||||
<para><link | <para><link | ||||
xlink:href="&url.articles.pr-guidelines;/index.html">&os; | xlink:href="&url.articles.pr-guidelines;/index.html">&os; | ||||
Problem Report Handling Guidelines</link></para> | Problem Report Handling Guidelines</link></para> | ||||
</listitem> | </listitem> | ||||
<listitem> | <listitem> | ||||
<para><link | <para><link | ||||
xlink:href="&url.base;/support.html">http://www.FreeBSD.org/support.html</link></para> | xlink:href="&url.base;/support.html">http://www.freebsd.org/support.html</link></para> | ||||
</listitem> | </listitem> | ||||
</itemizedlist> | </itemizedlist> | ||||
</sect1> | </sect1> | ||||
<sect1> | |||||
<title>Phabricator</title> | |||||
<para>The &os; Project utilizes <link | |||||
xlink:href="https://reviews.freebsd.org">Phabricator</link> | |||||
for code review requests. See the <link | |||||
xlink:href="https://wiki.freebsd.org/CodeReview">CodeReview</link> | |||||
wiki page for details.</para> | |||||
</sect1> | |||||
<sect1 xml:id="people"> | |||||
<title>Who's Who</title> | |||||
<para>Besides the repository meisters, there are other &os; | |||||
project members and teams whom you will probably get to know in | |||||
your role as a committer. Briefly, and by no means | |||||
all-inclusively, these are:</para> | |||||
<variablelist> | |||||
<varlistentry> | |||||
<term>&a.doceng;</term> | |||||
<listitem> | |||||
<para>doceng is the group responsible for the documentation | |||||
build infrastructure, approving new documentation | |||||
committers, and ensuring that the &os; website and | |||||
documentation on the FTP site is up to date with respect | |||||
to the <application>subversion</application> tree. It is | |||||
not a conflict resolution body. | |||||
The vast majority of documentation related discussion | |||||
takes place on the &a.doc;. More details regarding the | |||||
doceng team can be found in its <link | |||||
xlink:href="http://www.FreeBSD.org/internal/doceng.html">charter</link>. | |||||
Committers interested in contributing to the documentation | |||||
should familiarize themselves with the <link | |||||
xlink:href="&url.books.fdp-primer;/index.html">Documentation | |||||
Project Primer</link>.</para> | |||||
</listitem> | |||||
</varlistentry> | |||||
<varlistentry> | |||||
<term>&a.bde.email;</term> | |||||
<listitem> | |||||
<para>Bruce is the Style Police-Meister. When you do a | |||||
commit that could have been done better, Bruce will be | |||||
there to tell you. Be thankful that someone is. Bruce is | |||||
also very knowledgeable on the various standards | |||||
applicable to &os;.</para> | |||||
</listitem> | |||||
</varlistentry> | |||||
<varlistentry> | |||||
<term>&a.re.members.email;</term> | |||||
<listitem> | |||||
<para>These are the members of the &a.re;. 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. If | |||||
there is something you want merged from &os.current; to | |||||
&os.stable; (whatever values those may have at any given | |||||
time), these are the people to talk to about it.</para> | |||||
<para>Hiroki is also the keeper of the release documentation | |||||
(<filename>src/release/doc/*</filename>). If you commit a | |||||
change that you think is worthy of mention in the release | |||||
notes, please make sure he knows about it. Better still, | |||||
send him a patch with your suggested commentary.</para> | |||||
</listitem> | |||||
</varlistentry> | |||||
<varlistentry> | |||||
<term>&a.so.email;</term> | |||||
<listitem> | |||||
<para>&a.so; is the | |||||
<link xlink:href="&url.base;/security/">&os; Security | |||||
Officer</link> and oversees the | |||||
&a.security-officer;.</para> | |||||
</listitem> | |||||
</varlistentry> | |||||
<varlistentry> | |||||
<term>&a.wollman.email;</term> | |||||
<listitem> | |||||
<para>If you need advice on obscure network internals or | |||||
are not sure of some potential change to the networking | |||||
subsystem you have in mind, Garrett is someone to talk | |||||
to. Garrett is also very knowledgeable on the various | |||||
standards applicable to &os;.</para> | |||||
</listitem> | |||||
</varlistentry> | |||||
<varlistentry> | |||||
<term>&a.committers;</term> | |||||
<listitem> | |||||
<para>&a.svn-src-all.name;, &a.svn-ports-all.name; and | |||||
&a.svn-doc-all.name; are the mailing lists that the | |||||
version control system uses to send commit messages to. | |||||
You should <emphasis>never</emphasis> send email directly | |||||
to these lists. You should only send replies to this list | |||||
when they are short and are directly related to a | |||||
commit.</para> | |||||
</listitem> | |||||
</varlistentry> | |||||
<varlistentry> | |||||
<term>&a.developers;</term> | |||||
<listitem> | |||||
<para>All committers are subscribed to -developers. This | |||||
list was created to be a forum for the committers | |||||
<quote>community</quote> issues. Examples are Core | |||||
voting, announcements, etc.</para> | |||||
<para>The &a.developers; is for the exclusive use of &os; | |||||
committers. In order to develop &os;, committers must | |||||
have the ability to openly discuss matters that will be | |||||
resolved before they are publicly announced. Frank | |||||
discussions of work in progress are not suitable for open | |||||
publication and may harm &os;.</para> | |||||
<para>All &os; committers are expected not to | |||||
not publish or forward messages from the | |||||
&a.developers; outside the list membership without | |||||
permission of all of the authors. Violators will be | |||||
removed from the | |||||
&a.developers;, resulting in a suspension of commit | |||||
privileges. Repeated or flagrant violations may result in | |||||
permanent revocation of commit privileges.</para> | |||||
<para>This list is <emphasis>not</emphasis> intended as a | |||||
place for code reviews or for any technical discussion. | |||||
In fact using it as such hurts the &os; Project as it | |||||
gives a sense of a closed list where general decisions | |||||
affecting all of the &os; using community are made without | |||||
being <quote>open</quote>. Last, but not least | |||||
<emphasis>never, never ever, email the &a.developers; and | |||||
CC:/BCC: another &os; list</emphasis>. Never, ever email | |||||
another &os; email list and CC:/BCC: the &a.developers;. | |||||
Doing so can greatly diminish the benefits of this | |||||
list.</para> | |||||
</listitem> | |||||
</varlistentry> | |||||
</variablelist> | |||||
</sect1> | |||||
<sect1 xml:id="ssh.guide"> | |||||
<title>SSH Quick-Start Guide</title> | |||||
<procedure> | |||||
<step> | |||||
<para>If you do not wish to type your password in every time | |||||
you use &man.ssh.1;, and you use keys to | |||||
authenticate, &man.ssh-agent.1; is there for your | |||||
convenience. If you want to use &man.ssh-agent.1;, make | |||||
sure that you run it before running other applications. X | |||||
users, for example, usually do this from their | |||||
<filename>.xsession</filename> or | |||||
<filename>.xinitrc</filename>. See &man.ssh-agent.1; for | |||||
details.</para> | |||||
</step> | |||||
<step> | |||||
<para>Generate a key pair using &man.ssh-keygen.1;. The key | |||||
pair will wind up in your | |||||
<filename>$HOME/.ssh/</filename> | |||||
directory.</para> | |||||
<important> | |||||
<para>Only <acronym>ECDSA</acronym>, | |||||
<acronym>Ed25519</acronym> or <acronym>RSA</acronym> keys | |||||
are supported.</para> | |||||
</important> | |||||
</step> | |||||
<step> | |||||
<para>Send your public key | |||||
(<filename>$HOME/.ssh/id_ecdsa.pub</filename>, | |||||
<filename>$HOME/.ssh/id_ed25519.pub</filename>, or | |||||
<filename>$HOME/.ssh/id_rsa.pub</filename>) | |||||
to the person setting you up as a committer so it can be put | |||||
into | |||||
<filename><replaceable>yourlogin</replaceable></filename> | |||||
in | |||||
<filename>/etc/ssh-keys/</filename> on | |||||
<systemitem>freefall</systemitem>.</para> | |||||
</step> | |||||
</procedure> | |||||
<para>Now you should be able to use &man.ssh-add.1; for | |||||
authentication once per session. This will prompt you for | |||||
your private key's pass phrase, and then store it in your | |||||
authentication agent (&man.ssh-agent.1;). If you no longer | |||||
wish to have your key stored in the agent, issuing | |||||
<command>ssh-add -d</command> will remove it.</para> | |||||
<para>Test by doing something such as <command>ssh | |||||
freefall.FreeBSD.org ls /usr</command>.</para> | |||||
<para>For more information, see | |||||
<package>security/openssh</package>, | |||||
&man.ssh.1;, &man.ssh-add.1;, &man.ssh-agent.1;, | |||||
&man.ssh-keygen.1;, and &man.scp.1;.</para> | |||||
<para>For information on adding, changing, or removing &man.ssh.1; | |||||
keys, see <uri | |||||
xlink:href="https://wiki.freebsd.org/clusteradm/ssh-keys">this | |||||
article</uri>.</para> | |||||
</sect1> | |||||
<sect1 xml:id="coverity"> | <sect1 xml:id="coverity"> | ||||
editor_callfortesting.orgAuthorUnsubmitted Not Done Inline ActionsProbably make this an Optional account creation step like Wiki... editor_callfortesting.org: Probably make this an Optional account creation step like Wiki... | |||||
bcrUnsubmitted Not Done Inline ActionsCould also be in the developers handbook. doc committers don't need to know this. bcr: Could also be in the developers handbook. doc committers don't need to know this. | |||||
<title>&coverity; Availability for &os; Committers</title> | <title>&coverity; Availability for &os; Committers</title> | ||||
<para>All &os; developers can obtain access to | <para>All &os; developers can obtain access to | ||||
<application>Coverity</application> analysis results of all &os; | <application>Coverity</application> analysis results of all &os; | ||||
Project software. All who are interested in obtaining access to | Project software. All who are interested in obtaining access to | ||||
the analysis results of the automated | the analysis results of the automated | ||||
<application>Coverity</application> runs, can sign up at <uri | <application>Coverity</application> runs, can sign up at <uri | ||||
xlink:href="http://scan.coverity.com/">Coverity | xlink:href="http://scan.coverity.com/">Coverity | ||||
Scan</uri>.</para> | Scan</uri>.</para> | ||||
<para>The &os; wiki includes a mini-guide for developers who are | <para>The &os; wiki includes a mini-guide for developers who are | ||||
interested in working with the &coverity; analysis reports: <uri | interested in working with the &coverity; analysis reports: <uri | ||||
xlink:href="http://wiki.freebsd.org/CoverityPrevent">http://wiki.freebsd.org/CoverityPrevent</uri>. | xlink:href="http://wiki.freebsd.org/CoverityPrevent">http://wiki.freebsd.org/CoverityPrevent</uri>. | ||||
Please note that this mini-guide is only readable by &os; | Please note that this mini-guide is only readable by &os; | ||||
developers, so if you cannot access this page, you will have to | developers, so if you cannot access this page, you will have to | ||||
ask someone to add you to the appropriate Wiki access | ask someone to add you to the appropriate Wiki access | ||||
list.</para> | list.</para> | ||||
<para>Finally, all &os; developers who are going to use | <para>Finally, all &os; developers who are going to use | ||||
&coverity; are always encouraged to ask for more details and | &coverity; are always encouraged to ask for more details and | ||||
usage information, by posting any questions to the mailing list | usage information, by posting any questions to the mailing list | ||||
of the &os; developers.</para> | of the &os; developers.</para> | ||||
</sect1> | </sect1> | ||||
<sect1 xml:id="rules"> | |||||
<title>The &os; Committers' Big List of Rules</title> | |||||
<para>Everyone involved with the &os; project is expected to | |||||
abide by the <emphasis>Code of Conduct</emphasis> available from | |||||
<link xlink:href="&url.base;/internal/code-of-conduct.html" | |||||
>http://www.FreeBSD.org/internal/code-of-conduct.html</link>. | |||||
As committers, you form the public face of the project, and how | |||||
you behave has a vital impact on the public perception of it. | |||||
This guide expands on the parts of the | |||||
<emphasis>Code of Conduct</emphasis> specific to | |||||
committers.</para> | |||||
<orderedlist> | |||||
<listitem> | |||||
<para>Respect other committers.</para> | |||||
</listitem> | |||||
<listitem> | |||||
<para>Respect other contributors.</para> | |||||
</listitem> | |||||
<listitem> | |||||
<para>Discuss any significant change | |||||
<emphasis>before</emphasis> committing.</para> | |||||
</listitem> | |||||
<listitem> | |||||
<para>Respect existing maintainers (if listed in the | |||||
<varname>MAINTAINER</varname> field in | |||||
<filename>Makefile</filename> or in | |||||
<filename>MAINTAINER</filename> in the top-level | |||||
directory).</para> | |||||
</listitem> | |||||
<listitem> | |||||
<para>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.</para> | |||||
</listitem> | |||||
<listitem> | |||||
<para>Changes go to &os.current; before &os.stable; unless | |||||
specifically permitted by the release engineer or unless | |||||
they are not applicable to &os.current;. Any non-trivial or | |||||
non-urgent change which is applicable should also be allowed | |||||
to sit in &os.current; for at least 3 days before merging so | |||||
that it can be given sufficient testing. The release | |||||
engineer has the same authority over the &os.stable; branch | |||||
as outlined for the maintainer in rule #5.</para> | |||||
</listitem> | |||||
<listitem> | |||||
<para>Do not fight in public with other committers; it looks | |||||
bad.</para> | |||||
</listitem> | |||||
<listitem> | |||||
<para>Respect all code freezes and read the | |||||
<literal>committers</literal> and | |||||
<literal>developers</literal> mailing lists in a timely | |||||
manner so you know when a code freeze is in effect.</para> | |||||
</listitem> | |||||
<listitem> | |||||
<para>When in doubt on any procedure, ask first!</para> | |||||
</listitem> | |||||
<listitem> | |||||
<para>Test your changes before committing them.</para> | |||||
</listitem> | |||||
<listitem> | |||||
<para>Do not commit to anything under the | |||||
<filename>src/contrib</filename>, | |||||
<filename>src/crypto</filename>, or | |||||
<filename>src/sys/contrib</filename> trees without | |||||
<emphasis>explicit</emphasis> approval from the respective | |||||
maintainer(s).</para> | |||||
</listitem> | |||||
</orderedlist> | |||||
<para>As noted, breaking some of these rules can be grounds for | |||||
suspension or, upon repeated offense, permanent removal of | |||||
commit privileges. Individual members of core have the power to | |||||
temporarily suspend commit privileges until core as a whole has | |||||
the chance to review the issue. In case of an | |||||
<quote>emergency</quote> (a committer doing damage to the | |||||
repository), a temporary suspension may also be done by the | |||||
repository meisters. Only a 2/3 majority of core has the | |||||
authority to suspend commit privileges for longer than a week or | |||||
to remove them permanently. This rule does not exist to set | |||||
core up as a bunch of cruel dictators who can dispose of | |||||
committers as casually as empty soda cans, but to give the | |||||
project a kind of safety fuse. If someone is out of control, it | |||||
is important to be able to deal with this immediately rather | |||||
than be paralyzed by debate. In all cases, a committer whose | |||||
privileges are suspended or revoked is entitled to a | |||||
<quote>hearing</quote> by core, the total duration of the | |||||
suspension being determined at that time. A committer whose | |||||
privileges are suspended may also request a review of the | |||||
decision after 30 days and every 30 days thereafter (unless the | |||||
total suspension period is less than 30 days). A committer | |||||
whose privileges have been revoked entirely may request a review | |||||
after a period of 6 months has elapsed. This review policy is | |||||
<emphasis>strictly informal</emphasis> and, in all cases, core | |||||
reserves the right to either act on or disregard requests for | |||||
review if they feel their original decision to be the right | |||||
one.</para> | |||||
<para>In all other aspects of project operation, core is a subset | |||||
of committers and is bound by the | |||||
<emphasis>same rules</emphasis>. Just because someone is in | |||||
core this does not mean that they have special dispensation to | |||||
step outside any of the lines painted here; core's | |||||
<quote>special powers</quote> only kick in when it acts as a | |||||
group, not on an individual basis. As individuals, the core | |||||
team members are all committers first and core second.</para> | |||||
<sect2> | |||||
<title>Details</title> | |||||
<orderedlist> | |||||
<listitem xml:id="respect"> | |||||
<para>Respect other committers.</para> | |||||
<para>This means that you need to treat other committers as | |||||
the peer-group developers that they are. Despite our | |||||
occasional attempts to prove the contrary, one does not | |||||
get to be a committer by being stupid and nothing rankles | |||||
more than being treated that way by one of your peers. | |||||
Whether we always feel respect for one another or not (and | |||||
everyone has off days), we still have to | |||||
<emphasis>treat</emphasis> other committers with respect | |||||
at all times, on public forums and in private | |||||
email.</para> | |||||
<para>Being able to work together long term is this | |||||
project's greatest asset, one far more important than any | |||||
set of changes to the code, and turning arguments about | |||||
code into issues that affect our long-term ability to work | |||||
harmoniously together is just not worth the trade-off by | |||||
any conceivable stretch of the imagination.</para> | |||||
<para>To comply with this rule, do not send email when you | |||||
are angry or otherwise behave in a manner which is likely | |||||
to strike others as needlessly confrontational. First | |||||
calm down, then think about how to communicate in the most | |||||
effective fashion for convincing the other person(s) that | |||||
your side of the argument is correct, do not just blow off | |||||
some steam so you can feel better in the short term at the | |||||
cost of a long-term flame war. Not only is this very bad | |||||
<quote>energy economics</quote>, but repeated displays of | |||||
public aggression which impair our ability to work well | |||||
together will be dealt with severely by the project | |||||
leadership and may result in suspension or termination of | |||||
your commit privileges. The project leadership will take | |||||
into account both public and private communications | |||||
brought before it. It will not seek the disclosure of | |||||
private communications, but it will take it into account | |||||
if it is volunteered by the committers involved in the | |||||
complaint.</para> | |||||
<para>All of this is never an option which the project's | |||||
leadership enjoys in the slightest, but unity comes first. | |||||
No amount of code or good advice is worth trading that | |||||
away.</para> | |||||
</listitem> | |||||
<listitem> | |||||
<para>Respect other contributors.</para> | |||||
<para>You were not always a committer. At one time you were | |||||
a contributor. Remember that at all times. Remember what | |||||
it was like trying to get help and attention. Do not | |||||
forget that your work as a contributor was very important | |||||
to you. Remember what it was like. Do not discourage, | |||||
belittle, or demean contributors. Treat them with | |||||
respect. They are our committers in waiting. They are | |||||
every bit as important to the project as committers. | |||||
Their contributions are as valid and as important as your | |||||
own. After all, you made many contributions before you | |||||
became a committer. Always remember that.</para> | |||||
<para>Consider the points raised under | |||||
<xref linkend="respect"/> and apply them also to | |||||
contributors.</para> | |||||
</listitem> | |||||
<listitem> | |||||
<para>Discuss any significant change | |||||
<emphasis>before</emphasis> committing.</para> | |||||
<para>The repository is not where changes should be | |||||
initially submitted for correctness or argued over, that | |||||
should happen first in the mailing lists or by use of the | |||||
Phabricator service and the commit should only happen once | |||||
something resembling consensus has been reached. This | |||||
does not mean that you have to ask permission before | |||||
correcting every obvious syntax error or manual page | |||||
misspelling, simply that you should try to develop a feel | |||||
for when a proposed change is not quite such a no-brainer | |||||
and requires some feedback first. People really do not | |||||
mind sweeping changes if the result is something clearly | |||||
better than what they had before, they just do not like | |||||
being <emphasis>surprised</emphasis> by those changes. | |||||
The very best way of making sure that you are on the right | |||||
track is to have your code reviewed by one or more other | |||||
committers.</para> | |||||
<para>When in doubt, ask for review!</para> | |||||
</listitem> | |||||
<listitem> | |||||
<para>Respect existing maintainers if listed.</para> | |||||
<para>Many parts of &os; are not <quote>owned</quote> in | |||||
the sense that any specific individual will jump up and | |||||
yell if you commit a change to <quote>their</quote> area, | |||||
but it still pays to check first. One convention we use | |||||
is to put a maintainer line in the | |||||
<filename>Makefile</filename> for any package or subtree | |||||
which is being actively maintained by one or more people; | |||||
see <link | |||||
xlink:href="&url.books.developers-handbook;/policies.html">http://www.FreeBSD.org/doc/en_US.ISO8859-1/books/developers-handbook/policies.html</link> | |||||
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. In cases where the | |||||
<quote>maintainer-ship</quote> of something is not clear, | |||||
you can also look at the repository logs for the file(s) | |||||
in question and see if someone has been working recently | |||||
or predominantly in that area.</para> | |||||
<para>Other areas of &os; fall under the control of someone | |||||
who manages an overall category of &os; evolution, such as | |||||
internationalization or networking. See <link | |||||
xlink:href="&url.base;/administration.html">http://www.FreeBSD.org/administration.html</link> | |||||
for more information on this.</para> | |||||
</listitem> | |||||
<listitem> | |||||
<para>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.</para> | |||||
<para>This may be hard to swallow in times of conflict (when | |||||
each side is convinced that they are in the right, of | |||||
course) but a version control system makes it unnecessary | |||||
to have an ongoing dispute raging when it is far easier to | |||||
simply reverse the disputed change, get everyone calmed | |||||
down again and then try to figure out what is the best way | |||||
to proceed. If the change turns out to be the best thing | |||||
after all, it can be easily brought back. If it turns out | |||||
not to be, then the users did not have to live with the | |||||
bogus change in the tree while everyone was busily | |||||
debating its merits. People <emphasis>very</emphasis> | |||||
rarely call for back-outs in the repository since | |||||
discussion generally exposes bad or controversial changes | |||||
before the commit even happens, but on such rare occasions | |||||
the back-out should be done without argument so that we | |||||
can get immediately on to the topic of figuring out | |||||
whether it was bogus or not.</para> | |||||
</listitem> | |||||
<listitem> | |||||
<para>Changes go to &os.current; before &os.stable; unless | |||||
specifically permitted by the release engineer or unless | |||||
they are not applicable to &os.current;. Any non-trivial | |||||
or non-urgent change which is applicable should also be | |||||
allowed to sit in &os.current; for at least 3 days before | |||||
merging so that it can be given sufficient testing. The | |||||
release engineer has the same authority over the | |||||
&os.stable; branch as outlined in rule #5.</para> | |||||
<para>This is another <quote>do not argue about it</quote> | |||||
issue since it is the release engineer who is ultimately | |||||
responsible (and gets beaten up) if a change turns out to | |||||
be bad. Please respect this and give the release engineer | |||||
your full cooperation when it comes to the &os.stable; | |||||
branch. The management of &os.stable; may frequently seem | |||||
to be overly conservative to the casual observer, but also | |||||
bear in mind the fact that conservatism is supposed to be | |||||
the hallmark of &os.stable; and different rules apply | |||||
there than in &os.current;. There is also really no point | |||||
in having &os.current; be a testing ground if changes are | |||||
merged over to &os.stable; immediately. Changes need a | |||||
chance to be tested by the &os.current; developers, so | |||||
allow some time to elapse before merging unless the | |||||
&os.stable; fix is critical, time sensitive or so obvious | |||||
as to make further testing unnecessary (spelling fixes to | |||||
manual pages, obvious bug/typo fixes, etc.) In other | |||||
words, apply common sense.</para> | |||||
<para>Changes to the security branches (for example, | |||||
<literal>releng/9.3</literal>) must be approved by a | |||||
member of the &a.security-officer;, or in some cases, by a | |||||
member of the &a.re;.</para> | |||||
</listitem> | |||||
<listitem> | |||||
<para>Do not fight in public with other committers; it looks | |||||
bad.</para> | |||||
<para>This project has a public image to uphold and that | |||||
image is very important to all of us, especially if we are | |||||
to continue to attract new members. There will be | |||||
occasions when, despite everyone's very best attempts at | |||||
self-control, tempers are lost and angry words are | |||||
exchanged. The best thing that can be done in such cases | |||||
is to minimize the effects of this until everyone has | |||||
cooled back down. That means that you should not air your | |||||
angry words in public and you should not forward private | |||||
correspondence or other private communications to public | |||||
mailing lists, mail aliases, instant messaging channels or | |||||
social media sites. What people say one-to-one is often | |||||
much less sugar-coated than what they would say in public, | |||||
and such communications therefore have no place there - | |||||
they only serve to inflame an already bad situation. If | |||||
the person sending you a flame-o-gram at least had the | |||||
grace to send it privately, then have the grace to keep it | |||||
private yourself. If you feel you are being unfairly | |||||
treated by another developer, and it is causing you | |||||
anguish, bring the matter up with core rather than taking | |||||
it public. Core will do its best to play peace makers and | |||||
get things back to sanity. In cases where the dispute | |||||
involves a change to the codebase and the participants do | |||||
not appear to be reaching an amicable agreement, core may | |||||
appoint a mutually-agreeable third party to resolve the | |||||
dispute. All parties involved must then agree to be bound | |||||
by the decision reached by this third party.</para> | |||||
</listitem> | |||||
<listitem> | |||||
<para>Respect all code freezes and read the | |||||
<literal>committers</literal> and | |||||
<literal>developers</literal> mailing list on a timely | |||||
basis so you know when a code freeze is in effect.</para> | |||||
<para>Committing unapproved changes during a code freeze is | |||||
a really big mistake and committers are expected to keep | |||||
up-to-date on what is going on before jumping in after a | |||||
long absence and committing 10 megabytes worth of | |||||
accumulated stuff. People who abuse this on a regular | |||||
basis will have their commit privileges suspended until | |||||
they get back from the &os; Happy Reeducation Camp we | |||||
run in Greenland.</para> | |||||
</listitem> | |||||
<listitem> | |||||
<para>When in doubt on any procedure, ask first!</para> | |||||
<para>Many mistakes are made because someone is in a hurry | |||||
and just assumes they know the right way of doing | |||||
something. If you have not done it before, chances are | |||||
good that you do not actually know the way we do things | |||||
and really need to ask first or you are going to | |||||
completely embarrass yourself in public. There is no | |||||
shame in asking | |||||
<quote>how in the heck do I do this?</quote> We already | |||||
know you are an intelligent person; otherwise, you would | |||||
not be a committer.</para> | |||||
</listitem> | |||||
<listitem> | |||||
<para>Test your changes before committing them.</para> | |||||
<!-- XXX Needs update re sparc64 + pc98 | |||||
Also, needs more details on which machines are available for testing | |||||
--> | |||||
<para>This may sound obvious, but if it really were so | |||||
obvious then we probably would not see so many cases of | |||||
people clearly not doing this. If your changes are to the | |||||
kernel, make sure you can still compile both GENERIC and | |||||
LINT. If your changes are anywhere else, make sure you | |||||
can still make world. If your changes are to a branch, | |||||
make sure your testing occurs with a machine which is | |||||
running that code. If you have a change which also may | |||||
break another architecture, be sure and test on all | |||||
supported architectures. Please refer to the | |||||
<link xlink:href="http://www.FreeBSD.org/internal/">&os; | |||||
Internal Page</link> for a list of available resources. | |||||
As other architectures are added to the &os; supported | |||||
platforms list, the appropriate shared testing resources | |||||
will be made available.</para> | |||||
</listitem> | |||||
<listitem> | |||||
<para>Do not commit to anything under the | |||||
<filename>src/contrib</filename>, | |||||
<filename>src/crypto</filename>, and | |||||
<filename>src/sys/contrib</filename> trees without | |||||
<emphasis>explicit</emphasis> approval from the respective | |||||
maintainer(s).</para> | |||||
<para>The trees mentioned above are for contributed software | |||||
usually imported onto a vendor branch. Committing | |||||
something there, even if it does not take the file off the | |||||
vendor branch, may cause unnecessary headaches for those | |||||
responsible for maintaining that particular piece of | |||||
software. Thus, unless you have | |||||
<emphasis>explicit</emphasis> approval from the maintainer | |||||
(or you are the maintainer), do <emphasis>not</emphasis> | |||||
commit there!</para> | |||||
<para>Please note that this does not mean you should not try | |||||
to improve the software in question; you are still more | |||||
than welcome to do so. Ideally, you should submit your | |||||
patches to the vendor. If your changes are | |||||
&os;-specific, talk to the maintainer; they may be | |||||
willing to apply them locally. But whatever you do, do | |||||
<emphasis>not</emphasis> commit there by yourself!</para> | |||||
<para>Contact the &a.core; if you wish to take up | |||||
maintainership of an unmaintained part of the tree.</para> | |||||
</listitem> | |||||
</orderedlist> | |||||
</sect2> | |||||
<sect2> | |||||
<title>Policy on Multiple Architectures</title> | |||||
<para>&os; has added several new architecture ports during | |||||
recent release cycles and is truly no longer an &i386; centric | |||||
operating system. In an effort to make it easier to keep | |||||
&os; portable across the platforms we support, core has | |||||
developed the following mandate:</para> | |||||
<blockquote> | |||||
<para>Our 32-bit reference platform is &arch.i386;, and our | |||||
64-bit reference platform is &arch.amd64;. Major design | |||||
work (including major API and ABI changes) must prove | |||||
itself on at least one 32-bit and at least one 64-bit | |||||
platform, preferably the primary reference platforms, | |||||
before it may be committed to the source tree.</para> | |||||
</blockquote> | |||||
<para>The &arch.i386; and &arch.amd64; platforms were chosen | |||||
due to being more readily available to developers and as | |||||
representatives of more diverse processor and system designs - | |||||
big versus little endian, register file versus register stack, | |||||
different DMA and cache implementations, hardware page tables | |||||
versus software TLB management etc.</para> | |||||
<para>We will continue to re-evaluate this policy as cost and | |||||
availability of the 64-bit platforms change.</para> | |||||
<para>Developers should also be aware of our Tier Policy for | |||||
the long term support of hardware architectures. The rules | |||||
here are intended to provide guidance during the development | |||||
process, and are distinct from the requirements for features | |||||
and architectures listed in that section. The Tier rules for | |||||
feature support on architectures at release-time are more | |||||
strict than the rules for changes during the development | |||||
process.</para> | |||||
</sect2> | |||||
<sect2> | |||||
<title>Other Suggestions</title> | |||||
<para>When committing documentation changes, use a spell checker | |||||
before committing. For all XML docs, verify that the | |||||
formatting directives are correct by running | |||||
<command>make lint</command> and | |||||
<package>textproc/igor</package>.</para> | |||||
<para>For manual pages, run <package>sysutils/manck</package> | |||||
and <package>textproc/igor</package> | |||||
over the manual page to verify all of the cross | |||||
references and file references are correct and that the man | |||||
page has all of the appropriate <varname>MLINK</varname>s | |||||
installed.</para> | |||||
<para>Do not mix style fixes with new functionality. A style | |||||
fix is any change which does not modify the functionality of | |||||
the code. Mixing the changes obfuscates the functionality | |||||
change when asking for differences between revisions, which | |||||
can hide any new bugs. Do not include whitespace changes with | |||||
content changes in commits to <filename>doc/</filename> . | |||||
The extra clutter in the diffs | |||||
makes the translators' job much more difficult. Instead, make | |||||
any style or whitespace changes in separate commits that are | |||||
clearly labeled as such in the commit message.</para> | |||||
</sect2> | |||||
<sect2> | |||||
<title>Deprecating Features</title> | |||||
<para>When it is necessary to remove functionality from software | |||||
in the base system the following guidelines should be followed | |||||
whenever possible:</para> | |||||
<orderedlist> | |||||
<listitem> | |||||
<para>Mention is made in the manual page and possibly the | |||||
release notes that the option, utility, or interface is | |||||
deprecated. Use of the deprecated feature generates a | |||||
warning.</para> | |||||
</listitem> | |||||
<listitem> | |||||
<para>The option, utility, or interface is preserved until | |||||
the next major (point zero) release.</para> | |||||
</listitem> | |||||
<listitem> | |||||
<para>The option, utility, or interface is removed and no | |||||
longer documented. It is now obsolete. It is also | |||||
generally a good idea to note its removal in the release | |||||
notes.</para> | |||||
</listitem> | |||||
</orderedlist> | |||||
</sect2> | |||||
<sect2> | |||||
<title>Privacy and Confidentiality</title> | |||||
<orderedlist> | |||||
<listitem> | |||||
<para>Most &os; business is done in public.</para> | |||||
<para>&os; is an <emphasis>open</emphasis> project. Which | |||||
means that not only can anyone use the source code, but | |||||
that most of the development process is open to public | |||||
scrutiny.</para> | |||||
</listitem> | |||||
<listitem> | |||||
<para>Certain sensitive matters must remain private or | |||||
held under embargo.</para> | |||||
<para>There unfortunately cannot be complete transparency. | |||||
As a &os; developer you will have a certain degree of | |||||
privileged access to information. Consequently you are | |||||
expected to respect certain requirements for | |||||
confidentiality. Sometimes the need for confidentiality | |||||
comes from external collaborators or has a specific time | |||||
limit. Mostly though, it is a matter of not releasing | |||||
private communications.</para> | |||||
</listitem> | |||||
<listitem> | |||||
<para>The Security Officer has sole control over the | |||||
release of security advisories.</para> | |||||
<para>Where there are security problems that affect many | |||||
different operating systems, &os; frequently depends on | |||||
early access in order to be able to prepare advisories for | |||||
coordinated release. Unless &os; developers can be | |||||
trusted to maintain security, such early access will not | |||||
be made available. The Security Officer is responsible | |||||
for controlling pre-release access to information about | |||||
vulnerabilities, and for timing the release of all | |||||
advisories. He may request help under condition of | |||||
confidentiality from any developer with relevant knowledge | |||||
in order to prepare security fixes.</para> | |||||
</listitem> | |||||
<listitem> | |||||
<para>Communications with Core are kept confidential for as | |||||
long as necessary.</para> | |||||
<para>Communications to core will initially be treated as | |||||
confidential. Eventually however, most of Core's business | |||||
will be summarized into the monthly or quarterly core | |||||
reports. Care will be taken to avoid publicising any | |||||
sensitive details. Records of some particularly sensitive | |||||
subjects may not be reported on at all and will be | |||||
retained only in Core's private archives.</para> | |||||
</listitem> | |||||
<listitem> | |||||
<para>Non-disclosure Agreements may be required for access | |||||
to certain commercially sensitive data.</para> | |||||
<para>Access to certain commercially sensitive data may | |||||
only be available under a Non-Disclosure Agreement. The | |||||
FreeBSD Foundation legal staff must be consulted before | |||||
any binding agreements are entered into.</para> | |||||
</listitem> | |||||
<listitem> | |||||
<para>Private communications should not be made | |||||
public without permission.</para> | |||||
<para>Beyond the specific requirements above there is a | |||||
general expectation not to publish private communications | |||||
between developers without the consent of all parties | |||||
involved. Ask permission before forwarding a message onto | |||||
a public mailing list, or posting it to a forum or website | |||||
that can be accessed by other than the original | |||||
correspondents.</para> | |||||
</listitem> | |||||
<listitem> | |||||
<para>Communications on project-only or restricted access | |||||
channels should be treated as private.</para> | |||||
<para>Similarly to personal communications, certain | |||||
internal communications channels, including &os; Committer | |||||
only mailing lists and restricted access IRC channels | |||||
should be considered as private communications. You need | |||||
permission in order to publish material from these | |||||
sources.</para> | |||||
</listitem> | |||||
<listitem> | |||||
<para>Core may approve publication.</para> | |||||
<para>Where it is impractical to obtain permission due to | |||||
the number of correspondents or where permission to | |||||
publish is unreasonably withheld, Core may approve release | |||||
of such private matters that merit more general | |||||
publication.</para> | |||||
</listitem> | |||||
</orderedlist> | |||||
</sect2> | |||||
</sect1> | |||||
<sect1 xml:id="archs"> | |||||
<title>Support for Multiple Architectures</title> | |||||
<para>&os; is a highly portable operating system intended to | |||||
function on many different types of hardware architectures. | |||||
Maintaining clean separation of Machine Dependent (MD) and | |||||
Machine Independent (MI) code, as well as minimizing MD code, is | |||||
an important part of our strategy to remain agile with regards | |||||
to current hardware trends. Each new hardware architecture | |||||
supported by &os; adds substantially to the cost of code | |||||
maintenance, toolchain support, and release engineering. It | |||||
also dramatically increases the cost of effective testing of | |||||
kernel changes. As such, there is strong motivation to | |||||
differentiate between classes of support for various | |||||
architectures while remaining strong in a few key architectures | |||||
that are seen as the &os; <quote>target audience</quote>.</para> | |||||
<sect2> | |||||
<title>Statement of General Intent</title> | |||||
<para>The &os; Project targets "production quality commercial | |||||
off-the-shelf (COTS) workstation, server, and high-end | |||||
embedded systems". By retaining a focus on a narrow set of | |||||
architectures of interest in these environments, the &os; | |||||
Project is able to maintain high levels of quality, stability, | |||||
and performance, as well as minimize the load on various | |||||
support teams on the project, such as the ports team, | |||||
documentation team, security officer, and release engineering | |||||
teams. Diversity in hardware support broadens the options for | |||||
&os; consumers by offering new features and usage | |||||
opportunities (such as support for 64-bit CPUs, use in | |||||
embedded environments, etc.), but these benefits must always | |||||
be carefully considered in terms of the real-world maintenance | |||||
cost associated with additional platform support.</para> | |||||
<para>The &os; Project differentiates platform targets into | |||||
four tiers. Each tier includes a specification of the | |||||
requirements for an architecture to be in that tier, | |||||
as well as specifying the obligations of developers with | |||||
regards to the platform. In addition, a policy is defined | |||||
regarding the circumstances required to change the tier | |||||
of an architecture.</para> | |||||
</sect2> | |||||
<sect2> | |||||
<title>Tier 1: Fully Supported Architectures</title> | |||||
<para>Tier 1 platforms are fully supported by the security | |||||
officer, release engineering, and toolchain maintenance staff. | |||||
New features added to the operating system must be fully | |||||
functional across all Tier 1 architectures for every release | |||||
(features which are inherently architecture-specific, such as | |||||
support for hardware device drivers, may be exempt from this | |||||
requirement). In general, all Tier 1 platforms must have | |||||
build and Tinderbox support either in the FreeBSD.org cluster, | |||||
or be easily available for all developers. Embedded platforms | |||||
may substitute an emulator available in the &os; cluster | |||||
for actual hardware.</para> | |||||
<para>Tier 1 architectures are expected to be Production Quality | |||||
with respects to all aspects of the &os; operating system, | |||||
including installation and development environments.</para> | |||||
<para>Tier 1 architectures are expected to be completely | |||||
integrated into the source tree and have all features | |||||
necessary to produce an entire system relevant for that target | |||||
architecture. Tier 1 architectures generally have at least 6 | |||||
active developers.</para> | |||||
<para>Tier 1 architectures are expected to be fully supported by | |||||
the ports system. All the ports should build on a Tier 1 | |||||
platform, or have the appropriate filters to prevent the | |||||
inappropriate ones from building there. The packaging system | |||||
must support all Tier 1 architectures. To ensure an | |||||
architecture's Tier 1 status, proponents of that architecture | |||||
must show that all relevant packages can be built on that | |||||
platform.</para> | |||||
<para>Tier 1 embedded architectures must be able to cross-build | |||||
packages on at least one other Tier 1 architecture. The | |||||
packages must be the most relevant for the platform, but may | |||||
be a non-empty subset of those that build natively.</para> | |||||
<para>Tier 1 architectures must be fully documented. All basic | |||||
operations need to be covered by the handbook or other | |||||
documents. All relevant integration documentation must also | |||||
be integrated into the tree, or readily available.</para> | |||||
<para>Current Tier 1 platforms are &arch.i386; and | |||||
&arch.amd64;.</para> | |||||
</sect2> | |||||
<sect2> | |||||
<title>Tier 2: Developmental Architectures</title> | |||||
<para>Tier 2 platforms are not supported by the security officer | |||||
and release engineering teams. Platform maintainers are | |||||
responsible for toolchain support in the tree. The toolchain | |||||
maintainers are expected to work with the platform maintainers | |||||
to refine these changes. Major new toolchain components are | |||||
allowed to break support for Tier 2 architectures if the | |||||
&os;-local changes have not been incorporated upstream. | |||||
The toolchain maintainers are expected to provide prompt | |||||
review of any proposed changes and cannot block, through their | |||||
inaction, changes going into the tree. New features added to | |||||
&os; should be feasible to implement on these platforms, | |||||
but an implementation is not required before the feature may | |||||
be added to the &os; source tree. New features that may be | |||||
difficult to implement on Tier 2 architectures should provide | |||||
a means of disabling them on those architectures. The | |||||
implementation of a Tier 2 architecture may be committed to | |||||
the main &os; tree as long as it does not interfere with | |||||
production work on Tier 1 platforms, or substantially with | |||||
other Tier 2 platforms. Before a Tier 2 platform can be added | |||||
to the &os; base source tree, the platform must be able to | |||||
boot multi-user on actual hardware. Generally, there must be | |||||
at least three active developers working on the | |||||
platform.</para> | |||||
<para>Tier 2 architectures are usually systems targeted at Tier | |||||
1 support, but that are still under development. | |||||
Architectures reaching end of life may also be moved from Tier | |||||
1 status to Tier 2 status as the availability of resources to | |||||
continue to maintain the system in a Production Quality state | |||||
diminishes. Well supported niche architectures may also be | |||||
Tier 2.</para> | |||||
<para>Tier 2 architectures have basic support for them | |||||
integrated into the ports infrastructure. They may have cross | |||||
compilation support added, at the discretion of portmgr. Some | |||||
ports must built natively into packages if the package system | |||||
supports that architecture. If not integrated into the base | |||||
system, some external patches for the architecture for ports | |||||
must be available.</para> | |||||
<para>Tier 2 architectures can be integrated into the &os; | |||||
handbook. The basics for how to get a system running must be | |||||
documented, although not necessarily for every single board or | |||||
system a Tier 2 architecture supports. The supported hardware | |||||
list must exist and should be relatively recent. It should be | |||||
integrated into the &os; documentation.</para> | |||||
<para>Current Tier 2 platforms are &arch.arm;, &arch.arm64;, | |||||
&arch.ia64; (through &os; 10), | |||||
&arch.pc98;, &arch.powerpc;, and &arch.sparc64;.</para> | |||||
</sect2> | |||||
<sect2> | |||||
<title>Tier 3: Experimental Architectures</title> | |||||
<para>Tier 3 platforms are not supported by the security officer | |||||
and release engineering teams. At the discretion of the | |||||
toolchain maintainers, they may be supported in the toolchain. | |||||
Tier 3 platforms are architectures in the early stages of | |||||
development, for non-mainstream hardware platforms, or which | |||||
are considered legacy systems unlikely to see broad future | |||||
use. Initial support for Tier 3 platforms should be worked on | |||||
in external SCM repositories. | |||||
The transition to &os;'s subversion should take place after | |||||
the platform boots multi-user on hardware; sharing via | |||||
subversion is needed for wider exposure; and multiple | |||||
developers are actively working on the platform. | |||||
Platforms that transition to Tier 3 status may be | |||||
removed from the tree if they are no longer actively supported | |||||
by the &os; developer community at the discretion of the | |||||
release engineer.</para> | |||||
<para>Tier 3 platforms may have ports support, either integrated | |||||
or external, but do not require it.</para> | |||||
<para>Tier 3 platforms must have the basics documented for how | |||||
to build a kernel and how to boot it on at least one target | |||||
hardware or emulation environment. This documentation need | |||||
not be integrated into the &os; tree.</para> | |||||
<para>Current Tier 3 platforms are &arch.mips;, and | |||||
&arch.riscv;.</para> | |||||
</sect2> | |||||
<sect2> | |||||
<title>Tier 4: Unsupported Architectures</title> | |||||
<para>Tier 4 systems are not supported in any form by the | |||||
project.</para> | |||||
<para>All systems not otherwise classified into a support tier | |||||
are Tier 4 systems. The &arch.ia64; platform is transitioning | |||||
to Tier 4 status in &os; 11.</para> | |||||
</sect2> | |||||
<sect2> | |||||
<title>Policy on Changing the Tier of an Architecture</title> | |||||
<para>Systems may only be moved from one tier to another by | |||||
approval of the &os; Core Team, which shall make that | |||||
decision in collaboration with the Security Officer, Release | |||||
Engineering, and toolchain maintenance teams.</para> | |||||
</sect2> | |||||
</sect1> | |||||
<sect1 xml:id="ports"> | <sect1 xml:id="ports"> | ||||
<title>Ports Specific FAQ</title> | <title>Ports Specific FAQ</title> | ||||
<qandaset> | <qandaset> | ||||
<qandadiv xml:id="ports-qa-adding"> | <qandadiv xml:id="ports-qa-adding"> | ||||
<title>Adding a New Port</title> | <title>Adding a New Port</title> | ||||
<qandaentry xml:id="ports-qa-add-new"> | <qandaentry xml:id="ports-qa-add-new"> | ||||
▲ Show 20 Lines • Show All 501 Lines • ▼ Show 20 Lines | |||||
Do you want to commit? (no = start a shell) [y/n]</screen> | Do you want to commit? (no = start a shell) [y/n]</screen> | ||||
<para>At that point, the script will either open a shell | <para>At that point, the script will either open a shell | ||||
for you to fix things, or open your text editor with the | for you to fix things, or open your text editor with the | ||||
commit message all prepared and then commit the | commit message all prepared and then commit the | ||||
merge.</para> | merge.</para> | ||||
<para>The script assumes that you can connect to | <para>The script assumes that you can connect to | ||||
<literal>repo.FreeBSD.org</literal> with | <literal>repo.freebsd.org</literal> with | ||||
<application>SSH</application> directly, so if your | <application>SSH</application> directly, so if your | ||||
local login name is different than your &os; cluster | local login name is different than your &os; cluster | ||||
account, you need a few lines in your | account, you need a few lines in your | ||||
<filename>~/.ssh/config</filename>:</para> | <filename>~/.ssh/config</filename>:</para> | ||||
<programlisting>Host repo.freebsd.org # Can be *.freebsd.org | <programlisting>Host repo.freebsd.org # Can be *.freebsd.org | ||||
User <replaceable>freebsd-login</replaceable></programlisting> | User <replaceable>freebsd-login</replaceable></programlisting> | ||||
▲ Show 20 Lines • Show All 237 Lines • ▼ Show 20 Lines | <qandaentry xml:id="ports-qa-misc-correctly-building"> | ||||
<question> | <question> | ||||
<para>How do I know if my port is building correctly or | <para>How do I know if my port is building correctly or | ||||
not?</para> | not?</para> | ||||
</question> | </question> | ||||
<answer> | <answer> | ||||
<para>The packages are built multiple times each week. If | <para>The packages are built multiple times each week. If | ||||
a port fails, the maintainer will receive an email from | a port fails, the maintainer will receive an email from | ||||
<literal>pkg-fallout@FreeBSD.org</literal>.</para> | <literal>pkg-fallout@freebsd.org</literal>.</para> | ||||
<para>Reports for all the package builds (official, | <para>Reports for all the package builds (official, | ||||
experimental, and non-regression) are aggregated at | experimental, and non-regression) are aggregated at | ||||
<link | <link | ||||
xlink:href="https://pkg-status.freebsd.org/">pkg-status.FreeBSD.org</link>.</para> | xlink:href="http://pkg-status.freebsd.org/">pkg-status.freebsd.org</link>.</para> | ||||
</answer> | </answer> | ||||
</qandaentry> | </qandaentry> | ||||
<qandaentry xml:id="ports-qa-misc-INDEX"> | <qandaentry xml:id="ports-qa-misc-INDEX"> | ||||
<question> | <question> | ||||
<para>I added a new port. Do I need to add it to the | <para>I added a new port. Do I need to add it to the | ||||
<filename>INDEX</filename>?</para> | <filename>INDEX</filename>?</para> | ||||
</question> | </question> | ||||
▲ Show 20 Lines • Show All 61 Lines • ▼ Show 20 Lines | <answer> | ||||
<para>Full package builds will be done with the patches | <para>Full package builds will be done with the patches | ||||
provided by the submitter, and the submitter is required | provided by the submitter, and the submitter is required | ||||
to fix detected problems (<emphasis>fallout</emphasis>) | to fix detected problems (<emphasis>fallout</emphasis>) | ||||
before commit.</para> | before commit.</para> | ||||
<procedure> | <procedure> | ||||
<step> | <step> | ||||
<para>Go to the <link | <para>Go to the <link | ||||
xlink:href="https://bugs.freebsd.org/submit">Bugzilla | xlink:href="http://bugs.freebsd.org/submit">Bugzilla | ||||
new <acronym>PR</acronym> page</link>.</para> | new <acronym>PR</acronym> page</link>.</para> | ||||
</step> | </step> | ||||
<step> | <step> | ||||
<para>Select the product your patch is about.</para> | <para>Select the product your patch is about.</para> | ||||
</step> | </step> | ||||
<step> | <step> | ||||
Show All 30 Lines | <para>When the &a.portmgr; replies, fix the fallout. | ||||
</step> | </step> | ||||
</procedure> | </procedure> | ||||
</answer> | </answer> | ||||
</qandaentry> | </qandaentry> | ||||
</qandadiv> | </qandadiv> | ||||
</qandaset> | </qandaset> | ||||
</sect1> | </sect1> | ||||
<sect1 xml:id="non-committers"> | |||||
<title>Issues Specific to Developers Who Are Not | |||||
Committers</title> | |||||
<para>A few people who have access to the &os; machines do not | |||||
have commit bits. Almost all of this document will apply to | |||||
these developers as well (except things specific to commits and | |||||
the mailing list memberships that go with them). In particular, | |||||
we recommend that you read:</para> | |||||
<itemizedlist> | |||||
<listitem> | |||||
<para><link linkend="admin">Administrative | |||||
Details</link></para> | |||||
</listitem> | |||||
<listitem> | |||||
<para><link | |||||
linkend="conventions-everyone">Conventions</link></para> | |||||
<note> | |||||
<para>You should get your mentor to add you to the | |||||
<quote>Additional Contributors</quote> | |||||
(<filename>doc/en_US.ISO8859-1/articles/contributors/contrib.additional.xml</filename>), | |||||
if you are not already listed there.</para> | |||||
</note> | |||||
</listitem> | |||||
<listitem> | |||||
<para><link linkend="developer.relations">Developer | |||||
Relations</link></para> | |||||
</listitem> | |||||
<listitem> | |||||
<para><link linkend="ssh.guide">SSH Quick-Start | |||||
Guide</link></para> | |||||
</listitem> | |||||
<listitem> | |||||
<para><link linkend="rules">The &os; Committers' Big List | |||||
of Rules</link></para> | |||||
</listitem> | |||||
</itemizedlist> | |||||
</sect1> | |||||
<sect1 xml:id="google-analytics"> | <sect1 xml:id="google-analytics"> | ||||
<title>Information About &ga;</title> | <title>Information About &ga;</title> | ||||
editor_callfortesting.orgAuthorUnsubmitted Not Done Inline ActionsWhy is this here? editor_callfortesting.org: Why is this here? | |||||
<para>As of December 12, 2012, &ga; was enabled on the | <para>As of December 12, 2012, &ga; was enabled on the | ||||
&os; Project website to collect anonymized usage statistics | &os; Project website to collect anonymized usage statistics | ||||
regarding usage of the site. The information collected is | regarding usage of the site. The information collected is | ||||
valuable to the &os; Documentation Project, in order to | valuable to the &os; Documentation Project, in order to | ||||
identify various problems on the &os; website.</para> | identify various problems on the &os; website.</para> | ||||
<sect2 xml:id="google-analytics-policy"> | <sect2 xml:id="google-analytics-policy"> | ||||
<title>&ga; General Policy</title> | <title>&ga; General Policy</title> | ||||
<para>The &os; Project takes visitor privacy very | <para>The &os; Project takes visitor privacy very | ||||
seriously. As such, the &os; Project website honors the | seriously. As such, the &os; Project website honors the | ||||
<quote>Do Not Track</quote> header <emphasis>before</emphasis> | <quote>Do Not Track</quote> header <emphasis>before</emphasis> | ||||
fetching the tracking code from Google. For more information, | fetching the tracking code from Google. For more information, | ||||
please see the | please see the | ||||
<link xlink:href="http://www.FreeBSD.org/privacy.html">&os; | <link xlink:href="http://www.freebsd.org/privacy.html">&os; | ||||
Privacy Policy</link>.</para> | Privacy Policy</link>.</para> | ||||
<para>&ga; access is <emphasis>not</emphasis> arbitrarily | <para>&ga; access is <emphasis>not</emphasis> arbitrarily | ||||
allowed — access must be requested, voted on by the | allowed — access must be requested, voted on by the | ||||
&a.doceng;, and explicitly granted.</para> | &a.doceng;, and explicitly granted.</para> | ||||
<para>Requests for &ga; data must include a specific purpose. | <para>Requests for &ga; data must include a specific purpose. | ||||
For example, a valid reason for requesting access would be | For example, a valid reason for requesting access would be | ||||
▲ Show 20 Lines • Show All 81 Lines • ▼ Show 20 Lines | <para>To add a file onto a branch, simply checkout or update | ||||
<link linkend="subversion-primer">Subversion Primer</link> | <link linkend="subversion-primer">Subversion Primer</link> | ||||
for details on how to perform an MFC.</para> | for details on how to perform an MFC.</para> | ||||
</answer> | </answer> | ||||
</qandaentry> | </qandaentry> | ||||
<qandaentry> | <qandaentry> | ||||
<question> | <question> | ||||
<para>How do I access <systemitem | <para>How do I access <systemitem | ||||
class="fqdomainname">people.FreeBSD.org</systemitem> to | class="fqdomainname">people.freebsd.org</systemitem> to | ||||
put up personal or project information?</para> | put up personal or project information?</para> | ||||
</question> | </question> | ||||
<answer> | <answer> | ||||
<para><systemitem | <para><systemitem | ||||
class="fqdomainname">people.FreeBSD.org</systemitem> is | class="fqdomainname">people.freebsd.org</systemitem> is | ||||
the same as <systemitem | the same as <systemitem | ||||
class="fqdomainname">freefall.FreeBSD.org</systemitem>. | class="fqdomainname">freefall.freebsd.org</systemitem>. | ||||
Just create a <filename>public_html</filename> directory. | Just create a <filename>public_html</filename> directory. | ||||
Anything you place in that directory will automatically be | Anything you place in that directory will automatically be | ||||
visible under <uri | visible under <uri | ||||
xlink:href="http://people.FreeBSD.org/">http://people.FreeBSD.org/</uri>.</para> | xlink:href="http://people.freebsd.org/">http://people.freebsd.org/</uri>.</para> | ||||
</answer> | </answer> | ||||
</qandaentry> | </qandaentry> | ||||
<qandaentry> | <qandaentry> | ||||
<question> | <question> | ||||
<para>Where are the mailing list archives stored?</para> | <para>Where are the mailing list archives stored?</para> | ||||
</question> | </question> | ||||
<answer> | <answer> | ||||
<para>The mailing lists are archived under | <para>The mailing lists are archived under | ||||
<filename>/local/mail</filename> on <systemitem | <filename>/local/mail</filename> on <systemitem | ||||
class="fqdomainname" | class="fqdomainname" | ||||
>freefall.FreeBSD.org</systemitem>.</para> | >freefall.freebsd.org</systemitem>.</para> | ||||
</answer> | </answer> | ||||
</qandaentry> | </qandaentry> | ||||
<qandaentry> | |||||
<question> | |||||
<para>I would like to mentor a new committer. What process | |||||
do I need to follow?</para> | |||||
</question> | |||||
<answer> | |||||
<para>See the <link | |||||
xlink:href="http://www.freebsd.org/internal/new-account.html">New | |||||
Account Creation Procedure</link> document on the | |||||
internal pages.</para> | |||||
</answer> | |||||
</qandaentry> | |||||
</qandaset> | </qandaset> | ||||
</sect1> | </sect1> | ||||
<sect1 xml:id="benefits"> | |||||
<title>Benefits and Perks for &os; Comitters</title> | |||||
<sect2 xml:id="benefits-recognition"> | |||||
<title>Recognition</title> | |||||
<para>Recognition as a competent software engineer is the | |||||
longest lasting value. In addition, getting a chance to work | |||||
with some of the best people that every engineer would dream | |||||
of meeting is a great perk!</para> | |||||
</sect2> | |||||
<sect2 xml:id="benefits-freebsdmall"> | |||||
<title>FreeBSD Mall</title> | |||||
<para>&os; committers can get a free 4-CD or DVD set at | |||||
conferences from | |||||
<link xlink:href="http://www.freebsdmall.com">&os; Mall, | |||||
Inc.</link>.</para> | |||||
</sect2> | |||||
<sect2 xml:id="benefits-irc"> | |||||
<title><acronym>IRC</acronym></title> | |||||
<para>In addition, developers may request a cloaked hostmask | |||||
for their account on the Freenode IRC network in the form | |||||
of | |||||
<literal>freebsd/developer/</literal><replaceable>freefall | |||||
name</replaceable> or | |||||
<literal>freebsd/developer/</literal><replaceable>NickServ | |||||
name</replaceable>. To request a cloak, send an email to | |||||
&a.irc.email; with your requested hostmask and NickServ | |||||
account name.</para> | |||||
</sect2> | |||||
<sect2 xml:id="benefits-gandi"> | |||||
<title><systemitem | |||||
class="domainname">Gandi.net</systemitem></title> | |||||
<para>Gandi provides website hosting, cloud computing, domain | |||||
registration, and X.509 certificate services.</para> | |||||
<para>Gandi offers an E-rate discount to all &os; developers. | |||||
Send mail to <email>non-profit@gandi.net</email> using your | |||||
<literal>@freebsd.org</literal> mail address, and indicate | |||||
your Gandi handle.</para> | |||||
</sect2> | |||||
</sect1> | |||||
</article> | </article> |
This should not change. Not sure why it did.