source: trunk/doc/src/docbook/developerdoc/core_ref.xml @ 3415

Last change on this file since 3415 was 3415, checked in by Nicklas Nordborg, 14 years ago

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

  • Property svn:eol-style set to native
  • Property svn:keywords set to Id
File size: 13.0 KB
Line 
1<?xml version="1.0" encoding="UTF-8"?>
2<!DOCTYPE chapter PUBLIC
3    "-//Dawid Weiss//DTD DocBook V3.1-Based Extension for XML and graphics inclusion//EN"
4    "../../../../lib/docbook/preprocess/dweiss-docbook-extensions.dtd">
5<!--
6  $Id: core_ref.xml 3415 2007-05-31 07:33:52Z nicklas $
7
8  Copyright (C) Authors contributing to this file.
9
10  This file is part of BASE - BioArray Software Environment.
11  Available at http://base.thep.lu.se/
12
13  BASE is free software; you can redistribute it and/or
14  modify it under the terms of the GNU General Public License
15  as published by the Free Software Foundation; either version 2
16  of the License, or (at your option) any later version.
17
18  BASE is distributed in the hope that it will be useful,
19  but WITHOUT ANY WARRANTY; without even the implied warranty of
20  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
21  GNU General Public License for more details.
22
23  You should have received a copy of the GNU General Public License
24  along with this program; if not, write to the Free Software
25  Foundation, Inc., 59 Temple Place - Suite 330,
26  Boston, MA  02111-1307, USA.
27-->
28
29<chapter id="core_ref">
30  <?dbhtml dir="core_ref"?>
31  <title>Core developer reference</title>
32
33  <sect1 id="core_ref.release">
34    <title>Publishing a new release</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#newrelease"
38        >http://base.thep.lu.se/chrome/site/doc/development/index.html#newrelease</ulink>
39    </para>
40  </sect1>
41 
42  <sect1 id="core_ref.build">
43    <title>Subversion / building BASE</title>
44    <para>
45      This documentation is only available in the old format.
46      See <ulink url="http://base.thep.lu.se/chrome/site/doc/development/build.html"
47        >http://base.thep.lu.se/chrome/site/doc/development/build.html</ulink>
48    </para>
49  </sect1>
50
51  <sect1 id="core_ref.rules" chunked="1">
52    <title>Coding rules and guidelines</title>
53   
54    <sect2 id="core_ref.rules.devprocess">
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     
228    </sect2>
229    <sect2 id="core_ref.rules.style">
230      <title>General coding style guidelines</title>
231      <para>
232        This documentation is only available in the old format.
233        See <ulink url="http://base.thep.lu.se/chrome/site/doc/development/coding/generic.html"
234          >http://base.thep.lu.se/chrome/site/doc/development/coding/generic.html</ulink>
235      </para>
236    </sect2>
237 
238    <sect2 id="core_ref.rules.compatibility">
239      <title>API changes and backwards compatibility</title>
240      <para>
241        The main rule is to don't introduce any changes that are
242        backwards incompatible. That is, existing client applications
243        and plug-ins should continue to run in the next release of BASE,
244        without the need to change them. It may sound easy but there are
245        many things to watch out for.
246      </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>
255     
256      <para>
257        There is a great article about this subject on <ulink 
258        url="http://wiki.eclipse.org/index.php/Evolving_Java-based_APIs"
259          >http://wiki.eclipse.org/index.php/Evolving_Java-based_APIs</ulink>.
260        This is what we will try to comply with.
261      </para>
262     
263      <sect3 id="core_ref.rules.compatibility.public_api">
264        <title>Does the changes affect the Public API?</title>
265       
266        <para>
267          See <xref linkend="api_overview.public_api" /> and
268          <ulink url="http://base.thep.lu.se/chrome/site/doc/api/index.html"
269          >the javadoc</ulink>for information
270          about the public API.
271        </para>
272       
273        <para>
274          Changes made to the non-public API doesn't have to follow the
275          same rules.
276        </para>
277      </sect3>
278     
279      <sect3 id="core_ref.rules.compatibility.contract">
280        <title>Contract compatibility</title>
281       
282        <para>
283          TODO
284        </para>
285       
286      </sect3>
287     
288      <sect3 id="core_ref.rules.compatibility.binary">
289        <title>Binary compatibility</title>
290       
291        <para>
292          TODO
293        </para>
294       
295      </sect3>
296     
297      <sect3 id="core_ref.rules.compatibility.data">
298        <title>Internal data structure compatibility</title>
299       
300        <para>
301          TODO
302        </para>
303       
304      </sect3>
305     
306      <sect3 id="core_ref.rules.compatibility.source">
307        <title>Source code compatibility</title>
308       
309        <para>
310          TODO
311        </para>
312       
313      </sect3>
314     
315    </sect2>
316   
317    <sect2 id="core_ref.rules.datalayer">
318      <title>Data-layer rules</title>
319      <para>
320        This documentation is only available in the old format.
321        See <ulink url="http://base.thep.lu.se/chrome/site/doc/development/coding/data/index.html"
322          >http://base.thep.lu.se/chrome/site/doc/development/coding/data/index.html</ulink>
323      </para>
324    </sect2>   
325    <sect2 id="core_ref.rules.itemclass">
326      <title>Item-class rules</title>
327      <para>
328        This documentation is only available in the old format.
329        See <ulink url="http://base.thep.lu.se/chrome/site/doc/development/coding/item/index.html"
330          >http://base.thep.lu.se/chrome/site/doc/development/coding/item/index.html</ulink>
331      </para>
332    </sect2>   
333    <sect2 id="core_ref.rules.batchclass">
334      <title>Batch-class rules</title>
335      <para>
336        TODO
337      </para>
338    </sect2>   
339    <sect2 id="core_ref.rules.testclass">
340      <title>Test-class rules</title>
341      <para>
342        TODO
343      </para>
344    </sect2>   
345  </sect1>
346 
347  <sect1 id="core_ref.coreinternals">
348    <title>Internals of the Core API</title>
349    <para>
350      This documentation is only available in the old format.
351      See <ulink url="http://base.thep.lu.se/chrome/site/doc/development/overview/core/index.html"
352        >http://base.thep.lu.se/chrome/site/doc/development/overview/core/index.html</ulink>
353    </para>
354    <sect2 id="core_ref.authentication">
355      <title>Authentication and sessions</title>
356      <para>
357        This documentation is only available in the old format.
358        See <ulink url="http://base.thep.lu.se/chrome/site/doc/development/overview/core/authentication.html"
359          >http://base.thep.lu.se/chrome/site/doc/development/overview/core/authentication.html</ulink>
360      </para>
361    </sect2>   
362    <sect2 id="core_ref.accesspermissions">
363      <title>Access permissions</title>
364      <para>
365        This documentation is only available in the old format.
366        See <ulink url="http://base.thep.lu.se/chrome/site/doc/development/overview/core/accesspermissions.html"
367          >http://base.thep.lu.se/chrome/site/doc/development/overview/core/accesspermissions.html</ulink>
368      </para>
369    </sect2>   
370    <sect2 id="core_ref.datavalidation">
371      <title>Data validation</title>
372      <para>
373        TODO
374      </para>
375    </sect2>   
376    <sect2 id="core_ref.transactions">
377      <title>Transaction handling</title>
378      <para>
379        TODO
380      </para>
381    </sect2>   
382    <sect2 id="core_ref.crwd">
383      <title>Create/read/write/delete operations</title>
384      <para>
385        This documentation is only available in the old format.
386        See <ulink url="http://base.thep.lu.se/chrome/site/doc/development/overview/core/itemhandling.html"
387          >http://base.thep.lu.se/chrome/site/doc/development/overview/core/itemhandling.html</ulink>
388      </para>
389    </sect2>   
390    <sect2 id="core_ref.batch">
391      <title>Batch operations</title>
392      <para>
393        This documentation is only available in the old format.
394        See <ulink url="http://base.thep.lu.se/chrome/site/doc/development/overview/core/batchprocessing.html"
395          >http://base.thep.lu.se/chrome/site/doc/development/overview/core/batchprocessing.html</ulink>
396      </para>
397    </sect2>   
398    <sect2 id="core_ref.quota">
399      <title>Quota</title>
400      <para>
401        TODO
402      </para>
403    </sect2>   
404    <sect2 id="core_ref.pluginexecution">
405      <title>Plugin execution / job queue</title>
406      <para>
407        This documentation is only available in the old format.
408        See <ulink url="http://base.thep.lu.se/chrome/site/doc/development/overview/core/plugins.html"
409          >http://base.thep.lu.se/chrome/site/doc/development/overview/core/plugins.html</ulink>
410      </para>
411    </sect2>   
412  </sect1>
413
414</chapter>
Note: See TracBrowser for help on using the repository browser.