Changeset 3415


Ignore:
Timestamp:
May 31, 2007, 9:33:52 AM (16 years ago)
Author:
Nicklas Nordborg
Message:

References #552, #553, #554: More information about backwards compatibility and Public vs. Internal
API.

Location:
trunk
Files:
1 added
5 edited

Legend:

Unmodified
Added
Removed

  • trunk/doc/src/docbook/appendix/index.xml

    r3334 r3415  
    3939  <include file="migrate.properties.xml" />
    4040  <include file="other_config.xml" />
     41  <include file="incompatible.xml" />
    4142</part>

  • trunk/doc/src/docbook/developerdoc/api_overview.xml

    r3409 r3415  
    5757        >javadoc</ulink> for information about
    5858      what parts of the API that contributes to the public API.
     59      Methods, classes and other elements that have been tagged as
     60      <code>@deprecated</code> should be considered as part of the internal API
     61      and may be removed in a subsequent relase without warning.
     62    </para>
     63   
     64    <para>
     65      See <xref linkend="appendix.incompatible" /> to read more about
     66      changes that have been introduced by each release.
    5967    </para>
    6068
    … …  
    7078      </para>
    7179     
    72       <variablelist>
    73       <varlistentry>
    74         <term>Binary compatibility</term>
     80     
     81      <sect3 id="api_overview.compatibility.binary">
     82        <title>Binary compatibility</title>
     83        <para>
     84        <blockquote>
     85          Pre-existing Client binaries must link and run with new releases of the
     86          Component without recompiling.
     87        </blockquote>
     88       
     89        For example:
     90        <itemizedlist>
    7591        <listitem>
    7692          <para>
     93            We can't change the number or types of parameters to a method
     94            or constructor.
     95          </para>
     96        </listitem>
     97        <listitem>
     98          <para>
     99            We can't add or change methods to interfaces that are intended
     100            to be implemented by plug-in or client code.
     101          </para>
     102        </listitem>
     103        </itemizedlist>
     104        </para>       
     105      </sect3>
     106     
     107      <sect3 id="api_overview.compatibility.contract">
     108        <title>Contract compatibility</title>
     109        <para>
    77110          <blockquote>
    78             Pre-existing Client binaries must link and run with new releases of the
    79             Component without recompiling.
     111          API changes must not invalidate formerly legal Client code.
    80112          </blockquote>
    81          
     113       
    82114          For example:
    83115          <itemizedlist>
    84116          <listitem>
    85117            <para>
    86               We can't change the number or types of parameters to a method
    87               or constructor.
    88             </para>
    89           </listitem>
    90           <listitem>
    91             <para>
    92               We can't add or change methods to interfaces that are intended
    93               to be implemented by plug-in or client code.
     118              We can't change the implementation of a method to do
     119              things differently than before. For example, allow <constant>null</constant>
     120              as a return value when it wasn't allowed before.
    94121            </para>
    95122          </listitem>
    96123          </itemizedlist>
     124       
     125          <note>
     126            <para>
     127            Sometimes there is a very fine line between what is considered a
     128            bug and what is considered a feature. For example, if the
     129            actual implementation doesn't do what the javadoc says,
     130            do we change the code or do we change the documentation?
     131            This has to be considered from case to case and depends on
     132            the age of the code and if we expect plug-ins and clients to be
     133            affected by it or not.
     134            </para>
     135          </note>
     136        </para>
     137      </sect3>
     138     
     139      <sect3 id="api_overview.compatibility.source">
     140        <title>Source code compatibility</title>
     141        <para>
     142        This is not an important matter and is not always possible to
     143        achieve. In most cases, the problems are easy to fix.
     144        Example:
     145       
     146        <itemizedlist>
     147        <listitem>
     148          <para>
     149          Adding a class may break a plug-in or client that import
     150          classes with <constant>.*</constant> if the same class name
     151          exists in another package.
    97152          </para>
    98153        </listitem>
    99       </varlistentry>
    100       <varlistentry>
    101         <term>Contract compatibility</term>
    102         <listitem>
    103           <para>
    104             <blockquote>
    105             API changes must not invalidate formerly legal Client code.
    106             </blockquote>
    107          
    108             For example:
    109             <itemizedlist>
    110             <listitem>
    111               <para>
    112                 We can't change the implementation of a method to do
    113                 things differently than before. For example, allow <constant>null</constant>
    114                 as a return value when it wasn't allowed before.
    115               </para>
    116             </listitem>
    117             </itemizedlist>
    118          
    119             <note>
    120               <para>
    121               Sometimes there is a very fine line between what is considered a
    122               bug and what is considered a feature. For example, if the
    123               actual implementation doesn't do what the javadoc says,
    124               do we change the code or do we change the documentation?
    125               This has to be considered from case to case and depends on
    126               the age of the code and if we expect plug-ins and clients to be
    127               affected by it or not.
    128               </para>
    129             </note>
    130           </para>
    131         </listitem>
    132       </varlistentry>
    133       <varlistentry>
    134         <term>Source code compatibility</term>
    135         <listitem>
    136           <para>
    137           This is not an important matter and is not always possible to
    138           achieve. In most cases, the problems are easy to fix.
    139           Example:
    140          
    141           <itemizedlist>
    142           <listitem>
    143             <para>
    144             Adding a class may break a plug-in or client that import
    145             classes with <constant>.*</constant> if the same class name
    146             exists in another package.
    147             </para>
    148           </listitem>
    149           </itemizedlist>
    150           </para>
    151          
    152         </listitem>
    153       </varlistentry>
    154       </variablelist>
    155      
    156    
     154        </itemizedlist>
     155        </para>
     156      </sect3>
    157157    </sect2>
    158  
    159158  </sect1>
    160159

  • trunk/doc/src/docbook/developerdoc/core_ref.xml

    r3409 r3415  
    2727-->
    2828
    29 <chapter id="core_ref" chunked="0">
     29<chapter id="core_ref">
    3030  <?dbhtml dir="core_ref"?>
    3131  <title>Core developer reference</title>
    3232
    33   <sect1 id="core_ref.procedures">
    34     <title>Important procedures</title>
    35     <para>
    36       This documentation is only available in the old format.
    37       See <ulink url="http://base.thep.lu.se/chrome/site/doc/development/index.html#rules"
    38         >http://base.thep.lu.se/chrome/site/doc/development/index.html#rules</ulink>
    39     </para>
    40   </sect1>
    41  
    4233  <sect1 id="core_ref.release">
    4334    <title>Publishing a new release</title>
    … …  
    5849  </sect1>
    5950
    60   <sect1 id="core_ref.rules">
     51  <sect1 id="core_ref.rules" chunked="1">
    6152    <title>Coding rules and guidelines</title>
    6253   
    6354    <sect2 id="core_ref.rules.devprocess">
    64       <title>Development process</title>
    65       <para>
    66         This documentation is only available in the old format.
    67         See <ulink url="http://base.thep.lu.se/chrome/site/doc/development/coding/process.html"
    68           >http://base.thep.lu.se/chrome/site/doc/development/coding/process.html</ulink>
    69       </para>
     55      <title>Development process and other important procedures</title>
     56      <para>
     57         This section describes the development process we try to use in the BASE project.
     58         It is not carved in stone and deviations may occur. For every new feature
     59         or enhancement the procure below should be followed.
     60         If you encounter any problems, arrange a group meeting. Someone else
     61         may have the solution! The text is biased towards adding new
     62         items to BASE, but it should be possible to use the general outline
     63         even for other types of features.
     64      </para>
     65     
     66      <bridgehead>1. Group meeting</bridgehead>
     67      <itemizedlist>
     68      <listitem>
     69        <para>
     70        The group should have a short meeting and discuss the new or changed
     71        feature. Problem areas should be identified, not solved!
     72        </para>
     73      </listitem>
     74      <listitem>
     75        <para>
     76        The person who is going to make the analysis, design and development is
     77        responsible for taking notes. They should be kept until the analysis
     78        and design phase has been finished.     
     79        </para>
     80      </listitem>
     81      <listitem>
     82        <para>
     83        A follow-up meeting should be held at the end of the analysis phase. 
     84        </para>
     85      </listitem>
     86      <listitem>
     87        <para>
     88        A single meeting may of course discuss more than one feature.
     89        </para>
     90      </listitem>
     91      </itemizedlist>
     92     
     93      <bridgehead>2. Analysis and design</bridgehead>
     94      <itemizedlist>
     95      <listitem>
     96        <para>
     97        Create an diagram of the classes including their properties, links and associations.
     98        Use the already existing diagrams and code as a template.
     99        The diagram should have information about cache and proxy settings.
     100        </para>
     101      </listitem>
     102      <listitem>
     103        <para>
     104        Write a short document about the diagram, especially things that are not obvious
     105        and explain any deviations from the recommendations in the coding guidelines.
     106        </para>
     107      </listitem>
     108      <listitem>
     109        <para>
     110        Identify things that may affect backwards compatibility. For more
     111        information about such things read <xref linkend="api_overview.public_api" />
     112        and <xref linkend="core_ref.rules.compatibility" />.
     113        </para>
     114      </listitem>
     115      <listitem>
     116        <para>
     117        Identify what parts of the documentation that needs to changed or added
     118        to describe the new feature. This includes, but is not limited to:
     119        <itemizedlist>
     120        <listitem>
     121          <para>
     122          User and administrator documentation, how to use the feature, screenshots,
     123          etc.
     124          </para>
     125        </listitem>
     126        <listitem>
     127          <para>
     128          Plug-in and core developer documentation, code examples, database schema changes,
     129          etc.
     130          </para>
     131        </listitem>
     132        </itemizedlist>
     133        </para>
     134      </listitem>
     135      <listitem>
     136        <para>
     137        If there are any problems with the existing code, these should be solved at
     138        this stage. Write some prototype code for testing if necessary.
     139        </para>
     140      </listitem>
     141      <listitem>
     142        <para>
     143        Group meeting to verify that the specified solution is ok, and to make sure
     144        everybody has enough knowledge of the solution.
     145        </para>
     146      </listitem>
     147      </itemizedlist>
     148     
     149      <bridgehead>3. Create the classes for the data layer</bridgehead>
     150      <itemizedlist>
     151      <listitem>
     152        <para>
     153        If step 2 is properly done, this should not take long.
     154        </para>
     155      </listitem>
     156      <listitem>
     157        <para>
     158        Follow the coding guidelines in <xref linkend="core_ref.rules.datalayer" />.
     159        </para>
     160      </listitem>
     161      <listitem>
     162        <para>
     163        At the end of this step, go back and have a lock at the diagram/documentation
     164        from the analysis and design phase and make sure everything is still correct.
     165        </para>
     166      </listitem>
     167      </itemizedlist>
     168     
     169      <bridgehead>4. Create the corresponding classes in the core layer</bridgehead>
     170      <itemizedlist>
     171      <listitem>
     172        <para>
     173        For simple cases this is also easy. Other cases may require more effort.
     174        </para>
     175      </listitem>
     176      <listitem>
     177        <para>
     178        If needed, go back to the analysis and design phase and do some more investigations.
     179        Make sure the documentation is updated if there are changes.
     180        </para>
     181      </listitem>
     182      </itemizedlist>
     183     
     184      <bridgehead>5. Create test code</bridgehead>
     185      <itemizedlist>
     186      <listitem>
     187        <para>
     188        Build on and use the existing test as much as possible.
     189        </para>
     190      </listitem>
     191      </itemizedlist>
     192     
     193      <bridgehead>6. Write code to update existing installations</bridgehead>
     194      <important>
     195      <itemizedlist>
     196      <listitem>
     197        <para>
     198        If the database schema is changed or if there for some reason is need to update
     199        existing data in the database, the <constant>Install.SCHEMA_VERSION</constant>
     200        counter must be increased.
     201        </para>
     202      </listitem>
     203      <listitem>
     204        <para>
     205        Add code to the <classname>net.sf.basedb.core.Update</classname> class
     206        to increase the schema version and modify data in existing installations.
     207        </para>
     208      </listitem>
     209      </itemizedlist>
     210      </important>
     211     
     212      <bridgehead>7. Write new and update existing user documentation</bridgehead>
     213      <itemizedlist>
     214      <listitem>
     215        <para>
     216        Most likely, users and plug-in developers wants to know about the feature.
     217        </para>
     218      </listitem>
     219      </itemizedlist>
     220
     221      <important>
     222      <para>
     223      Don't forget to update the <xref linkend="appendix.incompatible" /> document
     224      if you have introduced any incomaptible changes.
     225      </para>
     226      </important>
     227     
    70228    </sect2>
    71229    <sect2 id="core_ref.rules.style">
    … …  
    87245        many things to watch out for.
    88246      </para>
     247     
     248      <important>
     249        <title>Don't forget to log changes!</title>
     250        <para>
     251        Any change that may affect backwards compatibility must be logged in
     252        <xref linkend="appendix.incompatible" />.
     253        </para>
     254      </important>
    89255     
    90256      <para>

  • trunk/doc/src/javadoc/overview.html

    r3409 r3415  
    3232  or plug-in developers. We guarantee a certain degree of stability
    3333  among the classes and methods in the public API. See documentation
    34   on the <a href="http://base.thep.lu.se">BASE web site</a> for more information.
     34  on the <a href="http://base.thep.lu.se/chrome/site/doc/docbook/html/developerdoc/api/api_overview.html"
     35    >BASE web site</a> for more information.
     36  Methods that have been tagged as <code>@deprecated</code> should be considered
     37  part of the internal API and may be removed without warning in
     38  a later release.
    3539  </p>
    3640

  • trunk/lib/docbook/custom-styles/docbook/plain/css/docbook.css

    r3409 r3415  
    203203}
    204204
    205 .blockquote {
     205div.blockquote {
    206206  font-style: italic;
     207  background: #E0E0E0;
     208  border: 1px solid gray;
    207209}
    208210
Note: See TracChangeset for help on using the changeset viewer.