Finished section 3 on interacting with developers.. just one more

Author: mako
Date: 2001/03/26 22:36:51
Finished section 3 on interacting with developers.. just one more
section to go on interacting with users (4 subsections) before the
first draft is finished.

diff --git a/FreeSoftwareDevelopmentHOWTO.sgml b/FreeSoftwareDevelopmentHOWTO.sgml
index 1ef34da105487a0d776c6d2e935023fe3ccd20ef..ad8e78fca92668f97ad78843d822a183b00189c9 100644 (file)
--- a/FreeSoftwareDevelopmentHOWTO.sgml
+++ b/FreeSoftwareDevelopmentHOWTO.sgml
@@ -1217,9 +1217,9 @@ pages for more information and options.
 
  <sect1 id="developers">
   <title>Maintaining a Project: Interacting with Developers</title>
 
  <sect1 id="developers">
   <title>Maintaining a Project: Interacting with Developers</title>

-   <indexterm>
-    <primary>fswd!developers</primary>
-   </indexterm>
+  <indexterm>
+   <primary>fswd!developers</primary>
+  </indexterm>

 
   <para>
    Once you have gotten the project started, you have gotten over the
 
   <para>
    Once you have gotten the project started, you have gotten over the


@@ -1232,8 +1232,18 @@ pages for more information and options.
   </para>
 
   <para>
   </para>
 
   <para>

-   The difference between free software development and propriety
-   software development is th developer base. As the leader of a free
+   In releasing your program, your program becomes free software. This
+   transition is more than just a larger user base. By releasing your
+   program as free software, <emphasis>your</emphasis> software
+   becomes the <emphasis>free software community's</emphasis>
+   software. The direction of your software's development will be
+   reshaped, redirected, and fully determined by your users and, to a
+   larger extent, by other developers in the community.
+  </para>
+
+  <para>
+   The major difference between free software development and propriety
+   software development is the developer base. As the leader of a free

    software project, you need to attract and keep developers in a way
    that leaders of proprietary software projects sipmly don't have to
    worry about. <emphasis>As the person leading development of a free
    software project, you need to attract and keep developers in a way
    that leaders of proprietary software projects sipmly don't have to
    worry about. <emphasis>As the person leading development of a free


@@ -1293,7 +1303,12 @@ pages for more information and options.
  
     <para>
      Like anything, its easier to see how others delegate than to do
  
     <para>
      Like anything, its easier to see how others delegate than to do

-     it yourself. In a sentance: <emphasis>Keep an eye out for other
+     it yourself. You may find that other developers seem even more
+     experienced or knowledgeable than you. Your job as a maintainer
+     does not mean you have to have to be the best or the
+     brightest. It means you need are responsible for showing good
+     judgement and for recognizing solutions that are maintainable and
+     are not. In a sentance: <emphasis>Keep an eye out for other

      qualified developers who show an interest and sustained
      involvement with your project and try and shift responsibility
      towards them.</emphasis> The following ideas might be good places
      qualified developers who show an interest and sustained
      involvement with your project and try and shift responsibility
      towards them.</emphasis> The following ideas might be good places


@@ -1343,7 +1358,7 @@ pages for more information and options.
 
     </sect4>
 
 
     </sect4>
 

-    <sect4>
+    <sect4 id="releasemanager">

      <title>Publicly appoint someone as the release manager for a
        specific release.</title>
 
      <title>Publicly appoint someone as the release manager for a
        specific release.</title>
 


@@ -1363,7 +1378,7 @@ pages for more information and options.
      </para>
     </sect4>
 
      </para>
     </sect4>
 

-    <sect4>
+    <sect4 id="delegatebranch">

      <title>Delegate control of an entire branch.</title>
      <para>
       If your project chooses to have branches (as described in <xref
      <title>Delegate control of an entire branch.</title>
      <para>
       If your project chooses to have branches (as described in <xref


@@ -1390,35 +1405,395 @@ pages for more information and options.
 
   <sect2 id="patching">
    <title>Accepting and Rejecting Patches</title>
 
   <sect2 id="patching">
    <title>Accepting and Rejecting Patches</title>

-   <para></para>
-  </sect2>
+   <para>
+    This HOWTO has already touched on the fact that as the maintainer
+    of a free software project, one of primary and most important
+    responsibilities will be accepting and rejecting patches submitted
+    to you by other developers.
+   </para>
+
+   <sect3>
+    <title>Technical judgement</title>
+
+    <para>
+     In <emphasis>Open Source Development with CVS</emphasis>, Karl
+     Fogel makes a convincing argument that the most important things
+     to keep in mind are a firm knowledge of the scope of your program
+     (that's the <quote>idea</quote> I talked about in <xref
+     linkend="chooseproject">) and the ability to recognize,
+     facilitate, and direct <quote>evolution</quote> of a free
+     software program so that the program can grow and change and
+     incorporate functionatlity that was orignally unforseen but avoid
+     digressions that might expand the scope of the program too much
+     and result and push the project towards an early death under its
+     own weight and unweildiness. These are the criteria that you as a
+     project mainatiner should take into account each time you recieve
+     a patch.
+    </para>
+
+    <para>
+     Fogel elaborates on this again and states the <quote>the
+     questions to ask yourself when considering whether to implement
+     (or approve) a change are:</quote>
+    </para>
+
+    <para>
+     <itemizedlist>

 
 

+      <listitem>
+       <para>Will it benefit a significant percentage of the program's
+       user community?</para>
+      </listitem>
+
+      <listitem>
+       <para>Does it fit within the program's domain or within a
+       natural, intuitive extension of that domain?</para>
+      </listitem>
+
+     </itemizedlist>
+    </para>
+
+    <para>
+     The answers to these questions are never straighforward and its
+     very possible (and even likely) that the person who submitted the
+     patch may feel differently about the answer to those questions
+     than you do. However, if you feel that that the answer to either
+     of those questions is <quote>no,</quote> it is your responsiblity
+     to reject the change. If you fail to do this, the project will
+     become unweildy and unmaintainable and will ultimately fail.
+    </para>
+   </sect3>
+
+   <sect3>
+    <title>Rejecting patches</title>
+
+    <para>
+     Rejecting patches is probably the most difficult and the most
+     sesnative job that the maintainer of any free software project
+     has to face. But sometimes it has to be done. I mentioned earlier
+     (in <xref linkend="developers"> and in <xref
+     linkend="delegation">) that any developer needs to try and
+     balance your responsibility and power to make what you think are
+     the best technical decisions with the fact that you will lose
+     support from other developers if you seem like you are on a
+     powertrip or being overly bossy or possesive of a community-based
+     project. I recommend that you keep three major facts in mind when
+     rejecting patches (or other changes):
+    </para>
+
+    <sect4>
+     <title>Bring it to the community</title>
+     <para>
+      One of the best ways of justifying  a decision to reject a patch
+      and working  to  not seem like  you  keep an  iron grip  on your
+      project is by  not making the  decision  alone at all. It  might
+      make  sense  to  turn over  larger  proposed  changes  or more
+      difficult decisions to a development mailing list where they can
+      be discussed. There will be some patches (bug fixes, etc.) which
+      will  definately be accepted  and some that you  feel are so off
+      base that they do not even merit further discussion. It is those
+      that fall into the grey area between these two groups that might
+      merit a quick forward to a mailing list.
+     </para>
+
+     <para>
+      I recommend this process wholeheartedly. As the project
+      maintainer you are worried about making the best decision for
+      the project, for the project's users and developers, and for
+      yourself as a responsible project leader. Turning things over to
+      an email list will demonstrate your own responsible and
+      responsive leadership as it tests and serves the interests of
+      your software's community.
+     </para>
+    </sect4>
+
+    <sect4>
+     <title>Technical issues is not always good justification</title>
+     <para>
+      Especially towards the beginning, you will find that many
+      changes are difficult to implement, introduce new bugs, or have
+      other techincal problems. Try to see past these. Especially with
+      added functionality, good ideas do not always come from good
+      coders. Technical merit is a valid reason to postpone the
+      application of a patch but it is not always a good reason to
+      reject a change outright. Even small changes are worth the
+      effort of working with the submittor to iron out bugs and
+      incorporate the change if you thing you think it seems like a
+      good addition to your project. The effort on your part will work
+      to make your project a community project and it will pull a new
+      or less experienced developer onto your project and even teach
+      them something that might help them in their next patch.
+     </para>
+    </sect4>
+
+    <sect4>
+     <title>Common courtesy</title>
+     <para>
+      It should go without saying but, <emphasis>above all and in all
+      cases, just be nice.</emphasis> If someone has an idea and cares
+      about it enough to write some code and submit a patch, they
+      care, they are motivated, and they are already involved. Your
+      goal as the maintainer is make sure they submit again. They may
+      have thrown you a dud this time but next time may be the idea or
+      feature that revolutionizes your project. 
+     </para>
+
+     <para>
+      It is your responsibility to first justify your action to not
+      incorporate their change clearly and concisely. Then thank
+      them. Let them know that you a appreciate their help and feel
+      horrible that you can't incorproate their change. Let them know
+      that you look forward to their staying involved and you hope
+      that the next patch or idea meshes better with your project
+      because you appreciate their work and want to see it in the
+      project. If you have ever had a patch rejected that put a large
+      deal of time, thought, and energy into, you remember how it
+      feels and it feels bad. Keep this in mind when you have to let
+      someone down. It's never easy but you need to do everything you
+      have to make it as not-unpleasant as possible.
+     </para>
+    </sect4>
+   </sect3>
+  </sect2>

 
 <!-- Section2: branches  -->
 
   <sect2 id="branches">
    <title>Stable and Development Branches</title>
 
 <!-- Section2: branches  -->
 
   <sect2 id="branches">
    <title>Stable and Development Branches</title>

-   <para></para>
+
+   <para>
+    The idea of stable and development branches has already been
+    described briefly in <xref linkend="chooseversioning"> and in
+    <xref linkend="delegatebranch">. These alluses attest to the fact
+    to some of the ways that multiple branches can affect your
+    software. Branches can let you avoid (to some extent) some of the
+    problems around rejecting patches (as described in <xref
+    linkend="patching">) by allowing you to temporarily compromise the
+    stability of your project without affected those users who need
+    that stability.
+   </para>
+
+   <para>
+    The most common way of branching your project is to have one
+    branch that is stable and one that is development. This is the
+    model followed by the Linux kernel that is described in <xref
+    linkend="chooseversioning">. In this model, there is always one
+    branch that is stable and always one that is in
+    development. Before any new release, the development branch goes
+    into a <quote>feature freeze</quote> where major changes and added
+    features are rejected or put on hold under the development kernel
+    is released as the new stable branch and major development begins
+    again on the development branch. Bug fixes and small changes that
+    are unlikely to have any large negative reprocussion are
+    incorporated into the stable branch also to the development
+    branch.
+   </para>
+
+   <para>
+    Linux's model is an extreme one. On many projects, there is no
+    need to have two versions always available. It may make sense ot
+    have two versions only near a release. The Debian project has
+    historically made both a stable and an unstable distribution
+    available but has expanded to this to include: stable, unstable,
+    testing, experimental, and (around release time) a frozen
+    distribution that only incorporates bug fixes during the
+    transition from unstable to stable. There are few projects whose
+    size would necessitate a system like Debian but their use of
+    branches helps demonstrate how they can be used to balance
+    consitent and effective development with the need to make regular
+    and useable releases.
+   </para>
+
+   <para>
+    In trying to set up a development tree for yourself, there are
+    several things that might be useful to keep in mind:
+   </para>
+
+   <para>
+    <variablelist>
+
+     <varlistentry>
+      <term>Minimize the number of branches</term>
+      <listitem>
+       <para>
+        Debian may be able to make good use of four or five branches
+        but it contains gigabytes of software in over 5000 packages
+        compiled for a 5-6 different architectures. Two is a good
+        number. Too many branches will confuse your users (I can't
+        count how many times I had to describe debian's system when it
+        only had 2 and sometimes 3 branches!), potential developers
+        and even yourself. Branches can help but they come at a cost
+        so use them very sparingly.
+       </para>
+      </listitem>
+     </varlistentry>
+
+     <varlistentry>
+      <term>Make sure that all your different branches are explained</term>
+      <listitem>
+       <para>
+        As I mentioned in the preceeding paragraph, different branches
+        <emphasis>will</emphasis> confuse your users. Do everything
+        you can to avoid this by clearly explaining the different
+        branches in a promenant page on your website and in a Readme
+        file in the <acronym>FTP</acronym> or <acronym>HTTP</acronym>
+        directory.
+       </para>
+
+       <para>
+        I might also recommend against a mistake that I think Debian
+        has made. The terms <quote>unstable,</quote>
+        <quote>testing,</quote> and <quote>experimental</quote> are
+        vague and difficult to rank in order of stability (or
+        instability as the case may be). Try explaining to someone
+        that <quote>stable</quote> actually means <quote>ultra
+        stable</quote> and that <quote>unstable</quote> doesn't
+        actually include any unstable software but is really stable
+        software that is untested as a distribution.
+       </para>
+
+       <para>
+        If you are going to do branches, especially early on, keep in
+        mind that people are conditioned to understand the terms
+        <quote>stable</quote> and <quote>development</quote> and you
+        probaly can't go wrong with this simple and common division of
+        branches.
+       </para>
+      </listitem>
+     </varlistentry>
+
+     <varlistentry>
+      <term>Make sure all your branches are always available</term>
+      <listitem>
+       <para>
+        Like a lot of document, this should probably should go without
+        saying but experience has taught me that it's not always
+        obvious to people. It's a good idea to physicall split up
+        different branches in different directories or directory trees
+        on your <acronym>FTP</acronym> or <acronym>HTTP</acronym>
+        site. Linux accomplishes this by having all the v2.2 and a
+        v2.3 subdirectory where it is immediately obvious (after you
+        know their version numbering scheme) which directory is the
+        most recent stable and the current development
+        releases. Debian accomplishes this by naming all their
+        distribution by name and then changing symlinks named
+        <quote>stable,</quote> <quote>unstable</quote> and
+        <quote>frozen</quote> to point to which ever distribution (by
+        name) is in whatever stage. Both methods work and their are
+        others. In any case, it is important that different branches
+        are always available, are accessable from consistent
+        locations, and that different branches are clearly
+        distinguished from each other so your users know exactly what
+        they want to be downloading and where to get it.
+       </para>
+      </listitem>
+     </varlistentry>
+
+    </variablelist>
+   </para>
+

   </sect2>
 
 <!-- Section2: otherdev -->
 
   <sect2 id="otherdev">
    <title>Other Development issues</title>
   </sect2>
 
 <!-- Section2: otherdev -->
 
   <sect2 id="otherdev">
    <title>Other Development issues</title>

-   <para></para>
-  </sect2>
+   <para>
+    There are more issues around surrounding interaction with
+    developers in a free software project that I can touch on in great
+    detail in a HOWTO of this size. Please don't hesitate to contact
+    me if you see any major omissions. Other smaller issues that are
+    worth mentioning are:
+   </para>

 
 

+   <sect3>
+    <title>Freezing</title>
+    <para>
+     For those projects that choose to adopt a split development model
+     (<xref linkend="branches">), freezing is a concept that is worth
+     becoming familiar with. 
+    </para>
+
+    <para>
+     Freeze come in two major forms. A <quote>feature freeze</quote>
+     is a period when no signifigant functionality is added to a
+     program. It is a period where established functionality (even
+     skeletons of barely working functionality) can be improved and
+     perfected. It is a period where bugs are fixed. This type of
+     freeze is usually applied some period (a month or two) before a
+     release. It is easy to push a release back as you wait for
+     <quote>one more feature</quote> and a freeze helps to avoid this
+     situation by drawing the much neede line in the sand. It gives
+     developers room they need to get a program ready for release.
+    </para>
+
+    <para>
+     The second type of freeze is a <quote>code freeze</quote> which
+     is much more like a released piece of software. Once a piece of
+     software has entered a code freeze, all changes to the code are
+     frowned upon and only changes that fix known bugs are
+     permitted. This type of freeze usually follows a <quote>feature
+     freeze</quote> and directly preceeds a release. Most released
+     software is in what could be interpreted as a sort of high
+     level<quote>code freeze.</quote>
+    </para>
+
+    <para>
+     Even you do not choose to appoint a release manager (<xref
+     linkend="releasemanager">), you will have an easier time
+     justifying the rejection or postponement of patches (<xref
+     linkend="patching"> before a release with a publicly stated
+     freeze in effect.
+    </para>
+   </sect3>

 
 

+   <sect3>
+    <title>Forking</title>
+    <para>
+     Forks are the most extreme interpretation of a branch. A fork is
+     when a group of developers takes code from a free software
+     project and actually starts a brand new free software
+     project. The most famous example of a fork is Emacs and
+     XEmacs. Both emacsen are based on an almost identical codebase
+     but for technical, political, and philisophical reasons,
+     development was split into two projects which now compete with
+     each other.
+    </para>
+
+    <para>
+     The short version of the fork section is, <emphasis>don't do
+     them.</emphasis> Forks force developers to choose one project to
+     work with, cause nasty political divisions, redundancy of work.
+     Luckily, usually the threat of the fork is enough to scare the
+     maintainer or maintainers of a project into changing the way they
+     run their project to avoid it.
+    </para>
+
+    <para>
+     In his chapter on <quote>The Open Source Process,</quote> Karl
+     Fogel describes how to do a fork if you absolutely must. If you
+     have determined that is absolutely necessary and that the
+     differences between you and the people threatening to fork are
+     absolutely unresolvable, I recommend Fogel's book as a good place
+     to start.
+    </para>
+   </sect3>
+  </sect2>

  </sect1>
 
 <!-- Section1: users -->
 
  <sect1 id="users">
   <title>Maintaining a Project: Interacting with Users</title>
  </sect1>
 
 <!-- Section1: users -->
 
  <sect1 id="users">
   <title>Maintaining a Project: Interacting with Users</title>

+  <indexterm>
+   <primary>fswd!users</primary>
+  </indexterm>
+
+  <para>
+   If you've worked your way up to here, congratuatlions, you are
+   nearing the end of this document. This final section touches upon 
+  </para>

 
 

-   <indexterm>
-    <primary>fswd!users</primary>
-   </indexterm>

 
 <!-- Section2: testing -->
 
 
 <!-- Section2: testing -->
 

diff --git a/FreeSoftwareProjectManagementHOWTO.sgml b/FreeSoftwareProjectManagementHOWTO.sgml
index 1ef34da105487a0d776c6d2e935023fe3ccd20ef..ad8e78fca92668f97ad78843d822a183b00189c9 100644 (file)
--- a/FreeSoftwareProjectManagementHOWTO.sgml
+++ b/FreeSoftwareProjectManagementHOWTO.sgml
@@ -1217,9 +1217,9 @@ pages for more information and options.
 
  <sect1 id="developers">
   <title>Maintaining a Project: Interacting with Developers</title>
 
  <sect1 id="developers">
   <title>Maintaining a Project: Interacting with Developers</title>

-   <indexterm>
-    <primary>fswd!developers</primary>
-   </indexterm>
+  <indexterm>
+   <primary>fswd!developers</primary>
+  </indexterm>

 
   <para>
    Once you have gotten the project started, you have gotten over the
 
   <para>
    Once you have gotten the project started, you have gotten over the


@@ -1232,8 +1232,18 @@ pages for more information and options.
   </para>
 
   <para>
   </para>
 
   <para>

-   The difference between free software development and propriety
-   software development is th developer base. As the leader of a free
+   In releasing your program, your program becomes free software. This
+   transition is more than just a larger user base. By releasing your
+   program as free software, <emphasis>your</emphasis> software
+   becomes the <emphasis>free software community's</emphasis>
+   software. The direction of your software's development will be
+   reshaped, redirected, and fully determined by your users and, to a
+   larger extent, by other developers in the community.
+  </para>
+
+  <para>
+   The major difference between free software development and propriety
+   software development is the developer base. As the leader of a free

    software project, you need to attract and keep developers in a way
    that leaders of proprietary software projects sipmly don't have to
    worry about. <emphasis>As the person leading development of a free
    software project, you need to attract and keep developers in a way
    that leaders of proprietary software projects sipmly don't have to
    worry about. <emphasis>As the person leading development of a free


@@ -1293,7 +1303,12 @@ pages for more information and options.
  
     <para>
      Like anything, its easier to see how others delegate than to do
  
     <para>
      Like anything, its easier to see how others delegate than to do

-     it yourself. In a sentance: <emphasis>Keep an eye out for other
+     it yourself. You may find that other developers seem even more
+     experienced or knowledgeable than you. Your job as a maintainer
+     does not mean you have to have to be the best or the
+     brightest. It means you need are responsible for showing good
+     judgement and for recognizing solutions that are maintainable and
+     are not. In a sentance: <emphasis>Keep an eye out for other

      qualified developers who show an interest and sustained
      involvement with your project and try and shift responsibility
      towards them.</emphasis> The following ideas might be good places
      qualified developers who show an interest and sustained
      involvement with your project and try and shift responsibility
      towards them.</emphasis> The following ideas might be good places


@@ -1343,7 +1358,7 @@ pages for more information and options.
 
     </sect4>
 
 
     </sect4>
 

-    <sect4>
+    <sect4 id="releasemanager">

      <title>Publicly appoint someone as the release manager for a
        specific release.</title>
 
      <title>Publicly appoint someone as the release manager for a
        specific release.</title>
 


@@ -1363,7 +1378,7 @@ pages for more information and options.
      </para>
     </sect4>
 
      </para>
     </sect4>
 

-    <sect4>
+    <sect4 id="delegatebranch">

      <title>Delegate control of an entire branch.</title>
      <para>
       If your project chooses to have branches (as described in <xref
      <title>Delegate control of an entire branch.</title>
      <para>
       If your project chooses to have branches (as described in <xref


@@ -1390,35 +1405,395 @@ pages for more information and options.
 
   <sect2 id="patching">
    <title>Accepting and Rejecting Patches</title>
 
   <sect2 id="patching">
    <title>Accepting and Rejecting Patches</title>

-   <para></para>
-  </sect2>
+   <para>
+    This HOWTO has already touched on the fact that as the maintainer
+    of a free software project, one of primary and most important
+    responsibilities will be accepting and rejecting patches submitted
+    to you by other developers.
+   </para>
+
+   <sect3>
+    <title>Technical judgement</title>
+
+    <para>
+     In <emphasis>Open Source Development with CVS</emphasis>, Karl
+     Fogel makes a convincing argument that the most important things
+     to keep in mind are a firm knowledge of the scope of your program
+     (that's the <quote>idea</quote> I talked about in <xref
+     linkend="chooseproject">) and the ability to recognize,
+     facilitate, and direct <quote>evolution</quote> of a free
+     software program so that the program can grow and change and
+     incorporate functionatlity that was orignally unforseen but avoid
+     digressions that might expand the scope of the program too much
+     and result and push the project towards an early death under its
+     own weight and unweildiness. These are the criteria that you as a
+     project mainatiner should take into account each time you recieve
+     a patch.
+    </para>
+
+    <para>
+     Fogel elaborates on this again and states the <quote>the
+     questions to ask yourself when considering whether to implement
+     (or approve) a change are:</quote>
+    </para>
+
+    <para>
+     <itemizedlist>

 
 

+      <listitem>
+       <para>Will it benefit a significant percentage of the program's
+       user community?</para>
+      </listitem>
+
+      <listitem>
+       <para>Does it fit within the program's domain or within a
+       natural, intuitive extension of that domain?</para>
+      </listitem>
+
+     </itemizedlist>
+    </para>
+
+    <para>
+     The answers to these questions are never straighforward and its
+     very possible (and even likely) that the person who submitted the
+     patch may feel differently about the answer to those questions
+     than you do. However, if you feel that that the answer to either
+     of those questions is <quote>no,</quote> it is your responsiblity
+     to reject the change. If you fail to do this, the project will
+     become unweildy and unmaintainable and will ultimately fail.
+    </para>
+   </sect3>
+
+   <sect3>
+    <title>Rejecting patches</title>
+
+    <para>
+     Rejecting patches is probably the most difficult and the most
+     sesnative job that the maintainer of any free software project
+     has to face. But sometimes it has to be done. I mentioned earlier
+     (in <xref linkend="developers"> and in <xref
+     linkend="delegation">) that any developer needs to try and
+     balance your responsibility and power to make what you think are
+     the best technical decisions with the fact that you will lose
+     support from other developers if you seem like you are on a
+     powertrip or being overly bossy or possesive of a community-based
+     project. I recommend that you keep three major facts in mind when
+     rejecting patches (or other changes):
+    </para>
+
+    <sect4>
+     <title>Bring it to the community</title>
+     <para>
+      One of the best ways of justifying  a decision to reject a patch
+      and working  to  not seem like  you  keep an  iron grip  on your
+      project is by  not making the  decision  alone at all. It  might
+      make  sense  to  turn over  larger  proposed  changes  or more
+      difficult decisions to a development mailing list where they can
+      be discussed. There will be some patches (bug fixes, etc.) which
+      will  definately be accepted  and some that you  feel are so off
+      base that they do not even merit further discussion. It is those
+      that fall into the grey area between these two groups that might
+      merit a quick forward to a mailing list.
+     </para>
+
+     <para>
+      I recommend this process wholeheartedly. As the project
+      maintainer you are worried about making the best decision for
+      the project, for the project's users and developers, and for
+      yourself as a responsible project leader. Turning things over to
+      an email list will demonstrate your own responsible and
+      responsive leadership as it tests and serves the interests of
+      your software's community.
+     </para>
+    </sect4>
+
+    <sect4>
+     <title>Technical issues is not always good justification</title>
+     <para>
+      Especially towards the beginning, you will find that many
+      changes are difficult to implement, introduce new bugs, or have
+      other techincal problems. Try to see past these. Especially with
+      added functionality, good ideas do not always come from good
+      coders. Technical merit is a valid reason to postpone the
+      application of a patch but it is not always a good reason to
+      reject a change outright. Even small changes are worth the
+      effort of working with the submittor to iron out bugs and
+      incorporate the change if you thing you think it seems like a
+      good addition to your project. The effort on your part will work
+      to make your project a community project and it will pull a new
+      or less experienced developer onto your project and even teach
+      them something that might help them in their next patch.
+     </para>
+    </sect4>
+
+    <sect4>
+     <title>Common courtesy</title>
+     <para>
+      It should go without saying but, <emphasis>above all and in all
+      cases, just be nice.</emphasis> If someone has an idea and cares
+      about it enough to write some code and submit a patch, they
+      care, they are motivated, and they are already involved. Your
+      goal as the maintainer is make sure they submit again. They may
+      have thrown you a dud this time but next time may be the idea or
+      feature that revolutionizes your project. 
+     </para>
+
+     <para>
+      It is your responsibility to first justify your action to not
+      incorporate their change clearly and concisely. Then thank
+      them. Let them know that you a appreciate their help and feel
+      horrible that you can't incorproate their change. Let them know
+      that you look forward to their staying involved and you hope
+      that the next patch or idea meshes better with your project
+      because you appreciate their work and want to see it in the
+      project. If you have ever had a patch rejected that put a large
+      deal of time, thought, and energy into, you remember how it
+      feels and it feels bad. Keep this in mind when you have to let
+      someone down. It's never easy but you need to do everything you
+      have to make it as not-unpleasant as possible.
+     </para>
+    </sect4>
+   </sect3>
+  </sect2>

 
 <!-- Section2: branches  -->
 
   <sect2 id="branches">
    <title>Stable and Development Branches</title>
 
 <!-- Section2: branches  -->
 
   <sect2 id="branches">
    <title>Stable and Development Branches</title>

-   <para></para>
+
+   <para>
+    The idea of stable and development branches has already been
+    described briefly in <xref linkend="chooseversioning"> and in
+    <xref linkend="delegatebranch">. These alluses attest to the fact
+    to some of the ways that multiple branches can affect your
+    software. Branches can let you avoid (to some extent) some of the
+    problems around rejecting patches (as described in <xref
+    linkend="patching">) by allowing you to temporarily compromise the
+    stability of your project without affected those users who need
+    that stability.
+   </para>
+
+   <para>
+    The most common way of branching your project is to have one
+    branch that is stable and one that is development. This is the
+    model followed by the Linux kernel that is described in <xref
+    linkend="chooseversioning">. In this model, there is always one
+    branch that is stable and always one that is in
+    development. Before any new release, the development branch goes
+    into a <quote>feature freeze</quote> where major changes and added
+    features are rejected or put on hold under the development kernel
+    is released as the new stable branch and major development begins
+    again on the development branch. Bug fixes and small changes that
+    are unlikely to have any large negative reprocussion are
+    incorporated into the stable branch also to the development
+    branch.
+   </para>
+
+   <para>
+    Linux's model is an extreme one. On many projects, there is no
+    need to have two versions always available. It may make sense ot
+    have two versions only near a release. The Debian project has
+    historically made both a stable and an unstable distribution
+    available but has expanded to this to include: stable, unstable,
+    testing, experimental, and (around release time) a frozen
+    distribution that only incorporates bug fixes during the
+    transition from unstable to stable. There are few projects whose
+    size would necessitate a system like Debian but their use of
+    branches helps demonstrate how they can be used to balance
+    consitent and effective development with the need to make regular
+    and useable releases.
+   </para>
+
+   <para>
+    In trying to set up a development tree for yourself, there are
+    several things that might be useful to keep in mind:
+   </para>
+
+   <para>
+    <variablelist>
+
+     <varlistentry>
+      <term>Minimize the number of branches</term>
+      <listitem>
+       <para>
+        Debian may be able to make good use of four or five branches
+        but it contains gigabytes of software in over 5000 packages
+        compiled for a 5-6 different architectures. Two is a good
+        number. Too many branches will confuse your users (I can't
+        count how many times I had to describe debian's system when it
+        only had 2 and sometimes 3 branches!), potential developers
+        and even yourself. Branches can help but they come at a cost
+        so use them very sparingly.
+       </para>
+      </listitem>
+     </varlistentry>
+
+     <varlistentry>
+      <term>Make sure that all your different branches are explained</term>
+      <listitem>
+       <para>
+        As I mentioned in the preceeding paragraph, different branches
+        <emphasis>will</emphasis> confuse your users. Do everything
+        you can to avoid this by clearly explaining the different
+        branches in a promenant page on your website and in a Readme
+        file in the <acronym>FTP</acronym> or <acronym>HTTP</acronym>
+        directory.
+       </para>
+
+       <para>
+        I might also recommend against a mistake that I think Debian
+        has made. The terms <quote>unstable,</quote>
+        <quote>testing,</quote> and <quote>experimental</quote> are
+        vague and difficult to rank in order of stability (or
+        instability as the case may be). Try explaining to someone
+        that <quote>stable</quote> actually means <quote>ultra
+        stable</quote> and that <quote>unstable</quote> doesn't
+        actually include any unstable software but is really stable
+        software that is untested as a distribution.
+       </para>
+
+       <para>
+        If you are going to do branches, especially early on, keep in
+        mind that people are conditioned to understand the terms
+        <quote>stable</quote> and <quote>development</quote> and you
+        probaly can't go wrong with this simple and common division of
+        branches.
+       </para>
+      </listitem>
+     </varlistentry>
+
+     <varlistentry>
+      <term>Make sure all your branches are always available</term>
+      <listitem>
+       <para>
+        Like a lot of document, this should probably should go without
+        saying but experience has taught me that it's not always
+        obvious to people. It's a good idea to physicall split up
+        different branches in different directories or directory trees
+        on your <acronym>FTP</acronym> or <acronym>HTTP</acronym>
+        site. Linux accomplishes this by having all the v2.2 and a
+        v2.3 subdirectory where it is immediately obvious (after you
+        know their version numbering scheme) which directory is the
+        most recent stable and the current development
+        releases. Debian accomplishes this by naming all their
+        distribution by name and then changing symlinks named
+        <quote>stable,</quote> <quote>unstable</quote> and
+        <quote>frozen</quote> to point to which ever distribution (by
+        name) is in whatever stage. Both methods work and their are
+        others. In any case, it is important that different branches
+        are always available, are accessable from consistent
+        locations, and that different branches are clearly
+        distinguished from each other so your users know exactly what
+        they want to be downloading and where to get it.
+       </para>
+      </listitem>
+     </varlistentry>
+
+    </variablelist>
+   </para>
+

   </sect2>
 
 <!-- Section2: otherdev -->
 
   <sect2 id="otherdev">
    <title>Other Development issues</title>
   </sect2>
 
 <!-- Section2: otherdev -->
 
   <sect2 id="otherdev">
    <title>Other Development issues</title>

-   <para></para>
-  </sect2>
+   <para>
+    There are more issues around surrounding interaction with
+    developers in a free software project that I can touch on in great
+    detail in a HOWTO of this size. Please don't hesitate to contact
+    me if you see any major omissions. Other smaller issues that are
+    worth mentioning are:
+   </para>

 
 

+   <sect3>
+    <title>Freezing</title>
+    <para>
+     For those projects that choose to adopt a split development model
+     (<xref linkend="branches">), freezing is a concept that is worth
+     becoming familiar with. 
+    </para>
+
+    <para>
+     Freeze come in two major forms. A <quote>feature freeze</quote>
+     is a period when no signifigant functionality is added to a
+     program. It is a period where established functionality (even
+     skeletons of barely working functionality) can be improved and
+     perfected. It is a period where bugs are fixed. This type of
+     freeze is usually applied some period (a month or two) before a
+     release. It is easy to push a release back as you wait for
+     <quote>one more feature</quote> and a freeze helps to avoid this
+     situation by drawing the much neede line in the sand. It gives
+     developers room they need to get a program ready for release.
+    </para>
+
+    <para>
+     The second type of freeze is a <quote>code freeze</quote> which
+     is much more like a released piece of software. Once a piece of
+     software has entered a code freeze, all changes to the code are
+     frowned upon and only changes that fix known bugs are
+     permitted. This type of freeze usually follows a <quote>feature
+     freeze</quote> and directly preceeds a release. Most released
+     software is in what could be interpreted as a sort of high
+     level<quote>code freeze.</quote>
+    </para>
+
+    <para>
+     Even you do not choose to appoint a release manager (<xref
+     linkend="releasemanager">), you will have an easier time
+     justifying the rejection or postponement of patches (<xref
+     linkend="patching"> before a release with a publicly stated
+     freeze in effect.
+    </para>
+   </sect3>

 
 

+   <sect3>
+    <title>Forking</title>
+    <para>
+     Forks are the most extreme interpretation of a branch. A fork is
+     when a group of developers takes code from a free software
+     project and actually starts a brand new free software
+     project. The most famous example of a fork is Emacs and
+     XEmacs. Both emacsen are based on an almost identical codebase
+     but for technical, political, and philisophical reasons,
+     development was split into two projects which now compete with
+     each other.
+    </para>
+
+    <para>
+     The short version of the fork section is, <emphasis>don't do
+     them.</emphasis> Forks force developers to choose one project to
+     work with, cause nasty political divisions, redundancy of work.
+     Luckily, usually the threat of the fork is enough to scare the
+     maintainer or maintainers of a project into changing the way they
+     run their project to avoid it.
+    </para>
+
+    <para>
+     In his chapter on <quote>The Open Source Process,</quote> Karl
+     Fogel describes how to do a fork if you absolutely must. If you
+     have determined that is absolutely necessary and that the
+     differences between you and the people threatening to fork are
+     absolutely unresolvable, I recommend Fogel's book as a good place
+     to start.
+    </para>
+   </sect3>
+  </sect2>

  </sect1>
 
 <!-- Section1: users -->
 
  <sect1 id="users">
   <title>Maintaining a Project: Interacting with Users</title>
  </sect1>
 
 <!-- Section1: users -->
 
  <sect1 id="users">
   <title>Maintaining a Project: Interacting with Users</title>

+  <indexterm>
+   <primary>fswd!users</primary>
+  </indexterm>
+
+  <para>
+   If you've worked your way up to here, congratuatlions, you are
+   nearing the end of this document. This final section touches upon 
+  </para>

 
 

-   <indexterm>
-    <primary>fswd!users</primary>
-   </indexterm>

 
 <!-- Section2: testing -->
 
 
 <!-- Section2: testing -->