<?xml version="1.0" encoding="iso-8859-1"?>
<!--
     The FreeBSD Documentation Project

     $FreeBSD$
-->

<chapter id="policies">
  <chapterinfo>
    <authorgroup>
      <author>
	<firstname>Poul-Henning</firstname>
	<surname>Kamp</surname>
	<contrib>Contributed by </contrib>
      </author>
     <author>
	<firstname>Giorgos</firstname>
	<surname>Keramidas</surname>
      </author>
    </authorgroup>
    <!-- June 1996 -->
  </chapterinfo>

  <title>Source Tree Guidelines and Policies</title>

  <para>This chapter documents various guidelines and policies in force for
    the FreeBSD source tree.</para>

  <sect1 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 id="policies-maintainer">
    <title><makevar>MAINTAINER</makevar> 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 the
      <filename>src/MAINTAINERS</filename> file.  Maintainers of ports
      within the Ports Collection express their maintainership to the
      world by adding a <makevar>MAINTAINER</makevar> line to the
      <filename>Makefile</filename> of the port in question:</para>

    <programlisting><makevar>MAINTAINER</makevar>= <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 id="policies-contributed">
    <sect1info>
      <authorgroup>
	<author>
	  <firstname>Poul-Henning</firstname>
	  <surname>Kamp</surname>
	  <contrib>Contributed by </contrib>
	</author>
	<author>
	  <firstname>David</firstname>
	  <surname>O'Brien</surname>
	</author>
	<author>
	  <firstname>Gavin</firstname>
	  <surname>Atkinson</surname>
	</author>
      </authorgroup>
      <!-- June 1996 -->
    </sect1info>

    <title>Contributed Software</title>

    <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 id="vendor-import-svn">
      <sect2info>
	<authorgroup>
	  <author>
	    <firstname>Dag-Erling</firstname>
	    <surname>Sm&oslash;rgrav</surname>
	    <contrib>Contributed by </contrib>
	  </author>
	</authorgroup>
      </sect2info>
      <title>Vendor Imports with SVN</title>

      <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><command>cd</command> <filename class="directory">vendor/<replaceable>foo</replaceable>/dist/contrib/<replaceable>foo</replaceable></filename></userinput>
&prompt.user; <userinput><command>svn move</command> $(svn list) <filename>../..</filename></userinput>
&prompt.user; <userinput><command>cd</command> <filename>../..</filename></userinput>
&prompt.user; <userinput><command>svn remove</command> <filename>contrib</filename></userinput>
&prompt.user; <userinput><command>svn propdel</command> <option>-R</option> svn:mergeinfo</userinput>
&prompt.user; <userinput><command>svn commit</command></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><command>svn propdel</command> svn:keywords <option>-R</option> <filename>.</filename></userinput>
&prompt.user; <userinput><command>svn commit</command></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><command>cd</command> <filename>head/contrib/<replaceable>foo</replaceable></filename></userinput>
&prompt.user; <userinput><command>svn merge</command> <option>--record-only</option> <replaceable>svn_base</replaceable>/vendor/<replaceable>foo</replaceable>/dist@<replaceable>12345678</replaceable> <filename>.</filename></userinput>
&prompt.user; <userinput><command>svn commit</command></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>
	</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><command>cd</command> <filename>vendor/<replaceable>foo</replaceable>/dist</filename></userinput>
&prompt.user; <userinput><command>svn list</command> <option>-R</option> | <command>grep</command> <option>-v</option> '/$' | <command>sort</command> > <filename>../<replaceable>old</replaceable></filename></userinput>
&prompt.user; <userinput><command>cd</command> <filename>../<replaceable>foo-9.9</replaceable></filename></userinput>
&prompt.user; <userinput><command>find</command> <filename>.</filename> <option>-type</option> f | <command>cut</command> <option>-c</option> 3- | <command>sort</command> > <filename>../<replaceable>new</replaceable></filename></userinput></screen>

	  <para>With these two files, the following command will list
	    list removed files (files only in
	    <filename><replaceable>old</replaceable></filename>):</para>

	  <screen>&prompt.user; <userinput><command>comm <option>-23</option> <filename>../<replaceable>old</replaceable></filename> <filename>../<replaceable>new</replaceable></filename></command></userinput></screen>

	  <para>While the command below will list added files (files
	    only in
	    <filename><replaceable>new</replaceable></filename>):</para>

	  <screen>&prompt.user; <userinput><command>comm <option>-13</option> <filename>../<replaceable>old</replaceable></filename> <filename>../<replaceable>new</replaceable></filename></command></userinput></screen>

	  <para>Let's put this together:</para>

	  <screen>&prompt.user; <userinput><command>cd</command> <filename class="directory">vendor/<replaceable>foo</replaceable>/<replaceable>foo-9.9</replaceable></filename></userinput>
&prompt.user; <userinput><command>tar</command> cf - <filename>.</filename> | <command>tar</command> xf - <option>-C</option> <filename>../dist</filename></userinput>
&prompt.user; <userinput><command>cd</command> <filename class="directory">../dist</filename></userinput>
&prompt.user; <userinput><command>comm</command> <option>-23</option> <filename>../<replaceable>old</replaceable></filename> <filename>../<replaceable>new</replaceable></filename> | <command>xargs</command> svn remove</userinput>
&prompt.user; <userinput><command>comm</command> <option>-13</option> <filename>../<replaceable>old</replaceable></filename> <filename>../<replaceable>new</replaceable></filename> | <command>xargs</command> 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><command>svn copy</command> <filename><replaceable>svn_base</replaceable>/vendor/<replaceable>foo</replaceable>/dist</filename> <filename><replaceable>svn_base</replaceable>/vendor/<replaceable>foo</replaceable>/<replaceable>9.9</replaceable></filename></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><command>cd</command> <filename class="directory">head/contrib/<replaceable>foo</replaceable></filename></userinput>
&prompt.user; <userinput><command>svn update</command></userinput>
&prompt.user; <userinput><command>svn merge</command> <option>--accept=postpone</option> <filename><replaceable>svn_base</replaceable>/vendor/<replaceable>foo</replaceable>/dist</filename></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><command>svn diff</command> <option>--no-diff-deleted</option> <option>--old=</option><filename><replaceable>svn_base</replaceable>/vendor/<replaceable>foo</replaceable>/dist</filename> <option>--new=</option><filename>.</filename></userinput></screen>

	  <para>The <option>--no-diff-deleted</option> 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 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
	  <ulink url="&url.base;/administration.html#t-core">Core Team</ulink> 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></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
	      <ulink url="&url.base;/administration.html#t-core">Core Team</ulink> decides per case if it
	      should be commented out or not.  The
	      <ulink url="&url.base;/administration.html#t-core">Core Team</ulink> 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>
            <indexterm><primary>core team</primary></indexterm>
            <para>The <ulink url="&url.base;/administration.html#t-core">Core team</ulink> decides if
              the code should be part of <command>make world</command>.</para>
          </listitem>

          <listitem>
            <indexterm><primary>release engineering</primary></indexterm>
            <para>The <ulink url="&url.base;/administration.html#t-re">Release Engineering</ulink>
              decides if it goes into the release.</para>
          </listitem>
        </orderedlist>
      </listitem>
    </orderedlist>
  </sect1>

  <sect1 id="policies-shlib">
    <sect1info>
      <authorgroup>
	<author>
	  <firstname>Satoshi</firstname>
	  <surname>Asami</surname>
	  <contrib>Contributed by </contrib>
	</author>
	<author>
	  <firstname>Peter</firstname>
	  <surname>Wemm</surname>
	</author>
	<author>
	  <firstname>David</firstname>
	  <surname>O'Brien</surname>
	</author>
      </authorgroup>
      <!-- 9 Dec 1996 -->
    </sect1info>

    <title>Shared Libraries</title>

    <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>