$Id: README.developer 3144 2013-12-18 08:18:48Z peter $

Coding Style

We follow the coding style described in ​C++ coding guidelines ​pdf ​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 ​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 test/README​.

Interfacing ​Gnu Scientific Library, GSL

The GSL documentation describes how ​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 ​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 ​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 ​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.

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.63 (or later), ​http://www.gnu.org/software/automake/
• 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.

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

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 'NEWS' and '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 '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 '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@…

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 ​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 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 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/>.