cvs: peardoc /en/chapters rfcs-entities.xml /en/chapters/rfcs estrict-compatibility.xml

http://cvs.php.net/viewvc.cgi/peardoc/en/chapters/rfcs-entities.xml?r1=1.5&r2=1.6&diff_format=u
Index: peardoc/en/chapters/rfcs-entities.xml
diff -u peardoc/en/chapters/rfcs-entities.xml:1.5 peardoc/en/chapters/rfcs-entities.xml:1.6
--- peardoc/en/chapters/rfcs-entities.xml:1.5	Sun May  3 17:44:51 2009
+++ peardoc/en/chapters/rfcs-entities.xml	Mon May  4 05:31:53 2009
@@ -1,4 +1,5 @@
 &chapters.rfcs.error-handling;
+&chapters.rfcs.estrict-compatibility;
 &chapters.rfcs.header-comments;
 &chapters.rfcs.protected-members;
 &chapters.rfcs.qa-team;

http://cvs.php.net/viewvc.cgi/peardoc/en/chapters/rfcs/estrict-compatibility.xml?view=markup&rev=1.1
Index: peardoc/en/chapters/rfcs/estrict-compatibility.xml
+++ peardoc/en/chapters/rfcs/estrict-compatibility.xml
<?xml version="1.0" encoding="UTF-8"?>
<chapter version="5.0" xml:id="chapters.rfcs.estrict-compatibility"
         xmlns="http://docbook.org/ns/docbook"
         xmlns:xlink="http://www.w3.org/1999/xlink"
>
  <info>
    <title>Requiring E_STRICT Compatibility for New PEAR Packages</title>

    <date>2006-09-05</date>
  </info>

  <para>
   This RFC has been voted on and accepted in PEPr as
   <link xlink:href="&url.pear.pepr.proposal;419">proposal #419</link>.
  </para>

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

    <para>First stable release of PHP version 5 was done two years ago. This
    version of language has matured a lot throughout these two years and with
    PHP version 4 development effectively stopped should already be considered
    the preferred platform by developers of new PHP libraries and
    applications.</para>

    <para>PEAR policies encourage "backwards compatibility", which
    unfortunately means supporting the inadequate object model of PHP version
    4. While it does make sense for existing packages, requiring such
    "backwards compatibility" for new packages that get accepted into PEAR has
    at least two problems:</para>

    <itemizedlist>
      <listitem>
        <para>It slows the adoption of PHP version 5 by users of PEAR</para>
      </listitem>

      <listitem>
        <para>PEAR risks becoming a garbage dump of obsolescent code, or at
        least be perceived as one</para>
      </listitem>
    </itemizedlist>
  </section>

  <section xml:id="chapters.rfcs.estrict-compatibility.solution">
    <title>The solution</title>

    <para>The proposed solution is to focus on "forward compatibility"
    instead. PHP version 5 has a builtin means to ensure that code is forward
    compatible, which is <token>E_STRICT</token> error reporting level.</para>

    <section xml:id="chapters.rfcs.estrict-compatibility.solution.definition">
      <title>Definition of E_STRICT-compatible package</title>

      <para>The package is considered <token>E_STRICT</token>-compatible
      if</para>

      <itemizedlist>
        <listitem>
          <para>it can be used under PHP 5.1.4+</para>
        </listitem>

        <listitem>
          <para>its files do not emit error messages when used with error
          reporting level set to <literal>E_ALL | E_STRICT</literal> under PHP
          5.1.4+</para>
        </listitem>

        <listitem>
          <para>it follows PEAR coding standards that apply to PHP5-only
          packages</para>
        </listitem>

        <listitem>
          <para>it has only <literal>E_STRICT</literal>-compatible required
          dependencies</para>
        </listitem>
      </itemizedlist>

      <para><token>E_STRICT</token>-compatible package may have optional
      dependencies that are not <token>E_STRICT</token>-compatible, but this
      is discouraged.</para>
    </section>

    <section xml:id="chapters.rfcs.estrict-compatibility.solution.changes">
      <title>Proposed changes</title>

      <para>After this RFC is accepted, a deadline for accepting the new non
      <token>E_STRICT</token>-compatible packages is set as January 1, 2007.
      This deadline should be prominently announced on PEAR website and in
      PEAR manual. All new PHP5-related <link linkend="standards">coding
      standards</link> should also be integrated into the manual.</para>

      <para>Developers wishing to propose a new non
      <token>E_STRICT</token>-compatible package or start work on a non
      <token>E_STRICT</token>-compatible new major version (as defined in
      <link xlink:href="http://pear.php.net/group/docs/20031114-bbr.php">New
      guidelines for BC breaking releases</link>) of an existing package
      should do so before the deadline.</para>

      <para>After January 1, 2007 all new packages proposed via PEPr and all
      new major versions of existing packages should be
      <token>E_STRICT</token>-compatible. Proposals for non
      <token>E_STRICT</token>-compatible packages that reach this deadline not
      in "Called for votes" state should not be called for votes until the
      package is reworked to be <token>E_STRICT</token>-compatible.</para>

      <section>
        <title>Two versions exception</title>

        <para>the person proposing a new package may choose to also provide a
        version of said package that can be run under PHP version 4. Such a
        version requires a separate proposal that may only be called for votes
        after the proposal of <token>E_STRICT</token>-compatible version is
        accepted. The package must have the name of
        <token>E_STRICT</token>-compatible version with 'PHP4' appended (ex.:
        <package>Example_Foo</package> and
        <package>Example_FooPhp4</package>).</para>
      </section>

      <section>
        <title>Subpackages exception</title>

        <para>if a package does not yet have
        <token>E_STRICT</token>-compatible version then non
        <token>E_STRICT</token>-compatible subpackages for it may be accepted
        at the discretion of base package's developers. If base package
        already has <token>E_STRICT</token>-compatible version then acceptance
        of such subpackages falls under the previous exception.</para>
      </section>
    </section>

    <section xml:id="chapters.rfcs.estrict-compatibility.solution.impactexisting">
      <title>Impact on existing packages</title>

      <para>Development and release process of existing PEAR packages which
      are not <token>E_STRICT</token>-compatible may continue as usual. The
      only new requirement is that if a new major version of a package is
      started, it should be <token>E_STRICT</token>-compatible.</para>

      <para>If a new major version of an existing package was registered on
      PEAR website before the deadline is reached or the code of this new
      major version was present in PEAR CVS then this version is considered an
      "existing package" for the purpose of this RFC.</para>

      <para>Nevertheless, developers of existing packages are strongly
      encouraged to update their packages for
      <token>E_STRICT</token>-compatibility if a BC break is still allowed by
      <link
      xlink:href="http://pear.php.net/group/docs/20040226-vn.php">Version
      Naming guidelines</link>.</para>
    </section>
  </section>

  <section xml:id="chapters.rfcs.estrict-compatibility.notes">
    <title>Notes</title>

    <para>Several people expressed the concern that mandating
    <token>E_STRICT</token> dependencies may slow the development. While this
    is true, one of the goals of this proposal is to encourage the rewrite of
    base PEAR classes to PHP5.</para>
  </section>

  <section xml:id="chapters.rfcs.estrict-compatibility.changes">
    <title>A (Non-Exhaustive) List of E_STRICT-compatibility changes</title>

    <itemizedlist>
      <listitem>
        <para>Methods that are intended to be called statically should be
        defined with <token>static</token> keyword</para>
      </listitem>

      <listitem>
        <para>The <literal>$foo =&amp; new Foo()</literal> construct should
        not be used</para>
      </listitem>

      <listitem>
        <para><token>instanceof</token> operator should be used instead of
        <methodname>is_a()</methodname> function</para>
      </listitem>

      <listitem>
        <para>Declarations of methods in child classes should be compatible
        with those in parent classes</para>
      </listitem>
    </itemizedlist>

    <para>These changes obviously imply following the <link
    linkend="chapters.rfcs.error-handling">Error Handling Guidelines for PHP5
    packages</link> since PEAR class itself is not
    <token>E_STRICT</token>-compatible.</para>

    <para>Also the new object model should be taken into account: this means
    removing unneded references when working with objects and using clone
    where needed.</para>
  </section>
</chapter>