cvs: peardoc / manual.xml /en/chapters rfcs-entities.xml rfcs.xml /en/chapters/rfcs version-naming.xml

http://cvs.php.net/viewvc.cgi/peardoc/manual.xml?r1=1.5&r2=1.6&diff_format=u
Index: peardoc/manual.xml
diff -u peardoc/manual.xml:1.5 peardoc/manual.xml:1.6
--- peardoc/manual.xml:1.5	Sun Nov  9 17:33:45 2008
+++ peardoc/manual.xml	Sun May  3 12:50:12 2009
@@ -120,6 +120,8 @@
    &guide.migrating.customtasks;
    &guide.migrating.postinstall;
   </part>
+  
+  &chapters.rfcs;
  </book>
 
 

http://cvs.php.net/viewvc.cgi/peardoc/en/chapters/rfcs-entities.xml?view=markup&rev=1.1
Index: peardoc/en/chapters/rfcs-entities.xml
+++ peardoc/en/chapters/rfcs-entities.xml
<!--&package.tools.versioncontrol-svn;-->
&chapters.rfcs.version-naming;

http://cvs.php.net/viewvc.cgi/peardoc/en/chapters/rfcs.xml?view=markup&rev=1.1
Index: peardoc/en/chapters/rfcs.xml
+++ peardoc/en/chapters/rfcs.xml
<?xml version='1.0' encoding='utf-8' ?>
<part xml:id="chapters.rfcs" xmlns="http://docbook.org/ns/docbook"
  xmlns:xlink="http://www.w3.org/1999/xlink" 
>
  <info>
    <title>RFCs</title>
  </info>

  <partintro>
    <para>
      Request for comments are normative documents
      about how PEAR works. RFCs get proposed through the PEAR's
      <link xlink:href="&url.pear.pepr;">PEPr system</link>.
    </para>
  </partintro>
 
&chapters.rfcs-entities;
</part>
http://cvs.php.net/viewvc.cgi/peardoc/en/chapters/rfcs/version-naming.xml?view=markup&rev=1.1
Index: peardoc/en/chapters/rfcs/version-naming.xml
+++ peardoc/en/chapters/rfcs/version-naming.xml
<?xml version="1.0" encoding="UTF-8"?>
<chapter version="5.0" xml:id="chapters.rfcs.version-naming"
         xmlns="http://docbook.org/ns/docbook"
         xmlns:xlink="http://www.w3.org/1999/xlink"
>
  <info>
    <title>Version Naming</title>
  </info>

  <para>The RFC can be found on <link
  xlink:href="http://pear.php.net/pepr/pepr-proposal-show.php?id=65">PEPr</link>.</para>

  <para>As discussed previously on pear-group, where a full consensus could
  not be reached on the version naming standard, below is the proposed
  replacement RFC, which attempts to address the issues.</para>

  <section xml:id="chapters.rfcs.version-naming.issue">
    <title>The issue</title>

    <para>Pear-group announced a versioning naming standard which unfortunatly
    failed to explain the reasons behind the decisions made. The aim of the
    previous standard was</para>

    <itemizedlist>
      <listitem>
        <para>Formalize the version naming of packages.</para>
      </listitem>

      <listitem>
        <para>Fix problems with version_compare going from
        <literal>1.0.0RC1</literal> to <literal>1.0.1</literal></para>
      </listitem>

      <listitem>
        <para>To introduce a rule stating 'no-stable releases before
        <literal>1.0.0</literal>'</para>
      </listitem>

      <listitem>
        <para>Solve release naming for <literal>My_Package2</literal> (second
        releases)</para>
      </listitem>
    </itemizedlist>

    <para>It also attemtped to introduce a number of more controversial
    ideas</para>

    <itemizedlist>
      <listitem>
        <para>Make the package status more visible.</para>
      </listitem>
    </itemizedlist>

    <para>The last one did not result in a complete consensus, and patches
    have now been made to the packager and installer to add state to the
    filename, output when installing a package.</para>
  </section>

  <section xml:id="chapters.rfcs.version-naming.standard">
    <title>New version naming standard</title>

    <para>The solution is to replace the existing standard with one a
    <abbrev>simpler</abbrev> and slightly clearer one.</para>

    <table>
      <title>MyPackage versions</title>

      <tgroup cols="2">
        <thead>
          <row>
            <entry>Version</entry>

            <entry>Description</entry>
          </row>
        </thead>

        <tbody>
          <row>
            <entry><literal>0.1.0</literal> ...
            <literal>0.1335.0</literal></entry>

            <entry>initial pre-stable releases (bug fix releases increment
            <emphasis>.z</emphasis> eg. <literal>0.12.1</literal> )</entry>
          </row>

          <row>
            <entry><literal>1.0.0</literal></entry>

            <entry>first stable release</entry>
          </row>

          <row>
            <entry><literal>1.1.0</literal></entry>

            <entry>first feature upgrade</entry>
          </row>

          <row>
            <entry><literal>1.1.1</literal></entry>

            <entry>bug fixes on feature upgrade</entry>
          </row>
        </tbody>
      </tgroup>
    </table>

    <para>The next major version is <literal>MyPackage2</literal>:</para>

    <table>
      <title>MyPackage2 versions</title>

      <tgroup cols="2">
        <thead>
          <row>
            <entry>Version</entry>

            <entry>Description</entry>
          </row>
        </thead>

        <tbody>
          <row>
            <entry><literal>0.1.0</literal> ...
            <literal>0.1335.0</literal></entry>

            <entry>initial pre-stable releases (bug fix releases increment
            <emphasis>.z</emphasis> eg. <literal>0.12.1</literal> )</entry>
          </row>

          <row>
            <entry><literal>2.0.0</literal></entry>

            <entry>first stable release</entry>
          </row>

          <row>
            <entry><literal>2.1.0</literal></entry>

            <entry>first feature upgrade</entry>
          </row>

          <row>
            <entry><literal>2.1.1</literal></entry>

            <entry>bug fixes on feature upgrade</entry>
          </row>
        </tbody>
      </tgroup>
    </table>

    <section xml:id="chapters.rfcs.version-naming.standard.bcbreaks">
      <title>Deliberatly Breaking BC on packages</title>

      <para>Breaking BC may only be done:</para>

      <itemizedlist>
        <listitem>
          <para>within the <literal>0.*.*</literal> series</para>
        </listitem>

        <listitem>
          <para>moving from Major Package Versions (eg. to
          <literal>My_Package2</literal>)</para>
        </listitem>
      </itemizedlist>
    </section>

    <section xml:id="chapters.rfcs.version-naming.standard.first">
      <title>First Releases</title>

      <itemizedlist>
        <listitem>
          <para>should not be marked as stable</para>
        </listitem>

        <listitem>
          <para>should use <literal>0.1.0</literal> or greater (as you may
          have already started revision controlling while proposing it)</para>
        </listitem>
      </itemizedlist>
    </section>

    <section xml:id="chapters.rfcs.version-naming.standard.bugfix">
      <title>Bug fix only Releases</title>

      <itemizedlist>
        <listitem>
          <para>in pre stable - you can either increase <literal>y</literal>
          (in <literal>x.y</literal>) or <literal>z</literal> (in
          <literal>x.y.z</literal>), for example</para>

          <itemizedlist>
            <listitem>
              <para><literal>0.2.0</literal> -&gt;
              <literal>0.3.0</literal></para>
            </listitem>

            <listitem>
              <para><literal>0.2.0</literal> -&gt;
              <literal>0.2.1</literal></para>
            </listitem>
          </itemizedlist>
        </listitem>

        <listitem>
          <para>after a stable release</para>

          <itemizedlist>
            <listitem>
              <para><literal>1.3.0</literal> -&gt;
              <literal>1.3.1</literal></para>
            </listitem>

            <listitem>
              <para><literal>2.4.0</literal> -&gt;
              <literal>2.4.1</literal></para>
            </listitem>
          </itemizedlist>
        </listitem>
      </itemizedlist>
    </section>

    <section xml:id="chapters.rfcs.version-naming.standard.feature">
      <title>Feature addition Releases (that may also include bug
      fixes)</title>

      <para>Should just increment the <literal>y</literal> (in
      <literal>x.y</literal>), for examples</para>

      <itemizedlist>
        <listitem>
          <para><literal>0.3.0</literal> -&gt; <literal>0.4.0</literal></para>
        </listitem>

        <listitem>
          <para><literal>1.3.0</literal> -&gt; <literal>1.4.0</literal></para>
        </listitem>

        <listitem>
          <para><literal>2.10.0</literal> -&gt;
          <literal>2.11.0</literal></para>
        </listitem>
      </itemizedlist>
    </section>

    <section xml:id="chapters.rfcs.version-naming.standard.stable">
      <title>Stable Releases</title>

      <para>You should never release stable packages with a
      <literal>0.x</literal> format (this is a common situation at present,
      and is the only significant change that is being proposed.)</para>
    </section>

    <section xml:id="chapters.rfcs.version-naming.standard.rc">
      <title>Appending RC releases (Release Candidates)</title>

      <para>RC releases are strongly recommended for larger, popular
      packages.</para>

      <para>If you intend to append RC releases to your package, you should
      append a release number to after the RC, for example:</para>

      <itemizedlist>
        <listitem>
          <para><literal>0.123.0</literal> -&gt;
          <literal>1.0.0RC1</literal></para>
        </listitem>

        <listitem>
          <para><literal>1.0.0RC1</literal> -&gt;
          <literal>1.0.0RC2</literal></para>
        </listitem>

        <listitem>
          <para><literal>1.0.0RC2</literal> -&gt;
          <literal>1.0.0</literal></para>
        </listitem>

        <listitem>
          <para><literal>1.0.0</literal> -&gt; <literal>1.0.1</literal></para>
        </listitem>
      </itemizedlist>
    </section>

    <section xml:id="chapters.rfcs.version-naming.standard.defbcbreaks">
      <title>Defining BC breaks</title>

      <para>At present this is left to the maintainer to define (using common
      sense), the exact definition should be defined later by future
      RFCs.</para>
    </section>
  </section>
</chapter>