source: trunk/README.developer @ 3417

$Id: README.developer 3417 2015-05-25 01:35:59Z peter $

= Coding Style =

We follow the coding style described in
[http://cbbp.thep.lu.se/~jari/documents/c++_coding_guidelines/index.html C++ coding guidelines]
[http://cbbp.thep.lu.se/~jari/documents/c++_coding_guidelines/c++_coding_guidelines.pdf pdf]
[http://cbbp.thep.lu.se/~jari/documents/c++_coding_guidelines/c++_coding_guidelines.ps postscript]
with the additions described here.

=== Subversion usage ===

Commits should be minimalistic and the project should always compile
(`make` and `make check`) when someone makes a clean checkout. There
is a short introduction to subversion and its usage available as
[http://cbbp.thep.lu.se/~jari/documents/subversion_guidelines/index.html Subversion guidelines].
We follow these guidelines.

=== Testing ===

The test suite is run with `make check` at the project root directory
level.

The test suite should at minimum include creation of all classes (to
catch linking errors) and calls to template functions (as template
functions are not compiled until they are needed). There is a test
that checks that minimum amount of documentation is written. This test
is skipped if doxygen is not available and for that reason it is
recommended to have doxygen available if you modify header files.

For more details on writing and running tests, see file
[source:trunk/test/README test/README].

=== Interfacing [http://www.gnu.org/software/gsl/ Gnu Scientific Library, GSL] ===

The GSL documentation describes how
[http://www.gnu.org/software/gsl/manual/html_node/Error-Handling.html GSL error handling]
works. The GSL library follows the thread-safe
error reporting conventions of the posix Threads library. That is,
functions return a non-zero error code to indicate an error. In most
cases yat just returns whatever the underlying GSL library calls
returns. If GSL errors occur in constructors yat handles them
accordingly. If GSL reports errors that cannot be resolved by yat a
[http://cbbp.thep.lu.se/~jari/documents/yat/classtheplu_1_1yat_1_1utility_1_1GSL__error.html GSL_error]
exception will be thrown. However, the default behaviour of
GSL library is to call abort() when unrecoverable errors occur and
puts the yat (and any other) GSL error treatment out of play. For
production environments, yat and GSL users should turn off the default
GSL error treatment by calling gsl_set_error_handler_off(), but also
when yat's GSL error treatment is preferred.

When new GSL functionality is introduced to yat, it is the
responsibility of the programmer to make sure that GSL errors are
treated properly. Proper GSL error treatment is very important in
cases when yat users turn off the default GSL error handler since:

yat aims at treating GSL errors appropriately in an
[http://www.gotw.ca/gotw/008.htm exception safe and neutral]
way but there is still some work to do before we do exceptions in a neutral way.

=== Samtools ===

Code that depends on samtools API should be excluded from the build
when configured --without-samtools, i.e., put files within
`HAVE_LIBBAM` conditionals (or alternatively put code inside `#ifdef
HAVE_SAMTOOL` preprocessor conditionals). In order to support multiple
inclusion styles we do not include <bam.h> directly, but `#include
<config_bam.h>` and `#include YAT_BAM_HEADER`. Similarly, for `<sam.h>`
include `YAT_SAM_HEADER`. For more details on this, refer to
`yat/omic/config_bam.h`.

=== Doxygen ===
We generate our documentation using [http://www.doxygen.org Doxygen]
(version 1.5 or later). Doxygen allows several different styles. We
try to use the following style as we have found this minimizes parsing
problems:

{{{
/**
   \brief My class

   Some text documenting the class MyClass
*/
class MyClass
}}}

or similarly

{{{
/**
   \brief magic function

   Some text documenting my_function
*/
void my_function(void);
}}}

We use doxygen keywords preceded by `\` such as `\brief`,
`\return`. All classes and functions have a brief description, which
increases clarity on summary pages.

Try to keep comment line lengths within the terminal character limit,
in other words, less than 80 characters per line. This makes the
comments more readable.

'''Internal Interface'''

Helper functions and classes that are not part of yat API should
either be labeled with doxygen flag `\internal` or placed in
sub-namespace `detail`. Functionality placed in namespace `detail`
should be excluded from doxygen input using a pattern like this:

/// \cond IGNORE_DOXYGEN
namespace detail {

<Some very detailed code here>

}
/// \endcode

= Build =

== Requirements ==

To build from a subversion checkout, you will need GNU Autotools. More
specifically
 * Automake 1.11 (or later), http://www.gnu.org/software/automake/
 * Autoconf 2.64 (or later), http://www.gnu.org/software/autoconf/
 * Libtool 1.5 (or later), http://www.gnu.org/software/libtool/

== Disable shared library ==

yat uses GNU Libtool in order to build shared libraries on a variety
of systems.  While this is very nice for making usable binaries, it
can be a pain when trying to debug a program. For that reason,
compilation of shared libraries can be turned off by specifying the
`--disable-shared` option to configure.

== Debugging using GDB ==

If shared library is enabled (default), Libtool creates wrapper
scripts in directory `test/` that call the test programs located in
directory `test/.libs/`. While this allows us to dynamically link against
the temporary library in `yat/`, it makes straightforward usage of GDB
impossible. For that reason libtool provides a wrapper:

`#> libtool --mode=execute gdb foo_test`

that sets the necessary environment variables. For more detailed
discussion, please refer to the libtool manual:

http://www.gnu.org/software/libtool/manual/libtool.html#Debugging-executables


= Release Procedure =

These instructions cover how to release minor and patch releases in a
project that uses trac/subversion for revision control and project
management. How to release major releases is not covered yet since we
have not done that (with the exception of the first release). Release
numbering follows the normal convention of major.minor.patch and the
APR (see http://apr.apache.org/versioning.html) guidelines for
releases are used.

The main development is performed in the trunk branch of the
repository. A new release branch is created for each minor release
from the trunk and patch releases are snapshots of the minor release
branch. This implies that patch work is performed in the minor release
branch, and changes made release branch is transferred to the trunk
every time a new patch release is made. Remember, patch work should be
limited to bug fixes and important fixes only leaving development of
new features and designs to the trunk branch.

Releases should only be performed by an appointed member of the team,
the Release Manager.


=== Creating a release branch ===

Once people agree that a new release branch should be made, the
Release Manager creates it with the following procedure
(substitute A.B with the version you are preparing, e.g. 0.3)

 1. Check that 'YAT_LT_VERSION_INFO' is set correcly
    otherwise update following line in 'm4/version.m4'

8<----
    m4_define([YAT_LT_VERSION_INFO], [c:r:a])
8<----

 2. Add a line in NEWS
8<----
     See the end for copyrights and conditions.

    +yat A.B.x series from http://dev.thep.lu.se/yat/svn/branches/A.B-stable
    +
     Version A.B (released NOT YET)
8<----

 3. Commit the changes with

    #> svn ci -m "Prepare A.B-stable branch"

 4. For this step svncopyright is needed, http://dev.thep.lu.se/svndigest.
    Update copyright statements with command:

    #> make copyright

    Examine the updates and commit changes with

    #> svn ci -m "updating copyright statements"`.

 5. Create a new stable branch with

    #> make svn-stable-branch

 6. Prepare the trunk for the next minor release

   a) Update version number in 'm4/version.m4'. Locate and change the
      below lines

8<----
      MY_VERSION_early([A], [B+1], [0], [true])
      m4_define([YAT_LT_VERSION_INFO], [c+1:0:0])
8<----

   b) Add an entry in `NEWS`

8<----
      version A.[B+1] (released NOT YET)
8<----

      The date is set when version A.[B+1] is released. [[br]][[br]]

   c) Commit changes to the repository:

    #> svn ci -m "Bumping VERSION to A.[B+1]pre"

 7. When someone with access to documentation site has time available,
    they will upgrade to the new branch. This person is usually not the
    release manager, so please send a reminder.

=== Rolling a minor release ===

    These instructions describe how to make a release. Replace A.B.C
    with current VERSION (A.B if this is not a patch release).

 1. Update version number in 'm4/version.m4'. Locate and change the
    below line

8<----
      MY_VERSION_early([A], [B], [C], [false])
8<----


 2. Update the interface version number in 'm4/version.m4'. Locate and
    set the version in the below line

8<----
      m4_define([YAT_LT_VERSION_INFO], [c:r:a])
8<----

    appropriately. Refer to file 'm4/version.m4' for details on how to
    decide triplet 'c:r:a'.


 3. Set the date for the new release in 'NEWS'.

8<----
      version A.B.C (released 26 June 2007)
8<----


 4. Make sure that the items in 'NEWS' cover the new features of the
    release.


 5. Commit changes to the repository:

    #> svn ci -m "Preparing release A.B.C"


 6. For this step svncopyright is needed, http://dev.thep.lu.se/svndigest.
    Update copyright statements with command:

    #> make copyright

    Examine the updates and commit changes with

    #> svn ci -m "updating copyright statements"


 7. Now it's time to create a tarball, an svn tag, and upload the
    tarball to sourceforge. For this to work you need to hold write
    permissions at libyat project page at sourceforge. If your sf user
    id is different from the one defined in 'Makefile.am', you can
    override the default with 'sf_user=<your id>'. Issue the
    convenience target:

    #> make release-tag-upload sf_user=<sourceforge user id>

    This will run some sanity checks, run maintainer-check and
    distcheck, create an svn tag, and upload the newly created tarball
    to sourceforge. The last step requires that you provide your SF password.


 8. On WikiStart update links
    '[source:tags/A.B.C/NEWS NEWS]' and
    '[source:branches/A.B-stable/README README]'

 9. Update SubversionCheckout

   a) In section 'yat latest release' update command to
      'svn checkout http://dev.thep.lu.se/yat/svn/tags/A.B.C yat-A.B.C
      and link to
      '[source:tags/A.B.C/NEWS NEWS]'
      If this is a patch release jump to point 10).

   b) In section 'yat stable' update command to
      'svn checkout http://dev.thep.lu.se/yat/svn/branches/A.B-stable yat-A.B.x
      and link to
      '[source:branches/A.B-stable/NEWS NEWS]'


 10. Close the milestone associated with this release.


 11. Update the version list in Trac using the trac-admin tool.


 12. Use file 'announcement.txt' as template and send email to
    libyat-users@lists.sourceforge.net


 13. Merge the release into the trunk.

    a) Go to a pristine trunk WC:

       #> cd /path/to/yat-trunk/
       #> make check-svn-diff

    b) Merge changes into trunk:

       #> svn merge ^/branches/A.B-stable

    c) Resolve potential conflicts. Run tests and perform all other
       appropriate tests to make sure that the merge does not create
       havoc. Typically changes in `m4/version.m4` are problematic so
       check this file extra carefully.

    d) Commit changes to the trunk branch.

       #> svn commit -m "Merged release A.B.C into trunk."


 14. Prepare the stable branch for the next patch release.

    a) Update version number in 'm4/version.m4'. Locate and change the
       below line

8<---
       MY_VERSION_early([A], [B], [C+1], [true])
8<---

       Run 'make all' and while waiting finalize item b) below

    b) Add an entry in 'NEWS'

8<----
       version A.B.[C+1] (released NOT YET)
8<----

       The date is set when version A.B.[C+1] is released.


 15. Commit changes to the repository:

    #> svn ci -m "Bumping VERSION to A.B.[C+1]pre"


= Versioning =

We use a softened version of
[http://apr.apache.org/versioning.html APR guidelines] which in short implies

''"The basic intent is that '''`MAJOR`''' versions are incompatible,
large-scale upgrades of the API. '''`MINOR`''' versions retain
compatibility with older minor versions, and changes in the
'''`PATCH`''' level are perfectly compatible, forwards and
backwards."''

== '''`MAJOR`''' Releases ==

No compatibility is guaranteed between '''`MAJOR`''' versions.

== '''`MINOR`''' Releases ==

'''`MINOR`''' versions should be compatible with earlier minor
versions. However, in the `0.x` line we may allow exceptions to this
rule, if developers agree the gain of change is sufficient. Binary compatibility is typically not guaranteed between '''`MINOR`''' versions. The `YAT_LT_VERSION` in [source:trunk/build_support/version.m4 version.m4] should reflect which versions are binary compatible.

== '''`PATCH`''' Releases ==

Versions with same '''`MAJOR.MINOR`''' are perfectly compatible,
forwards and backwards.

This implies that only implementations can be modified in a `PATCH`
release. You cannot change the API, not even add functions or
classes because it will break forward compatibility for the previous
`PATCH` version. A `PATCH` release is a pure bug fix release

=== Backward Source Compatibility ===

Backward Source Compatibility means that an application that could build
against version `x.y` shall also build without error against
`x.y+1`. An application that compiled against header files from
previous `MINOR` version shall also compile without errors against the
header files of the new version.

Specifically this implies:
  - Do not remove any public, protected, or free functions.
  - If you modify a function, its signature must be compatible with
    previous signature, e.g., new parameters with default values may
    be added to signature.
  - Do not remove any class or inheritance for a class.

=== Backward Binary Compatibility ===

Backward Binary Compatibility means that an application that has been
compiled against version `x.y` can be linked against version
`x.y+1`.

Specifically this implies:

  - Do not remove or modify any function (except private), not even
    add a parameter with default value because it will make the
    function incompatible with earlier header files.

  - Do not add, remove, or modify member variables, because that will
    change the allocated size of the class. Therefore, to allow
    modifications of the internal representation, it is preferable to
    hold member variable is a ''pimpl'' that is allocated privately.
    http://developer.gnome.org/doc/guides/programming-guidelines/binary.html

  - Do not add or change order among virtual functions because it will
    change the layout of the virtual table.




----------------------------------------------------------------------
{{{
Copyright (C) 2003 Jari Häkkinen, Peter Johansson
Copyright (C) 2004 Jari Häkkinen
Copyright (C) 2006, 2007, 2008, 2009 Jari Häkkinen, Peter Johansson
Copyright (C) 2010, 2011, 2012, 2013, 2014, 2015 Peter Johansson

This file is part of yat library, http://dev.thep.lu.se/yat

The yat library is free software; you can redistribute it and/or
modify it under the terms of the GNU General Public License as
published by the Free Software Foundation; either version 3 of the
License, or (at your option) any later version.

The yat library is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
General Public License for more details.

You should have received a copy of the GNU General Public License
along with yat. If not, see <http://www.gnu.org/licenses/>.
}}}