source: trunk/doc/development/index.html @ 2924

Last change on this file since 2924 was 2924, checked in by Jari Häkkinen, 17 years ago

Update to publishing a new release.
  • Property svn:eol-style set to native
  • Property svn:keywords set to Id Date
File size: 15.9 KB
Line 
1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
2<!--
3  $Id: index.html 2924 2006-11-15 18:19:13Z jari $
4
5  Copyright (C) 2005-2006 Jari Häkkinen, Nicklas Nordborg
6
7  This file is part of BASE - BioArray Software Environment.
8  Available at http://base.thep.lu.se/
9
10  BASE is free software; you can redistribute it and/or
11  modify it under the terms of the GNU General Public License
12  as published by the Free Software Foundation; either version 2
13  of the License, or (at your option) any later version.
14
15  BASE is distributed in the hope that it will be useful,
16  but WITHOUT ANY WARRANTY; without even the implied warranty of
17  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
18  GNU General Public License for more details.
19
20  You should have received a copy of the GNU General Public License
21  along with this program; if not, write to the Free Software
22  Foundation, Inc., 59 Temple Place - Suite 330,
23  Boston, MA  02111-1307, USA.
24-->
25<html>
26  <head>
27    <title>BASE - Development information</title>
28  <link rel=stylesheet type="text/css" href="../styles.css">
29  </head>
30<body>
31
32<div class="navigation">
33  <a href="../index.html">BASE</a>
34  <img src="../next.gif">
35  Development information
36</div>
37
38  <h1>Development information</h1>
39
40  <div class="abstract">
41    <p>
42      All documentation that is needed for the BASE developer.
43    </p>
44   
45    <b>Contents</b><br>
46    <ol>
47    <li><a href="#startingpoints">Where to start</a>
48    <li><a href="#javadoc">API Javadoc</a>
49    <li><a href="#specifications">Specifications</a>
50    <li><a href="#overview">Implementation overview</a>
51    <li><a href="#rules">Coding rules and guidelines</a>
52    <li><a href="#plugins">Plug-ins</a>
53    <li><a href="#running">Running BASE in the subversion tree</a>
54    <li><a href="#newrelease">Publishing a new release</a>
55    </ol>
56   
57    <b>See also</b>
58    <ul>
59    <li><a href="ideas.html">Development ideas</a>
60    </ul>
61   
62    <p class="authors">
63    <b>Last updated:</b> $Date: 2006-11-15 18:19:13 +0000 (Wed, 15 Nov 2006) $
64    </p>
65  </div>
66
67 
68  <a name="startingpoints">
69  <h2>1. Where to start</h2>
70  </a>
71
72  <a name="javadoc">
73  <h2>2. API Javadoc</h2>
74  </a>
75
76  <dl>
77  <dt>a) <a href="../api/develop/index.html">Developers version</a></dt>
78  <dd>
79    This is the developers version of the API. It includes all
80    protected and private methods.
81  </dd>
82 
83  <dt>b) <a href="../api/public/index.html">Public version</a></dt>
84  <dd>
85    This is the public version of the API. It includes only
86    public classes and methods.
87  </dd>
88  </dl>
89 
90  <a name="specifications">
91  <h2>3. Specifications</h2>
92  </a>
93 
94  <dl>
95 
96  <dt>a) <a href="../specifications/technical.html">Initial technical specification</a></dt>
97  <dd>
98    Explains why we want to develop BASE 2.0 from a technical point of view.
99    It includes a short background of the problems with the current implementation,
100    and discusses one technical solution that may solve the problems. It ends
101    with a list of work items with issues that needs to be investigated during
102    a prototype phase.
103  </dd>
104 
105  <dt>b) <a href="../specifications/features.html">Preliminary list of features</a></dt>
106  <dd>
107    A preliminary list of features wanted and/or required in BASE 2.
108    Compiled by Carl from various sources.
109  </dd>
110 
111  <dt>c) <a href="../specifications/core/index.html">Specifications for the core</a></dt>
112  <dd>
113    The original specifications for BASE 2. Changes during the
114    development has been clearly marked. Our goal is to keep
115    the specifications up to date with the actual implementation
116    at all times.
117  </dd>
118 
119  <dt>d) <a href="../specifications/webclient/index.html">Specifications for the web client</a> - TODO</dt>
120  <dd>
121 
122  </dd>
123 
124  <dt>e) <a href="../specifications/migration/index.html">Specifications for the migration tool</a></dt>
125  <dd>
126 
127  </dd>
128 
129  </dl>
130 
131  <a name="overview">
132  <h2>4. Implementation overview</h2>
133  </a>
134 
135  <p>
136    The overview documentation is intended to give just an overview.
137    Detailed information can be found in the javadoc.
138  </p>
139 
140  <dl>
141  <dt>a) <a href="overview/index.html">Schematic overview of BASE</a></dt>
142  <dd>
143    An overview of the design of the entire BASE application.
144    This is a good place to start reading.
145  </dd>
146 
147  <dt>b) <a href="overview/data/index.html">Database schema and data layer API</a></dt>
148  <dd>
149    Complete information about the database and data layer.
150    The schema is divided into several sections, each describing a
151    particular part of the system. <i>I.e.</i>. user management, files, biomaterials,
152    etc.
153  </dd>
154 
155  <dt>c) <a href="overview/core/index.html">Internals of the core API</a></dt>
156  <dd>
157    An overview of the classes in the core that
158    are used for things like user authentication,
159    permissions checking, transaction handling,
160    data validation, batch processing, quota checking,
161    plug-in execution and job queue management.
162  </dd>
163
164  <dt>d) <a href="overview/query/index.html">Queries and the query API</a></dt>
165  <dd>
166    An overview of the Query API and how queries are
167    generated in cooperation with Hibernate. Here is also
168    information about the core classes that are used to execute
169    and deliver the result of a query. This document can also
170    be useful when building queries.
171  </dd>
172 
173  <dt>e) <a href="overview/dynamic/index.html">Dynamic API for experiments and analysis</a></dt>
174  <dd>
175    An overview of the Dynamic API, including how the tables are created in the
176    dynamic database, how data is inserted into those tables and how the queries that
177    selects data from the tables are working. This document is also useful for plug-in
178    developers.
179  </dd>
180
181  <dt>f) <a href="overview/exceptions/index.html">Exceptions</a> - TODO</dt>
182  <dd>
183    An overview of the exception hierarchy.
184  </dd>
185 
186  <dt>g) <a href="overview/utility/index.html">Utility classes</a> - TODO</dt>
187  <dd>
188    Some more or less generic functionality have been placed in publicly
189    available classes.
190  </dd>
191 
192  <dt>h) <a href="overview/web/index.html">Web interface</a> - TODO</dt>
193  <dd>
194  </dd>
195
196  </dl>
197 
198 
199  <a name="rules">
200  <h2>5. Coding rules and guidelines</h2>
201  </a>
202 
203  <dl>
204  <dt>a) <a href="coding/process.html">Development process</a>
205  <dd>
206    A document describing how to organise the development, covering the
207    analysis and design, implementation and test phases.
208  </dd>
209 
210  <dt>b) <a href="coding/generic.html">General coding style guidelines</a></dt>
211  <dd>
212    Generic rules that apply to all code unless some more specific rule
213    exists. It contains information about naming conventions, code formatting,
214    etc.
215  </dd>
216 
217  <dt>c) <a href="coding/data/index.html">Data-layer rules</a></dt>
218  <dd>
219    Rules for classes in the <code>net.sf.basedb.core.data</code> package
220    This is a very important document that includes many details about
221    how we map out data to the database with Hibernate.
222  </dd>
223 
224  <dt>d) <a href="coding/item/index.html">Item-class rules</a></dt>
225  <dd>
226    Rules for all classes that extend the <code>net.sf.basedb.core.BasicItem</code>
227    class. This is a very important document that includes many details about
228    permission checking, transaction handling, data validation, etc.
229  </dd>
230 
231  <dt>e) <a href="coding/batch/index.html">Batch-class rules</a> - TODO</dt>
232  <dd>
233    Rules for classes that extend the <code>net.sf.basedb.core.BasicBatcher</code>
234    class. This is a very important document for all classes that must handle
235    a lot of data in a single transaction, for example reporters and raw data.
236  </dd>
237 
238  <dt>f) <a href="coding/web/index.html">Web interface rules</a> - TODO</dt>
239  <dd>
240  </dd>
241 
242  <dt>g) <a href="coding/test/index.html">Test class rules</a> - TODO</dt>
243  <dd>
244  </dd>
245
246  <dt>h) Procedures </a> - TODO but here is an important one.</dt>
247  <dd>
248    <p>
249    When a database schema change is needed this must communicated
250    through the table <tt>SchemaVersion</tt>. The
251    Install.NEW_SCHEMA_VERSION counter must be increased (by hand!).
252    </p>
253
254    <p>
255    The class Update.java contains the method updateDatabase that
256    should be changed to reflect the changes. The change should be
257    documented in this class.
258    </p>
259  </dd>
260
261  </dl>
262 
263  <a name="plugins"></a>
264  <h2>6. Plug-ins</h2>
265 
266  <dl>
267  <dt>a) <a href="plugins/index.html">How to write plug-ins</a></dt>
268  <dd>
269    Document describing how to write a plug-in for BASE 2.
270  </dd>
271
272  <dt>b) <a href="plugins/import/index.html">Plug-ins for importing data</a></dt>
273  <dd>
274    How to create a plug-in that imports data.
275  </dd>
276 
277  <dt>c) <a href="plugins/authentication/index.html">Authentication plug-ins</a> - TODO</dt>
278  <dd>
279    With an authentication plug-in you can use any external
280    source for authenticating users when the log on to BASE.
281  </dd>
282 
283  <dt>d) <a href="plugins/analysis/index.html">Analysis plug-ins</a></dt>
284  <dd>
285    Information that is specific for analysis plug-ins.
286  </dd>
287 
288  <dt>e) <a href="plugins/storage/index.html">Secondary file storage</a> - TODO</dt>
289  <dd>
290  </dd>
291 
292  <dt>f) Example plug-ins with source code
293  <dd>
294    <p>
295    Contains the following example plug-ins:
296    </p>
297   
298    <ul>
299    <li>ExampleImporter: Pretends to import samples. It will ask for a file
300      and if existing samples should be updated or not, but doesn't
301      actually import anything.
302
303    <li>ExampleAnalyzer: Asks for a multiplication factor and a cut-off value.
304      It will create a child bioassay set by multiplying the original intensities
305      with the given factor and filter out those with original intensities less than
306      the cut-off. It works for any number of channels.
307   
308    </ul>
309    <br>
310    <p>
311    <a href="plugins/exampleplugins.tar.gz">Download</a> a tar file with the source
312    and compiled code.
313    </p>
314   
315  </dd>
316 
317  </dl>
318
319  <a name="running">
320  <h2>7. Running BASE in the subversion tree</h2>
321  </a>
322
323  <p> This section explains how to run a BASE server directly from the
324  subversion WC. The steps described here assume many things such as a
325  running database engine, an already set up tomcat server, and
326  more. If you have not made an initial BASE setup please refer to the
327  <a href=../installation.html>BASE installation document</a> for
328  information on how to setup BASE.</p>
329
330  <ol type=a>
331
332    <li>
333      <p> <a href=http://base.thep.lu.se/wiki/DownloadPage>Checkout of
334      the source</a> from the subversion repository. Change directory
335      to the checked out working copy of BASE.</p>
336    </li>
337
338    <li>
339      <p> Compile the project with <tt>ant web</tt>. This command will
340        compile the all packages needed to run the web server. There
341        are other targets for ant, see
342        <a
343        href=http://base.thep.lu.se/browser/trunk/build.xml>build.xml</a>
344        for the additional targets. </p>
345    </li>
346
347    <li>
348      <p> Place a working <tt>base.config</tt> file
349      to <tt>www/WEB-INF/classes/</tt>. </p>
350    </li>
351
352    <li>
353      <p> Copy <tt>src/log4j.properties.in</tt>
354      to <tt>www/WEB-INF/classes/log4j.properties</tt>. </p>
355    </li>
356
357    <li>
358      <p> Copy <tt>src/web.xml.in</tt>
359      to <tt>www/WEB-INF/classes/web.xml</tt>. </p>
360    </li>
361
362    <li>
363      <p> You may need to run the database schema update scripts if
364      the database schema has changed, or it may even be necessary to
365      regenerate the database completely depending on what you check
366      out from the repository. First do
367<pre>
368  ant installprg
369  cd src
370  ln -s ../www
371  cd install
372</pre>
373      If you need to update the database do (performing this is safe
374      even if you don't need the update)
375<pre>
376  ./updatedb.sh password
377  ./updateindexes.sh password
378</pre>
379      or if you need to reinitialize the underlying database do
380<pre>
381  &lt;connect to your rdbms and clear base and basedynamic>
382  ./initdb.sh password
383</pre>
384      <tt>password</tt> should be replaced with the BASE application
385      root account password. </p>
386
387      <p> You can remove the symbolic link created to the <tt>www</tt>
388      directory. The link is only needed to update or recreate the
389      database. </p>
390    </li>
391
392    <li>
393      <p> Create a link to <tt>/path/to/base/www</tt> from the
394      tomcat <tt>webapps</tt> directory:
395<pre>
396  cd /path/to/tomcat/webapps
397  ln -s /path/to/base/www base
398</pre>
399      </p>
400    </li>
401
402    <li>
403      <p> Restart tomcat. </p>
404    </li>
405
406    <li>
407      <p> Point your favourite browser to http://my.server:8080/base
408      (change the port number appropriately depending on how you set
409      up your tomcat server).</p>
410    </li>
411
412  </ol>
413
414  <a name="newrelease">
415  <h2>8. Publishing a new release</h2>
416  </a>
417
418  <p> <b> Publishing a bug fix release </b> <br>
419  This section describes what to do when publishing a bug fix release
420  of BASE, <i>e.g.</i> going from version 2.0.1 to 2.0.2.
421  </p>
422
423  <p>
424  <ol type=a>
425
426    <li>
427      <p> Make sure that everything that all commits are performed
428      into to the feature branch. Such as bumping version number(s) in
429      build.xml. The version and build numbers are pushed into
430      Application.java during packaging or build phase.</p>
431    </li>
432
433    <li>
434      <p> Create a tag using a one liner like
435<pre>
436  svn copy http://lev.thep.lu.se/repository/base/branches/2.0.2 \
437           http://lev.thep.lu.se/repository/base/tags/2.0.2 \
438           -m "Tagging version 2.0.2"
439</pre>
440      </p>
441    </li>
442
443    <li>
444      <p> Upgrade the demo server. </p>
445    </li>
446
447    <li>
448      <p> Create a new feature branch using a one liner like
449<pre>
450  svn copy http://lev.thep.lu.se/repository/base/tags/2.0.2 \
451           http://lev.thep.lu.se/repository/base/branches/2.0.3 \
452           -m "New bug fix branch for 2.0"
453</pre>
454      </p>
455    </li>
456
457    <li>
458      <p> Update the version list in Trac using the trac-admin
459      tool. </p>
460    </li>
461
462    <li>
463      <p> Create new binary and source packages with 'ant
464      package'. Publish the new version on
465      <a href=http://base.thep.lu.se/wiki/DownloadPage>the
466      wiki</a>. Also make the appropriate update to the download
467      page. </p>
468    </li>
469
470    <li>
471      <p> Merge the feature branch into the trunk.
472      <ol>
473        <li> <p> Checkout a pristine version of the trunk.
474<pre>
475  svn checkout http://lev.thep.lu.se/repository/base/trunk
476</pre>
477        </p>
478        </li>
479        <li>
480          <p> Merge changes into back into trunk. The branch started
481          at revision N and ended at revision M.
482<pre>
483  svn merge -r N:M http://lev.thep.lu.se/repository/base/branches/2.0.2
484</pre>
485          </p>
486        </li>
487        <li>
488          <p> Fix all conflicts. Run TestAll and do a installation to
489          make sure that the merge succeeded. </p>
490        </li>
491        <li>
492          <p> Add a log line in doc/merge.txt specifying what has been
493          merged. </p>
494        </li>
495        <li>
496          <p> Commit changes to trunk.
497<pre>
498  svn commit -m "Merged log:branches/2.0.2#N:M trunk."
499</pre>
500          </p>
501        </li>
502      </ol>
503      </p>
504    </li>
505
506    <li>
507      <p> Delete the old feature branch using a one liner like
508<pre>
509  svn delete http://lev.thep.lu.se/repository/base/branches/2.0.2 \
510          -m "Removed obsolete branch 2.0.2 superseded by source:/branches/2.0.3"
511</pre>
512      </p>
513    </li>
514
515    <li>
516      <p> Close the <a href=http://base.thep.lu.se/roadmap/>milestone
517      associated with the release</a> and add a new milestone. </p>
518    </li>
519
520  </ol>
521  </p>
522
523
524  <p> <b> Publishing a minor release </b> <br>
525  This section describes what to do when publishing a minor release
526  of BASE, <i>e.g.</i> going from version 2.0.x to 2.1
527  </p>
528
529  <p>
530  <ol type=a>
531
532    <li>
533      <p> Make sure that everything that all commits are performed
534      into to the feature branch. Such as bumping version number(s) in
535      build.xml. The version and build numbers are pushed into
536      Application.java during packaging or build phase.</p>
537    </li>
538
539    <li>
540      <p> Create a tag using a one liner like
541<pre>
542  svn copy http://lev.thep.lu.se/repository/base/trunk \
543           http://lev.thep.lu.se/repository/base/tags/2.1 \
544           -m "Tagging version 2.1"
545</pre>
546      </p>
547    </li>
548
549    <li>
550      <p> Upgrade the demo server. </p>
551    </li>
552
553    <li>
554      <p> Create a new feature branch using a one liner like
555<pre>
556  svn copy http://lev.thep.lu.se/repository/base/tags/2.1 \
557           http://lev.thep.lu.se/repository/base/branches/2.1.1 \
558           -m "New bug fix branch for 2.1"
559</pre>
560      </p>
561    </li>
562
563    <li>
564      <p> Update the version list in Trac using the trac-admin
565      tool. </p>
566    </li>
567
568    <li>
569      <p> Create new binary and source packages with 'ant
570      package'. Publish the new version on
571      <a href=http://base.thep.lu.se/wiki/DownloadPage>the
572      wiki</a>. Also make the appropriate update to the download
573      page. </p>
574    </li>
575
576    <li>
577      <p> Close the <a href=http://base.thep.lu.se/roadmap/>milestone
578      associated with the release</a> and add a new milestone. </p>
579    </li>
580
581  </ol>
582  </p>
583
584
585</body>
586</html>
Note: See TracBrowser for help on using the repository browser.