Differential D16089 Diff 44738 en_US.ISO8859-1/articles/committers-guide/article.xml

Changeset View

Standalone View

en_US.ISO8859-1/articles/committers-guide/article.xml

Show First 20 Lines • Show All 3,162 Lines • ▼ Show 20 Lines	*/</programlisting>
<para>When in doubt on any procedure, ask first!</para>		<para>When in doubt on any procedure, ask first!</para>
</listitem>		</listitem>

<listitem>		<listitem>
<para>Test your changes before committing them.</para>		<para>Test your changes before committing them.</para>
</listitem>		</listitem>

<listitem>		<listitem>
<para>Do not commit to anything under the		<para>Do not commit to contributed software without
<filename>src/contrib</filename>,
<filename>src/crypto</filename>, or
<filename>src/sys/contrib</filename> trees without
<emphasis>explicit</emphasis> approval from the respective		<emphasis>explicit</emphasis> approval from the respective
maintainers.</para>		maintainers.</para>
</listitem>		</listitem>

<listitem>		<listitem>
<para>Avoid private technical discussions.</para>		<para>Avoid private technical discussions.</para>
</listitem>		</listitem>
</orderedlist>		</orderedlist>
▲ Show 20 Lines • Show All 289 Lines • ▼ Show 20 Lines	<para>This may sound obvious, but the requirements are not
running that code.		running that code.
Refer to the		Refer to the
<link xlink:href="https://www.FreeBSD.org/internal/">&os;		<link xlink:href="https://www.FreeBSD.org/internal/">&os;
Internal Page</link> for a list of available		Internal Page</link> for a list of available
resources to help test.</para>		resources to help test.</para>
</listitem>		</listitem>

<listitem>		<listitem>
<para>Do not commit to anything under the		<para>Do not commit to contributed software without
<filename>src/contrib</filename>,
<filename>src/crypto</filename>, and
<filename>src/sys/contrib</filename> trees without
<emphasis>explicit</emphasis> approval from the respective		<emphasis>explicit</emphasis> approval from the respective
maintainers.</para>		maintainers.</para>

		<para>Contributed software is anything under the
		<filename>src/contrib</filename>,
		<filename>src/crypto</filename>, or
		<filename>src/sys/contrib</filename> trees.</para>

<para>The trees mentioned above are for contributed software		<para>The trees mentioned above are for contributed software
usually imported onto a vendor branch. Committing		usually imported onto a vendor branch. Committing
something there, even if it does not take the file off the		something there, may cause unnecessary headaches for
		jhbUnsubmitted Done Inline Actions s/for when/when/ jhb: s/for when/when/
vendor branch, may cause unnecessary headaches for those		when importing newer versions of the software. Strongly
responsible for maintaining that particular piece of		consider sending patches upstream to the vendor. Patches
		emasteUnsubmitted Done Inline Actions I might write "As a general rule" instead of "Strongly consider" emaste: I might write "As a general rule" instead of "Strongly consider"
		rpokalaUnsubmitted Not Done Inline Actions "general consider" => "general rule, consider" rpokala: "general consider" => "general rule, consider"
software. Thus, unless you have		may be committed to FreeBSD first with permission of the
<emphasis>explicit</emphasis> approval from the maintainer		maintainer.</para>
		emasteUnsubmitted Done Inline Actions comma not needed emaste: comma not needed
(or you are the maintainer), do <emphasis>not</emphasis>
commit there!</para>

<!-- FIXME: this paragraph should be rewritten -->		<para>Avoid comitting trivial or cosmetic changes to files
		jhbUnsubmitted Done Inline Actions s/comitting/committing/ jhb: s/comitting/committing/
<para>Please note that this does not mean you should not try		since it makes every merge thereafter more
to improve the software in question; you are still more		difficult: such patches need to be manually re-verified
than welcome to do so. Ideally, submit your		every import.</para>
		seancUnsubmitted Done Inline Actions Can we strengthen the language here slightly? Something like: `contrib/` software is home to various forks of upstream software that the FreeBSD Project has agreed to maintain locally. The reasons for maintaining a fork ranges from wanting strict control over a tightly coupled dependency to lack of portability or trust in the canonical repository's distribution of their code. Regardless of the reason(s), effort to minimize the maintenance burden of fork is helpful to fellow maintainers. seanc: Can we strengthen the language here slightly? Something like: > `contrib/` software is home…
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		<para>If a particular piece of software lacks a maintainer,
maintainership of an unmaintained part of the tree.</para>		you're encouraged to take up owership. If you're unsure
		seancUnsubmitted Done Inline Actions you're encourage to take up ownership (or reevaluate whether or not we need to maintain our own independent fork and can possibly get by with a ports-managed) distribution of the contributed software. If we don't have a maintainer for something it's also worth providing a small hint that we can also reexamine whether or not we want the code in `contrib/` at all. This advice isn't limited to `contrib/` but bears repetition because our forks are always inherently out of date with the canonical upstream repository. seanc: > you're encourage to take up ownership (or reevaluate whether or not we need to maintain our…
		eadlerAuthorUnsubmitted Done Inline Actions I'd rather not add this. It leads to the "What should be in base" debate. Unless and until we have a meaningful standard for that, this will just result in bikesheds. eadler: I'd rather not add this. It leads to the "What should be in base" debate. Unless and until we…
		of the current maintainership email &a.arch; and
		rpokalaUnsubmitted Not Done Inline Actions "maintainership email" => "maintainership, email" rpokala: "maintainership email" => "maintainership, email"
		ask.</para>
</listitem>		</listitem>
		rpokalaUnsubmitted Not Done Inline Actions "every import." => "as part of every import." or "after every import." rpokala: "every import." => "as part of every import." or "after every import."

<listitem>		<listitem>
<para>Avoid private technical discussions.</para>		<para>Avoid private technical discussions.</para>

<para>Discussing technical topics in public is almost always		<para>Discussing technical topics in public is almost always
better than not. &os; is an Open Source project for which		better than not. &os; is an Open Source project for which
<emphasis>Open</emphasis> is as important as writing		<emphasis>Open</emphasis> is as important as writing
source code. Default to public unless there is an		source code. Default to public unless there is an
▲ Show 20 Lines • Show All 1,559 Lines • ▼ Show 20 Lines	</listitem>
</itemizedlist>		</itemizedlist>
</sect2>		</sect2>
</sect1>		</sect1>

<sect1 xml:id="misc">		<sect1 xml:id="misc">
<title>Miscellaneous Questions</title>		<title>Miscellaneous Questions</title>

<qandaset>		<qandaset>
<qandaentry>
<question>
<para>Why are trivial or cosmetic changes to files on a
vendor branch a bad idea?</para>
</question>

<answer>
<itemizedlist>
<listitem>
<para>From now on, every new vendor release of that file
will need to have patches merged in by hand.</para>
</listitem>

<listitem>
<para>From now on, every new vendor release of that file
will need to have patches
<emphasis>verified</emphasis> by hand.</para>
</listitem>
</itemizedlist>
</answer>
</qandaentry>

<qandaentry>		<qandaentry>
<question>		<question>
<para>How do I add a new file to a branch?</para>		<para>How do I add a new file to a branch?</para>
</question>		</question>

<answer>		<answer>
<para>To add a file onto a branch, simply checkout or update		<para>To add a file onto a branch, simply checkout or update
to the branch you want to add to and then add the file		to the branch you want to add to and then add the file
▲ Show 20 Lines • Show All 108 Lines • Show Last 20 Lines