Page MenuHomeFreeBSD
Files F112002329

No OneTemporary
Actions

View Options

Index: head/en_US.ISO8859-1/books/developers-handbook/policies/chapter.xml
===================================================================
--- head/en_US.ISO8859-1/books/developers-handbook/policies/chapter.xml (revision 53700)
+++ head/en_US.ISO8859-1/books/developers-handbook/policies/chapter.xml (revision 53701)
@@ -1,612 +1,612 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!--
The FreeBSD Documentation Project
$FreeBSD$
-->
<chapter xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
xml:id="policies">
<info>
<title>Source Tree Guidelines and Policies</title>
<authorgroup>
<author>
<personname>
<firstname>Poul-Henning</firstname>
<surname>Kamp</surname>
</personname>
<contrib>Contributed by </contrib>
</author>
<author>
<personname>
<firstname>Giorgos</firstname>
<surname>Keramidas</surname>
</personname>
</author>
</authorgroup>
</info>
<para>This chapter documents various guidelines and policies in
force for the FreeBSD source tree.</para>
<sect1 xml:id="policies-style">
<title>Style Guidelines</title>
<indexterm><primary>style</primary></indexterm>
<para>Consistent coding style is extremely important, particularly
with large projects like &os;. Code should follow the &os;
coding styles described in &man.style.9; and
&man.style.Makefile.5;.</para>
</sect1>
<sect1 xml:id="policies-maintainer">
<title><varname>MAINTAINER</varname> on Makefiles</title>
<indexterm><primary>ports maintainer</primary></indexterm>
<para>If a particular portion of the &os;
<filename>src/</filename> distribution is being maintained by a
person or group of persons, this is communicated through an
entry in <filename>src/MAINTAINERS</filename>. Maintainers of
ports within the Ports Collection express their maintainership
to the world by adding a <varname>MAINTAINER</varname> line to
the <filename>Makefile</filename> of the port in
question:</para>
<programlisting><varname>MAINTAINER</varname>= <replaceable>email-addresses</replaceable></programlisting>
<tip>
<para>For other parts of the repository, or for sections not
listed as having a maintainer, or when you are unsure who the
active maintainer is, try looking at the recent commit history
of the relevant parts of the source tree. It is quite often
the case that a maintainer is not explicitly named, but the
people who are actively working in a part of the source tree
for, say, the last couple of years are interested in reviewing
changes. Even if this is not specifically mentioned in the
documentation or the source itself, asking for a review as a
form of courtesy is a very reasonable thing to do.</para>
</tip>
<para>The role of the maintainer is as follows:</para>
<itemizedlist>
<listitem>
<para>The maintainer owns and is responsible for that code.
This means that he or she is responsible for fixing bugs and
answering problem reports pertaining to that piece of the
code, and in the case of contributed software, for tracking
new versions, as appropriate.</para>
</listitem>
<listitem>
<para>Changes to directories which have a maintainer defined
shall be sent to the maintainer for review before being
committed. Only if the maintainer does not respond for an
unacceptable period of time, to several emails, will it be
acceptable to commit changes without review by the
maintainer. However, it is suggested that you try to have
the changes reviewed by someone else if at all
possible.</para>
</listitem>
<listitem>
<para>It is of course not acceptable to add a person or group
as maintainer unless they agree to assume this duty. On the
other hand it does not have to be a committer and it can
easily be a group of people.</para>
</listitem>
</itemizedlist>
</sect1>
<sect1 xml:id="policies-contributed">
<info>
<title>Contributed Software</title>
<authorgroup>
<author>
<personname>
<firstname>Poul-Henning</firstname>
<surname>Kamp</surname>
</personname>
<contrib>Contributed by </contrib>
</author>
<author>
<personname>
<firstname>David</firstname>
<surname>O'Brien</surname>
</personname>
</author>
<author>
<personname>
<firstname>Gavin</firstname>
<surname>Atkinson</surname>
</personname>
</author>
</authorgroup>
</info>
<indexterm><primary>contributed software</primary></indexterm>
<para>Some parts of the FreeBSD distribution consist of software
that is actively being maintained outside the FreeBSD project.
For historical reasons, we call this
<emphasis>contributed</emphasis> software. Some examples are
<application>sendmail</application>,
<application>gcc</application> and
<application>patch</application>.</para>
<para>Over the last couple of years, various methods have been
used in dealing with this type of software and all have some
number of advantages and drawbacks. No clear winner has
emerged.</para>
<para>Since this is the case, after some debate one of these
methods has been selected as the <quote>official</quote> method
and will be required for future imports of software of this
kind. Furthermore, it is strongly suggested that existing
contributed software converge on this model over time, as it has
significant advantages over the old method, including the
ability to easily obtain diffs relative to the
<quote>official</quote> versions of the source by everyone (even
without direct repository access). This will make it
significantly easier to return changes to the primary developers
of the contributed software.</para>
<para>Ultimately, however, it comes down to the people actually
doing the work. If using this model is particularly unsuited to
the package being dealt with, exceptions to these rules may be
granted only with the approval of the core team and with the
general consensus of the other developers. The ability to
maintain the package in the future will be a key issue in the
decisions.</para>
<note>
<para>Because it makes it harder to import future versions
minor, trivial and/or cosmetic changes are
<emphasis>strongly discouraged</emphasis> on files that are
still tracking the vendor branch.</para>
</note>
<sect2 xml:id="vendor-import-svn">
<info>
<title>Vendor Imports with SVN</title>
<authorgroup>
<author>
<personname>
<firstname>Dag-Erling</firstname>
<surname>Sm&oslash;rgrav</surname>
</personname>
<contrib>Contributed by </contrib>
</author>
</authorgroup>
</info>
<para>This section describes the vendor import procedure with
<application>Subversion</application> in details.</para>
<procedure>
<step>
<title>Preparing the Tree</title>
<para>If this is your first import after the switch to
<acronym>SVN</acronym>, you will have to flatten and clean
up the vendor tree, and bootstrap merge history in the
main tree. If not, you can safely omit this step.</para>
<para>During the conversion from <acronym>CVS</acronym> to
<acronym>SVN</acronym>, vendor branches were imported with
the same layout as the main tree. For example, the
<application>foo</application> vendor sources ended up in
<filename>vendor/<replaceable>foo</replaceable>/dist/contrib/<replaceable>foo</replaceable></filename>,
but it is pointless and rather inconvenient. What we
really want is to have the vendor source directly in
<filename>vendor/<replaceable>foo</replaceable>/dist</filename>,
like this:</para>
<screen>&prompt.user; <userinput>cd vendor/<replaceable>foo</replaceable>/dist/contrib/<replaceable>foo</replaceable></userinput>
&prompt.user; <userinput>svn move $(svn list) ../..</userinput>
&prompt.user; <userinput>cd ../..</userinput>
&prompt.user; <userinput>svn remove contrib</userinput>
&prompt.user; <userinput>svn propdel -R svn:mergeinfo</userinput>
&prompt.user; <userinput>svn commit</userinput></screen>
<para>Note that, the <literal>propdel</literal> bit is
necessary because starting with 1.5, Subversion will
automatically add <literal>svn:mergeinfo</literal> to any
directory you copy or move. In this case, you will not
need this information, since you are not going to merge
anything from the tree you deleted.</para>
<note>
<para>You may want to flatten the tags as well. The
procedure is exactly the same. If you do this, put off
the commit until the end.</para>
</note>
<para>Check the <filename>dist</filename> tree and perform
any cleanup that is deemed to be necessary. You may want
to disable keyword expansion, as it makes no sense on
unmodified vendor code. In some cases, it can be even be
harmful.</para>
<screen>&prompt.user; <userinput>svn propdel svn:keywords -R .</userinput>
&prompt.user; <userinput>svn commit</userinput></screen>
<para>Bootstrapping of <literal>svn:mergeinfo</literal> on
the target directory (in the main tree) to the revision
that corresponds to the last change was made to the vendor
tree prior to importing new sources is also needed:</para>
<screen>&prompt.user; <userinput>cd head/contrib/<replaceable>foo</replaceable></userinput>
-&prompt.user; <userinput>svn merge --record-only <replaceable>svn_base</replaceable>/vendor/<replaceable>foo</replaceable>/dist@<replaceable>12345678</replaceable> .</userinput>
+&prompt.user; <userinput>svn merge --record-only ^/vendor/<replaceable>foo</replaceable>/dist@<replaceable>12345678</replaceable> .</userinput>
&prompt.user; <userinput>svn commit</userinput></screen>
- <para>where <replaceable>svn_base</replaceable> is the base
- directory of your <acronym>SVN</acronym> repository, e.g.,
- <literal>svn+ssh://svn.FreeBSD.org/base</literal>.</para>
+ <para>With some shells, the <literal>^</literal> in the
+ above command may need to be escaped with a
+ backslash.</para>
</step>
<step>
<title>Importing New Sources</title>
<para>Prepare a full, clean tree of the vendor sources.
With <acronym>SVN</acronym>, we can keep a full
distribution in the vendor tree without bloating the main
tree. Import everything but merge only what is
needed.</para>
<para>Note that you will need to add any files that were
added since the last vendor import, and remove any that
were removed. To facilitate this, you should prepare
sorted lists of the contents of the vendor tree and of the
sources you are about to import:</para>
<screen>&prompt.user; <userinput>cd vendor/<replaceable>foo</replaceable>/dist</userinput>
&prompt.user; <userinput>svn list -R | grep -v '/$' | sort &gt; ../<replaceable>old</replaceable></userinput>
&prompt.user; <userinput>cd ../<replaceable>foo-9.9</replaceable></userinput>
&prompt.user; <userinput>find . -type f | cut -c 3- | sort &gt; ../<replaceable>new</replaceable></userinput></screen>
<para>With these two files, the following command will list
removed files (files only in
<filename><replaceable>old</replaceable></filename>):</para>
<screen>&prompt.user; <userinput>comm -23 ../<replaceable>old</replaceable> ../<replaceable>new</replaceable></userinput></screen>
<para>While the command below will list added files (files
only in
<filename><replaceable>new</replaceable></filename>):</para>
<screen>&prompt.user; <userinput>comm -13 ../<replaceable>old</replaceable> ../<replaceable>new</replaceable></userinput></screen>
<para>Let us put this together:</para>
<screen>&prompt.user; <userinput>cd vendor/<replaceable>foo</replaceable>/<replaceable>foo-9.9</replaceable></userinput>
&prompt.user; <userinput>tar cf - . | tar xf - -C ../dist</userinput>
&prompt.user; <userinput>cd ../dist</userinput>
&prompt.user; <userinput>comm -23 ../<replaceable>old</replaceable> ../<replaceable>new</replaceable> | xargs svn remove</userinput>
&prompt.user; <userinput>comm -13 ../<replaceable>old</replaceable> ../<replaceable>new</replaceable> | xargs svn add</userinput></screen>
<warning>
<para>If there are new directories in the new
distribution, the last command will fail. You will have
to add the directories, and run it again. Conversely,
if any directories were removed, you will have to remove
them manually.</para>
</warning>
<para>Check properties on any new files:</para>
<itemizedlist>
<listitem>
<para>All text files
should have <literal>svn:eol-style</literal> set to
<literal>native</literal>.</para>
</listitem>
<listitem>
<para>All binary files should have
<literal>svn:mime-type</literal> set to
<literal>application/octet-stream</literal>, unless
there is a more appropriate media type.</para>
</listitem>
<listitem>
<para>Executable files should have
<literal>svn:executable</literal> set to
<literal>*</literal>.</para>
</listitem>
<listitem>
<para>There should be no other properties on any file in
the tree.</para>
</listitem>
</itemizedlist>
<note>
<para>You are ready to commit, but you should first check
the output of <command>svn stat</command> and
<command>svn diff</command> to make sure everything is
in order.</para>
</note>
<para>Once you have committed the new vendor release, you
should tag it for future reference. The best and quickest
way is to do it directly in the repository:</para>
- <screen>&prompt.user; <userinput>svn copy <replaceable>svn_base</replaceable>/vendor/<replaceable>foo</replaceable>/dist <replaceable>svn_base</replaceable>/vendor/<replaceable>foo</replaceable>/<replaceable>9.9</replaceable></userinput></screen>
+ <screen>&prompt.user; <userinput>svn copy ^/vendor/<replaceable>foo</replaceable>/dist <replaceable>svn_base</replaceable>/vendor/<replaceable>foo</replaceable>/<replaceable>9.9</replaceable></userinput></screen>
<para>To get the new tag, you can update your working copy
of
<filename>vendor/<replaceable>foo</replaceable></filename>.</para>
<note>
<para>If you choose to do the copy in the checkout
instead, do not forget to remove the generated
<literal>svn:mergeinfo</literal> as described
above.</para>
</note>
</step>
<step>
<title>Merging to <emphasis>-HEAD</emphasis></title>
<para>After you have prepared your import, it is time to
merge. Option <option>--accept=postpone</option> tells
<acronym>SVN</acronym> not to handle merge conflicts yet,
because they will be taken care of manually:</para>
<screen>&prompt.user; <userinput>cd head/contrib/<replaceable>foo</replaceable></userinput>
&prompt.user; <userinput>svn update</userinput>
-&prompt.user; <userinput>svn merge --accept=postpone <replaceable>svn_base</replaceable>/vendor/<replaceable>foo</replaceable>/dist</userinput></screen>
+&prompt.user; <userinput>svn merge --accept=postpone ^/vendor/<replaceable>foo</replaceable>/dist</userinput></screen>
<para>Resolve any conflicts, and make sure that any files
that were added or removed in the vendor tree have been
properly added or removed in the main tree. It is always
a good idea to check differences against the vendor
branch:</para>
- <screen>&prompt.user; <userinput>svn diff --no-diff-deleted --old=<replaceable>svn_base</replaceable>/vendor/<replaceable>foo</replaceable>/dist --new=.</userinput></screen>
+ <screen>&prompt.user; <userinput>svn diff --no-diff-deleted --old=^/vendor/<replaceable>foo</replaceable>/dist --new=.</userinput></screen>
<para><option>--no-diff-deleted</option> tells
<acronym>SVN</acronym> not to check files that are in the
vendor tree but not in the main tree.</para>
<note>
<para>With <acronym>SVN</acronym>, there is no concept of
on or off the vendor branch. If a file that previously
had local modifications no longer does, just remove any
left-over cruft, such as &os; version tags, so it no
longer shows up in diffs against the vendor tree.</para>
</note>
<para>If any changes are required for the world to build
with the new sources, make them now &mdash; and test until
you are satisfied that everything build and runs
correctly.</para>
</step>
<step>
<title>Commit</title>
<para>Now, you are ready to commit. Make sure you get
everything in one go. Ideally, you would have done all
steps in a clean tree, in which case you can just commit
from the top of that tree. That is the best way to avoid
surprises. If you do it properly, the tree will move
atomically from a consistent state with the old code to a
consistent state with the new code.</para>
</step>
</procedure>
</sect2>
</sect1>
<sect1 xml:id="policies-encumbered">
<title>Encumbered Files</title>
<para>It might occasionally be necessary to include an encumbered
file in the FreeBSD source tree. For example, if a device
requires a small piece of binary code to be loaded to it before
the device will operate, and we do not have the source to that
code, then the binary file is said to be encumbered. The
following policies apply to including encumbered files in the
FreeBSD source tree.</para>
<orderedlist>
<listitem>
<para>Any file which is interpreted or executed by the system
CPU(s) and not in source format is encumbered.</para>
</listitem>
<listitem>
<para>Any file with a license more restrictive than BSD or GNU
is encumbered.</para>
</listitem>
<listitem>
<para>A file which contains downloadable binary data for use
by the hardware is not encumbered, unless (1) or (2) apply
to it. It must be stored in an architecture neutral ASCII
format (file2c or uuencoding is recommended).</para>
</listitem>
<listitem>
<para>Any encumbered file requires specific approval from the
<link
xlink:href="&url.base;/administration.html#t-core">Core
Team</link> before it is added to the repository.</para>
</listitem>
<listitem>
<para>Encumbered files go in <filename>src/contrib</filename>
or <filename>src/sys/contrib</filename>.</para>
</listitem>
<listitem>
<para>The entire module should be kept together. There is no
point in splitting it, unless there is code-sharing with
non-encumbered code.</para>
</listitem>
<listitem>
<para>Object files are named
<filename><replaceable>arch</replaceable>/<replaceable>filename</replaceable>.o.uu&gt;</filename>.</para>
</listitem>
<listitem>
<para>Kernel files:</para>
<orderedlist>
<listitem>
<para>Should always be referenced in
<filename>conf/files.*</filename> (for build
simplicity).</para>
</listitem>
<listitem>
<para>Should always be in <filename>LINT</filename>, but
the <link
xlink:href="&url.base;/administration.html#t-core">Core
Team</link> decides per case if it should be commented
out or not. The <link
xlink:href="&url.base;/administration.html#t-core">Core
Team</link> can, of course, change their minds later
on.</para>
</listitem>
<listitem>
<para>The <firstterm>Release Engineer</firstterm>
decides whether or not it goes into the release.</para>
</listitem>
</orderedlist>
</listitem>
<listitem>
<para>User-land files:</para>
<orderedlist>
<listitem>
<para>The <link
xlink:href="&url.base;/administration.html#t-core">Core
team</link><indexterm><primary>core
team</primary></indexterm> decides if the code
should be part of <command>make world</command>.</para>
</listitem>
<listitem>
<para>The <link
xlink:href="&url.base;/administration.html#t-re">Release
Engineering</link><indexterm><primary>release
engineering</primary></indexterm> decides if it goes
into the release.</para>
</listitem>
</orderedlist>
</listitem>
</orderedlist>
</sect1>
<sect1 xml:id="policies-shlib">
<info>
<title>Shared Libraries</title>
<authorgroup>
<author>
<personname>
<firstname>Satoshi</firstname>
<surname>Asami</surname>
</personname>
<contrib>Contributed by </contrib>
</author>
<author>
<personname>
<firstname>Peter</firstname>
<surname>Wemm</surname>
</personname>
</author>
<author>
<personname>
<firstname>David</firstname>
<surname>O'Brien</surname>
</personname>
</author>
</authorgroup>
</info>
<para>If you are adding shared library support to a port or other
piece of software that does not have one, the version numbers
should follow these rules. Generally, the resulting numbers
will have nothing to do with the release version of the
software.</para>
<para>The three principles of shared library building are:</para>
<itemizedlist>
<listitem>
<para>Start from <literal>1.0</literal></para>
</listitem>
<listitem>
<para>If there is a change that is backwards compatible, bump
minor number (note that ELF systems ignore the minor
number)</para>
</listitem>
<listitem>
<para>If there is an incompatible change, bump major
number</para>
</listitem>
</itemizedlist>
<para>For instance, added functions and bugfixes result in the
minor version number being bumped, while deleted functions,
changed function call syntax, etc. will force the major version
number to change.</para>
<para>Stick to version numbers of the form major.minor
(<replaceable>x</replaceable>.<replaceable>y</replaceable>).
Our a.out dynamic linker does not handle version numbers of the
form
<replaceable>x</replaceable>.<replaceable>y</replaceable>.<replaceable>z</replaceable>
well. Any version number after the <replaceable>y</replaceable>
(i.e., the third digit) is totally ignored when comparing shared
lib version numbers to decide which library to link with. Given
two shared libraries that differ only in the
<quote>micro</quote> revision, <command>ld.so</command> will
link with the higher one. That is, if you link with
<filename>libfoo.so.3.3.3</filename>, the linker only records
<literal>3.3</literal> in the headers, and will link with
anything starting with
<replaceable>libfoo.so.3</replaceable>.<replaceable>(anything
&gt;= 3)</replaceable>.<replaceable>(highest
available)</replaceable>.</para>
<note>
<para><command>ld.so</command> will always use the highest
<quote>minor</quote> revision. For instance, it will use
<filename>libc.so.2.2</filename> in preference to
<filename>libc.so.2.0</filename>, even if the program was
initially linked with <filename>libc.so.2.0</filename>.</para>
</note>
<para>In addition, our ELF dynamic linker does not handle minor
version numbers at all. However, one should still specify a
major and minor version number as our
<filename>Makefile</filename>s <quote>do the right thing</quote>
based on the type of system.</para>
<para>For non-port libraries, it is also our policy to change the
shared library version number only once between releases. In
addition, it is our policy to change the major shared library
version number only once between major OS releases (i.e., from
6.0 to 7.0). When you make a change to a system library that
requires the version number to be bumped, check the
<filename>Makefile</filename>'s commit logs. It is the
responsibility of the committer to ensure that the first such
change since the release will result in the shared library
version number in the <filename>Makefile</filename> to be
updated, and any subsequent changes will not.</para>
</sect1>
</chapter>

File Metadata

Mime Type
text/x-diff
Expires
Thu, Mar 13, 10:23 AM (1 d, 7 h)
Storage Engine
blob
Storage Format
Raw Data
Storage Handle
17117797
Default Alt Text
(24 KB)

Event Timeline