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

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

File:
1 edited

Legend:

Unmodified
Added
Removed
  • 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>
Note: See TracChangeset for help on using the changeset viewer.