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> | |||||
<para>Avoid private technical discussions.</para> | |||||
</listitem> | |||||
</orderedlist> | </orderedlist> | ||||
<para>As noted, breaking some of these rules can be grounds for | <para>As noted, breaking some of these rules can be grounds for | ||||
suspension or, upon repeated offense, permanent removal of | suspension or, upon repeated offense, permanent removal of | ||||
commit privileges. Individual members of core have the power to | commit privileges. Individual members of core have the power to | ||||
temporarily suspend commit privileges until core as a whole has | temporarily suspend commit privileges until core as a whole has | ||||
the chance to review the issue. In case of an | the chance to review the issue. In case of an | ||||
<quote>emergency</quote> (a committer doing damage to the | <quote>emergency</quote> (a committer doing damage to the | ||||
▲ Show 20 Lines • Show All 137 Lines • ▼ Show 20 Lines | <para>Many parts of &os; are not <quote>owned</quote> in | ||||
for documentation on this. Where sections of code have | for documentation on this. Where sections of code have | ||||
several maintainers, commits to affected areas by one | several maintainers, commits to affected areas by one | ||||
maintainer need to be reviewed by at least one other | maintainer need to be reviewed by at least one other | ||||
maintainer. In cases where the | maintainer. In cases where the | ||||
<quote>maintainer-ship</quote> of something is not clear, | <quote>maintainer-ship</quote> of something is not clear, | ||||
look at the repository logs for the files | look at the repository logs for the files | ||||
in question and see if someone has been working recently | in question and see if someone has been working recently | ||||
or predominantly in that area.</para> | 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">https://www.FreeBSD.org/administration.html</link> | |||||
for more information on this.</para> | |||||
</listitem> | </listitem> | ||||
<listitem> | <listitem> | ||||
<para>Any disputed change must be backed out pending | <para>Any disputed change must be backed out pending | ||||
resolution of the dispute if requested by a maintainer. | resolution of the dispute if requested by a maintainer. | ||||
Security related changes may override a maintainer's | Security related changes may override a maintainer's | ||||
wishes at the Security Officer's discretion.</para> | wishes at the Security Officer's discretion.</para> | ||||
▲ Show 20 Lines • Show All 113 Lines • ▼ Show 20 Lines | <para>Many mistakes are made because someone is in a hurry | ||||
<quote>how in the heck do I do this?</quote> We already | <quote>how in the heck do I do this?</quote> We already | ||||
know you are an intelligent person; otherwise, you would | know you are an intelligent person; otherwise, you would | ||||
not be a committer.</para> | not be a committer.</para> | ||||
</listitem> | </listitem> | ||||
<listitem> | <listitem> | ||||
<para>Test your changes before committing them.</para> | <para>Test your changes before committing them.</para> | ||||
<!-- XXX Needs update re sparc64 + pc98 | <para>This may sound obvious, but the requirements are not | ||||
Also, needs more details on which machines are available for testing | always obvious. Make sure that | ||||
--> | <command>make tinderbox</command> still passes. Some | ||||
<para>This may sound obvious, but if it really were so | changes may pass on one architecture but will fail on | ||||
obvious then we probably would not see so many cases of | another. Seemingly small changes, such as printf format | ||||
people clearly not doing this. If your changes are to the | strings, are often the cause of build failures. If your | ||||
kernel, make sure you can still compile both GENERIC and | changes are to a branch, | ||||
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 | make sure your testing occurs with a machine which is | ||||
running that code. If you have a change which also may | running that code. | ||||
break another architecture, be sure and test on all | Refer to the | ||||
supported architectures. Please 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 resources. | Internal Page</link> for a list of available | ||||
As other architectures are added to the &os; supported | resources to help test.</para> | ||||
platforms list, the appropriate shared testing resources | |||||
will be made available.</para> | |||||
</listitem> | </listitem> | ||||
<listitem> | <listitem> | ||||
<para>Do not commit to anything under the | <para>Do not commit to contributed software without | ||||
imp: this duplicates the above. | |||||
Not Done Inline ActionsOne's the title, the other is the details. I'll update to make this a bit clearer. eadler: One's the title, the other is the details. I'll update to make this a bit clearer. | |||||
<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 | ||||
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 | ||||
software. Thus, unless you have | may be committed to FreeBSD first with permission of the | ||||
<emphasis>explicit</emphasis> approval from the maintainer | maintainer.</para> | ||||
(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 | ||||
<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> | ||||
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 | ||||
of the current maintainership email &a.arch; and | |||||
ask.</para> | |||||
</listitem> | </listitem> | ||||
<listitem> | |||||
<para>Avoid private technical discussions.</para> | |||||
<para>Discussing technical topics in public is almost always | |||||
better than not. &os; is an Open Source project for which | |||||
seancUnsubmitted Not Done Inline ActionsErr... wait. This is a value judgement that isn't necessarily true and that it's worth teasing out a bit of nuance. Discussing technical topics in public casts a wide net and may attract a wide audience of participants. A wide net of participants cuts in two ways:
It is not uncommon for people to not realize the limitations in their understanding and to participate. One consequence of this phenomena is that qualified opinions will need to either wade through this discussion (which expends precious effort and executive capacity). It is also entirely too common for participation in a discussion to be misconstrued as authority or domain expertise. I'm not suggesting it is unimportant to invest in teaching people and to grow the community, but it's also important to be mindful of the activation energy of getting someone qualified to participate in community discussions. The results of private discussions should always be made public for the benefit of the community. We have many examples of this where subject matter experts get together in small groups or offline to discuss many different technical details. This offline practice is generally perceived to be helpful and appreciated by participants. The objection is the word "always." I agree with the rest of the paragraph in that FreeBSD is an open source operating system, however our goal is to ship the best open code available. Given that a number of us are commercially oriented in our thinking and motivations, this also means that we're on the clock with regards to our contributions and need to be efficient in our use of everyone's time. We put process guidelines in place to aid in good and healthy outcomes and to strike a balance between open and fully transparent, and productive and efficient. Would it be possible to rephrase this in the positive instead? Something like: <listeitem> <para>Conduct discussions in public or report the results of discussions to public forums.</para> <para>&os is a trusted Open Source project because of its emphasis on transparency and disclosure. Where reasonable, conducting discussions in public forums is encouraged (notably because there is no effort required to summarize the outcome for the public). Where this is not possible, due to subject mater expertise or timeliness, the results of technical discussions and topics should be made public so the project's working memory can be enriched through a shared understanding of the outcome from subject matter experts. The trade-off of productivity from focused conversations vs the cost of summarizing the outcome of a discussion is left to the best judgement of the participants.</para> <para>If you think something should be discussed in public, suggest to the other participants to have the discussion in public, or to make the summary available of a discussion available so the community at large may benefit from the rationale that lead up to a decision. Reminder: it is not acceptable to unilaterally make a discussion or summary available in a public forum without consent (e.g. &a.developers; or private correspondence). In the end, use good judgement to facilitate productive communication practices between individuals and be mindful of our open source community writ-large (including but not limited to: commercial users, appliance vendors, open source enthusiasts, students, and service providers).</para> </listitem> Does that work for you? If so, can you also chase that updated title elsewhere in this patch?
seanc: Err... wait. This is a value judgement that isn't necessarily true and that it's worth teasing… | |||||
eadlerAuthorUnsubmitted Not Done Inline Actions(I have some more to say here, but it is getting late for me. I don't necessarily agree with the text as above). I will also split up this review into separate ones since I figured out an easier way to handle this on my side, and the different patches are not conflicting as I thought they might be. eadler: (I have some more to say here, but it is getting late for me. I don't necessarily agree with… | |||||
<emphasis>Open</emphasis> is as important as writing | |||||
source code. Default to public unless there is an | |||||
explicit and clear reason for it to be private.</para> | |||||
<para>People who are not a part of the immediate convertion | |||||
bcrUnsubmitted Not Done Inline Actionss/convertion/conversation/ bcr: s/convertion/conversation/ | |||||
will be interested in both the result, and the motivation | |||||
for how that decision was made.</para> | |||||
<para>This default applies to both private emails between | |||||
developers, and the internal adminstrative lists (such as | |||||
&a.developers;.) This does not provide the right to | |||||
reveal private conversations without permission, but you | |||||
bcrUnsubmitted Not Done Inline Actionsthere is an "are" missing here after "you" bcr: there is an "are" missing here after "you" | |||||
encouraged to withhold a reply until the requestor asks in | |||||
a more public forum.</para> | |||||
<para>It is worth reading the section of | |||||
<link xlink:href="https://producingoss.com/en/setting-tone.html#avoid-private-discussions">Producing Open Source</link> on this topic.</para> | |||||
bcrUnsubmitted Not Done Inline ActionsYou can pull the "<link" part into the previous line, break it at "xlink" (indenting that one) and break the line after "Producing" again. bcr: You can pull the "<link" part into the previous line, break it at "xlink" (indenting that one)… | |||||
</listitem> | |||||
</orderedlist> | </orderedlist> | ||||
</sect2> | </sect2> | ||||
<sect2> | <sect2> | ||||
<title>Policy on Multiple Architectures</title> | <title>Policy on Multiple Architectures</title> | ||||
<para>&os; has added several new architecture ports during | <para>&os; has added several new architecture ports during | ||||
recent release cycles and is truly no longer an &i386; centric | recent release cycles and is truly no longer an &i386; centric | ||||
Not Done Inline ActionsThis needs a lot of work, it's kinda preachy now imp: This needs a lot of work, it's kinda preachy now | |||||
operating system. In an effort to make it easier to keep | operating system. In an effort to make it easier to keep | ||||
Not Done Inline Actionsthis is a giant it depends. There's often times that it's useful to poll others privately about a change you think might be contentious to build consensus or to learn of obvious pitfalls before proposing something in public. There's times when asking person X directly beats asking on the mailing list because X is the one who knows things the best, but rarely reads mailing lists. There are other times that public discussions are quite useful. I don't think we can have such a wide-reaching blanket statement, especially if people take a too-expansive view on this and use it as a stick to beat developers who, frankly, have done nothing wrong. imp: this is a giant it depends. There's often times that it's useful to poll others privately about… | |||||
&os; portable across the platforms we support, core has | &os; portable across the platforms we support, core has | ||||
developed this mandate:</para> | developed this mandate:</para> | ||||
<blockquote> | <blockquote> | ||||
<para>Our 32-bit reference platform is &arch.i386;, and our | <para>Our 32-bit reference platform is &arch.i386;, and our | ||||
64-bit reference platform is &arch.amd64;. Major design | 64-bit reference platform is &arch.amd64;. Major design | ||||
work (including major API and ABI changes) must prove | work (including major API and ABI changes) must prove | ||||
itself on at least one 32-bit and at least one 64-bit | itself on at least one 32-bit and at least one 64-bit | ||||
▲ Show 20 Lines • Show All 896 Lines • ▼ Show 20 Lines | <para>Fixing <link | ||||
<listitem> | <listitem> | ||||
<para>Backport of security and reliability fixes which | <para>Backport of security and reliability fixes which | ||||
only result in <varname>PORTREVISION</varname> bumps | only result in <varname>PORTREVISION</varname> bumps | ||||
and no changes to enabled features. for example, | and no changes to enabled features. for example, | ||||
adding a patch fixing a buffer overflow.</para> | adding a patch fixing a buffer overflow.</para> | ||||
</listitem> | </listitem> | ||||
<listitem> | <listitem> | ||||
<para>Minor version changes that do nothing but fix | |||||
Not Done Inline Actionsignore this part. Its pending a separate review. eadler: ignore this part. Its pending a separate review. | |||||
security or crash-related issues.</para> | |||||
</listitem> | |||||
<listitem> | |||||
<para>Adding/fixing | <para>Adding/fixing | ||||
<varname>CONFLICTS</varname>.</para> | <varname>CONFLICTS</varname>.</para> | ||||
</listitem> | </listitem> | ||||
<listitem> | <listitem> | ||||
<para>Web Browsers, browser plugins, and their | <para>Web Browsers, browser plugins, and their | ||||
required dependencies.</para> | required dependencies.</para> | ||||
</listitem> | </listitem> | ||||
▲ Show 20 Lines • Show All 608 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 |
this duplicates the above.