README.developer

Code
Comments
Other
Rev Date Author Line
2 19 Feb 03 jari 1 $Id$
2 19 Feb 03 jari 2
1674 22 Dec 08 peter 3 = Coding Style =
1605 28 Oct 08 peter 4
1674 22 Dec 08 peter 5 We follow the coding style described in
4110 27 Sep 21 peter 6 [https://cbbp.thep.lu.se/~jari/documents/c++_coding_guidelines/index.html C++ coding guidelines]
4110 27 Sep 21 peter 7 [https://cbbp.thep.lu.se/~jari/documents/c++_coding_guidelines/c++_coding_guidelines.pdf pdf]
4110 27 Sep 21 peter 8 [https://cbbp.thep.lu.se/~jari/documents/c++_coding_guidelines/c++_coding_guidelines.ps postscript]
1674 22 Dec 08 peter 9 with the additions described here.
1674 22 Dec 08 peter 10
1721 15 Jan 09 jari 11 === Subversion usage ===
1721 15 Jan 09 jari 12
1721 15 Jan 09 jari 13 Commits should be minimalistic and the project should always compile
1721 15 Jan 09 jari 14 (`make` and `make check`) when someone makes a clean checkout. There
1721 15 Jan 09 jari 15 is a short introduction to subversion and its usage available as
4110 27 Sep 21 peter 16 [https://cbbp.thep.lu.se/~jari/documents/subversion_guidelines/index.html Subversion guidelines].
2404 12 Jan 11 peter 17 We follow these guidelines.
1721 15 Jan 09 jari 18
1674 22 Dec 08 peter 19 === Testing ===
1674 22 Dec 08 peter 20
1721 15 Jan 09 jari 21 The test suite is run with `make check` at the project root directory
1721 15 Jan 09 jari 22 level.
1674 22 Dec 08 peter 23
1721 15 Jan 09 jari 24 The test suite should at minimum include creation of all classes (to
1721 15 Jan 09 jari 25 catch linking errors) and calls to template functions (as template
1721 15 Jan 09 jari 26 functions are not compiled until they are needed). There is a test
2500 26 Jun 11 peter 27 that checks that minimum amount of documentation is written. This test
2500 26 Jun 11 peter 28 is skipped if doxygen is not available and for that reason it is
2500 26 Jun 11 peter 29 recommended to have doxygen available if you modify header files.
1721 15 Jan 09 jari 30
1721 15 Jan 09 jari 31 For more details on writing and running tests, see file
1721 15 Jan 09 jari 32 [source:trunk/test/README test/README].
1721 15 Jan 09 jari 33
4357 23 Aug 23 peter 34 === Interfacing [https://www.gnu.org/software/gsl/ Gnu Scientific Library, GSL] ===
1674 22 Dec 08 peter 35
1674 22 Dec 08 peter 36 The GSL documentation describes how
4357 23 Aug 23 peter 37 [https://www.gnu.org/software/gsl/manual/html_node/Error-Handling.html
4110 27 Sep 21 peter 38 GSL error handling] works. The GSL library follows the thread-safe
1674 22 Dec 08 peter 39 error reporting conventions of the posix Threads library. That is,
1674 22 Dec 08 peter 40 functions return a non-zero error code to indicate an error. In most
1674 22 Dec 08 peter 41 cases yat just returns whatever the underlying GSL library calls
1674 22 Dec 08 peter 42 returns. If GSL errors occur in constructors yat handles them
1674 22 Dec 08 peter 43 accordingly. If GSL reports errors that cannot be resolved by yat a
4110 27 Sep 21 peter 44 [https://cbbp.thep.lu.se/~jari/documents/yat/classtheplu_1_1yat_1_1utility_1_1GSL__error.html
4110 27 Sep 21 peter 45 GSL_error] exception will be thrown. However, the default behaviour of
4110 27 Sep 21 peter 46 GSL library is to call abort() when unrecoverable errors occur, which
1674 22 Dec 08 peter 47 puts the yat (and any other) GSL error treatment out of play. For
4110 27 Sep 21 peter 48 production environments or when yat's GSL error treatment is
4110 27 Sep 21 peter 49 preferred, yat and GSL users should turn off the default GSL error
4110 27 Sep 21 peter 50 treatment either by calling gsl_set_error_handler_off() or by passing
4110 27 Sep 21 peter 51 [https://cbbp.thep.lu.se/~jari/documents/yat/namespacetheplu_1_1yat_1_1utility.html#ac846162271bf37e091b4692ba865b178
4110 27 Sep 21 peter 52 yat::utility::gsl_error_handler] to gsl_set_error.
1674 22 Dec 08 peter 53
1674 22 Dec 08 peter 54 When new GSL functionality is introduced to yat, it is the
1721 15 Jan 09 jari 55 responsibility of the programmer to make sure that GSL errors are
1674 22 Dec 08 peter 56 treated properly. Proper GSL error treatment is very important in
4110 27 Sep 21 peter 57 cases when yat users turn off the default GSL error handler since yat
4110 27 Sep 21 peter 58 aims at treating GSL errors appropriately in an
4110 27 Sep 21 peter 59 [http://www.gotw.ca/gotw/008.htm exception safe and neutral] way but
4110 27 Sep 21 peter 60 there is still some work to do before we do exceptions in a neutral
4110 27 Sep 21 peter 61 way.
1674 22 Dec 08 peter 62
2943 04 Jan 13 peter 63 === Samtools ===
2943 04 Jan 13 peter 64
2943 04 Jan 13 peter 65 Code that depends on samtools API should be excluded from the build
3983 26 Aug 20 peter 66 when configured --without-htslib, i.e., put files within
3983 26 Aug 20 peter 67 `YAT_HAVE_HTSLIB` conditionals, as defined in
3983 26 Aug 20 peter 68 'yat/utility/config_public.h'.
2943 04 Jan 13 peter 69
1674 22 Dec 08 peter 70 === Doxygen ===
2071 24 Sep 09 peter 71 We generate our documentation using [http://www.doxygen.org Doxygen]
2071 24 Sep 09 peter 72 (version 1.5 or later). Doxygen allows several different styles. We
2071 24 Sep 09 peter 73 try to use the following style as we have found this minimizes parsing
2071 24 Sep 09 peter 74 problems:
1674 22 Dec 08 peter 75
1674 22 Dec 08 peter 76 {{{
1674 22 Dec 08 peter 77 /**
1674 22 Dec 08 peter 78    \brief My class
1674 22 Dec 08 peter 79
1674 22 Dec 08 peter 80    Some text documenting the class MyClass
1674 22 Dec 08 peter 81 */
1674 22 Dec 08 peter 82 class MyClass
1674 22 Dec 08 peter 83 }}}
1674 22 Dec 08 peter 84
2711 16 Mar 12 peter 85 or similarly
1674 22 Dec 08 peter 86
1674 22 Dec 08 peter 87 {{{
1674 22 Dec 08 peter 88 /**
1674 22 Dec 08 peter 89    \brief magic function
1674 22 Dec 08 peter 90
1674 22 Dec 08 peter 91    Some text documenting my_function
1674 22 Dec 08 peter 92 */
1674 22 Dec 08 peter 93 void my_function(void);
1674 22 Dec 08 peter 94 }}}
1674 22 Dec 08 peter 95
2071 24 Sep 09 peter 96 We use doxygen keywords preceded by `\` such as `\brief`,
2071 24 Sep 09 peter 97 `\return`. All classes and functions have a brief description, which
2071 24 Sep 09 peter 98 increases clarity on summary pages.
1674 22 Dec 08 peter 99
2071 24 Sep 09 peter 100 Try to keep comment line lengths within the terminal character limit,
2071 24 Sep 09 peter 101 in other words, less than 80 characters per line. This makes the
2071 24 Sep 09 peter 102 comments more readable.
1674 22 Dec 08 peter 103
1674 22 Dec 08 peter 104 '''Internal Interface'''
1674 22 Dec 08 peter 105
3188 25 Mar 14 peter 106 Helper functions and classes that are not part of yat API should
3188 25 Mar 14 peter 107 either be labeled with doxygen flag `\internal` or placed in
3188 25 Mar 14 peter 108 sub-namespace `detail`. Functionality placed in namespace `detail`
3188 25 Mar 14 peter 109 should be excluded from doxygen input using a pattern like this:
1674 22 Dec 08 peter 110
3188 25 Mar 14 peter 111 /// \cond IGNORE_DOXYGEN
3188 25 Mar 14 peter 112 namespace detail {
3188 25 Mar 14 peter 113
3188 25 Mar 14 peter 114 <Some very detailed code here>
3188 25 Mar 14 peter 115
3188 25 Mar 14 peter 116 }
3188 25 Mar 14 peter 117 /// \endcode
3188 25 Mar 14 peter 118
1674 22 Dec 08 peter 119 = Build =
1674 22 Dec 08 peter 120
1674 22 Dec 08 peter 121 == Requirements ==
1674 22 Dec 08 peter 122
2404 12 Jan 11 peter 123 To build from a subversion checkout, you will need GNU Autotools. More
2711 16 Mar 12 peter 124 specifically
4357 23 Aug 23 peter 125  * Automake 1.11 (or later), https://www.gnu.org/software/automake/
4357 23 Aug 23 peter 126  * Autoconf 2.64 (or later), https://www.gnu.org/software/autoconf/
4357 23 Aug 23 peter 127  * Libtool 2.0 (or later), https://www.gnu.org/software/libtool/
1605 28 Oct 08 peter 128
1674 22 Dec 08 peter 129 == Disable shared library ==
573 06 Apr 06 jari 130
2404 12 Jan 11 peter 131 yat uses GNU Libtool in order to build shared libraries on a variety
1368 10 Jul 08 peter 132 of systems.  While this is very nice for making usable binaries, it
1368 10 Jul 08 peter 133 can be a pain when trying to debug a program. For that reason,
1368 10 Jul 08 peter 134 compilation of shared libraries can be turned off by specifying the
1368 10 Jul 08 peter 135 `--disable-shared` option to configure.
1368 10 Jul 08 peter 136
1674 22 Dec 08 peter 137 == Debugging using GDB ==
1372 15 Jul 08 peter 138
2404 12 Jan 11 peter 139 If shared library is enabled (default), Libtool creates wrapper
2404 12 Jan 11 peter 140 scripts in directory `test/` that call the test programs located in
2404 12 Jan 11 peter 141 directory `test/.libs/`. While this allows us to dynamically link against
2404 12 Jan 11 peter 142 the temporary library in `yat/`, it makes straightforward usage of GDB
1372 15 Jul 08 peter 143 impossible. For that reason libtool provides a wrapper:
1372 15 Jul 08 peter 144
1372 15 Jul 08 peter 145 `#> libtool --mode=execute gdb foo_test`
1372 15 Jul 08 peter 146
1372 15 Jul 08 peter 147 that sets the necessary environment variables. For more detailed
1372 15 Jul 08 peter 148 discussion, please refer to the libtool manual:
1372 15 Jul 08 peter 149
4357 23 Aug 23 peter 150 https://www.gnu.org/software/libtool/manual/libtool.html#Debugging-executables
1372 15 Jul 08 peter 151
3144 18 Dec 13 peter 152
3144 18 Dec 13 peter 153 = Release Procedure =
3144 18 Dec 13 peter 154
3144 18 Dec 13 peter 155 These instructions cover how to release minor and patch releases in a
3144 18 Dec 13 peter 156 project that uses trac/subversion for revision control and project
3144 18 Dec 13 peter 157 management. How to release major releases is not covered yet since we
3144 18 Dec 13 peter 158 have not done that (with the exception of the first release). Release
3144 18 Dec 13 peter 159 numbering follows the normal convention of major.minor.patch and the
3144 18 Dec 13 peter 160 APR (see http://apr.apache.org/versioning.html) guidelines for
3144 18 Dec 13 peter 161 releases are used.
3144 18 Dec 13 peter 162
3144 18 Dec 13 peter 163 The main development is performed in the trunk branch of the
3144 18 Dec 13 peter 164 repository. A new release branch is created for each minor release
3144 18 Dec 13 peter 165 from the trunk and patch releases are snapshots of the minor release
3144 18 Dec 13 peter 166 branch. This implies that patch work is performed in the minor release
3144 18 Dec 13 peter 167 branch, and changes made release branch is transferred to the trunk
3144 18 Dec 13 peter 168 every time a new patch release is made. Remember, patch work should be
3144 18 Dec 13 peter 169 limited to bug fixes and important fixes only leaving development of
3144 18 Dec 13 peter 170 new features and designs to the trunk branch.
3144 18 Dec 13 peter 171
3144 18 Dec 13 peter 172 Releases should only be performed by an appointed member of the team,
3144 18 Dec 13 peter 173 the Release Manager.
3144 18 Dec 13 peter 174
3144 18 Dec 13 peter 175
3144 18 Dec 13 peter 176 === Creating a release branch ===
3144 18 Dec 13 peter 177
3144 18 Dec 13 peter 178 Once people agree that a new release branch should be made, the
3144 18 Dec 13 peter 179 Release Manager creates it with the following procedure
3144 18 Dec 13 peter 180 (substitute A.B with the version you are preparing, e.g. 0.3)
3144 18 Dec 13 peter 181
3144 18 Dec 13 peter 182  1. Check that 'YAT_LT_VERSION_INFO' is set correcly
3144 18 Dec 13 peter 183     otherwise update following line in 'm4/version.m4'
3144 18 Dec 13 peter 184
3144 18 Dec 13 peter 185 8<----
3144 18 Dec 13 peter 186     m4_define([YAT_LT_VERSION_INFO], [c:r:a])
3144 18 Dec 13 peter 187 8<----
3144 18 Dec 13 peter 188
3144 18 Dec 13 peter 189  2. Add a line in NEWS
3144 18 Dec 13 peter 190 8<----
3144 18 Dec 13 peter 191      See the end for copyrights and conditions.
3144 18 Dec 13 peter 192
4357 23 Aug 23 peter 193     +yat A.B.x series from https://dev.thep.lu.se/yat/svn/branches/A.B-stable
3144 18 Dec 13 peter 194     +
3144 18 Dec 13 peter 195      Version A.B (released NOT YET)
3144 18 Dec 13 peter 196 8<----
3144 18 Dec 13 peter 197
3144 18 Dec 13 peter 198  3. Commit the changes with
3144 18 Dec 13 peter 199
3144 18 Dec 13 peter 200     #> svn ci -m "Prepare A.B-stable branch"
3144 18 Dec 13 peter 201
4357 23 Aug 23 peter 202  4. For this step svncopyright is needed, https://dev.thep.lu.se/svndigest.
3144 18 Dec 13 peter 203     Update copyright statements with command:
3144 18 Dec 13 peter 204
3144 18 Dec 13 peter 205     #> make copyright
3144 18 Dec 13 peter 206
3144 18 Dec 13 peter 207     Examine the updates and commit changes with
3144 18 Dec 13 peter 208
3144 18 Dec 13 peter 209     #> svn ci -m "updating copyright statements"`.
3144 18 Dec 13 peter 210
3144 18 Dec 13 peter 211  5. Create a new stable branch with
3144 18 Dec 13 peter 212
3144 18 Dec 13 peter 213     #> make svn-stable-branch
3144 18 Dec 13 peter 214
3144 18 Dec 13 peter 215  6. Prepare the trunk for the next minor release
3144 18 Dec 13 peter 216
3144 18 Dec 13 peter 217    a) Update version number in 'm4/version.m4'. Locate and change the
3144 18 Dec 13 peter 218       below lines
3144 18 Dec 13 peter 219
3144 18 Dec 13 peter 220 8<----
3144 18 Dec 13 peter 221       MY_VERSION_early([A], [B+1], [0], [true])
3144 18 Dec 13 peter 222       m4_define([YAT_LT_VERSION_INFO], [c+1:0:0])
3144 18 Dec 13 peter 223 8<----
3144 18 Dec 13 peter 224
3144 18 Dec 13 peter 225    b) Add an entry in `NEWS`
3144 18 Dec 13 peter 226
3144 18 Dec 13 peter 227 8<----
3144 18 Dec 13 peter 228       version A.[B+1] (released NOT YET)
3144 18 Dec 13 peter 229 8<----
3144 18 Dec 13 peter 230
3144 18 Dec 13 peter 231       The date is set when version A.[B+1] is released. [[br]][[br]]
3144 18 Dec 13 peter 232
3144 18 Dec 13 peter 233    c) Commit changes to the repository:
3144 18 Dec 13 peter 234
3144 18 Dec 13 peter 235     #> svn ci -m "Bumping VERSION to A.[B+1]pre"
3144 18 Dec 13 peter 236
3144 18 Dec 13 peter 237  7. When someone with access to documentation site has time available,
3144 18 Dec 13 peter 238     they will upgrade to the new branch. This person is usually not the
3144 18 Dec 13 peter 239     release manager, so please send a reminder.
3144 18 Dec 13 peter 240
3144 18 Dec 13 peter 241 === Rolling a minor release ===
3144 18 Dec 13 peter 242
3144 18 Dec 13 peter 243     These instructions describe how to make a release. Replace A.B.C
3144 18 Dec 13 peter 244     with current VERSION (A.B if this is not a patch release).
3144 18 Dec 13 peter 245
3144 18 Dec 13 peter 246  1. Update version number in 'm4/version.m4'. Locate and change the
3144 18 Dec 13 peter 247     below line
3144 18 Dec 13 peter 248
3144 18 Dec 13 peter 249 8<----
3144 18 Dec 13 peter 250       MY_VERSION_early([A], [B], [C], [false])
3144 18 Dec 13 peter 251 8<----
3144 18 Dec 13 peter 252
3144 18 Dec 13 peter 253
3144 18 Dec 13 peter 254  2. Update the interface version number in 'm4/version.m4'. Locate and
3144 18 Dec 13 peter 255     set the version in the below line
3144 18 Dec 13 peter 256
3144 18 Dec 13 peter 257 8<----
3144 18 Dec 13 peter 258       m4_define([YAT_LT_VERSION_INFO], [c:r:a])
3144 18 Dec 13 peter 259 8<----
3144 18 Dec 13 peter 260
3144 18 Dec 13 peter 261     appropriately. Refer to file 'm4/version.m4' for details on how to
3144 18 Dec 13 peter 262     decide triplet 'c:r:a'.
3144 18 Dec 13 peter 263
3144 18 Dec 13 peter 264
3144 18 Dec 13 peter 265  3. Set the date for the new release in 'NEWS'.
3144 18 Dec 13 peter 266
3144 18 Dec 13 peter 267 8<----
3144 18 Dec 13 peter 268       version A.B.C (released 26 June 2007)
3144 18 Dec 13 peter 269 8<----
3144 18 Dec 13 peter 270
3144 18 Dec 13 peter 271
3144 18 Dec 13 peter 272  4. Make sure that the items in 'NEWS' cover the new features of the
3144 18 Dec 13 peter 273     release.
3144 18 Dec 13 peter 274
3144 18 Dec 13 peter 275
3144 18 Dec 13 peter 276  5. Commit changes to the repository:
3144 18 Dec 13 peter 277
3144 18 Dec 13 peter 278     #> svn ci -m "Preparing release A.B.C"
3144 18 Dec 13 peter 279
3144 18 Dec 13 peter 280
4357 23 Aug 23 peter 281  6. For this step svncopyright is needed, https://dev.thep.lu.se/svndigest.
3144 18 Dec 13 peter 282     Update copyright statements with command:
3144 18 Dec 13 peter 283
3144 18 Dec 13 peter 284     #> make copyright
3144 18 Dec 13 peter 285
3144 18 Dec 13 peter 286     Examine the updates and commit changes with
3144 18 Dec 13 peter 287
3144 18 Dec 13 peter 288     #> svn ci -m "updating copyright statements"
3144 18 Dec 13 peter 289
3144 18 Dec 13 peter 290
3144 18 Dec 13 peter 291  7. Now it's time to create a tarball, an svn tag, and upload the
3144 18 Dec 13 peter 292     tarball to sourceforge. For this to work you need to hold write
3997 08 Oct 20 peter 293     permissions at libyat project page at sourceforge and provide your
3997 08 Oct 20 peter 294     soyurceforge user ID via variable 'sf_user'. Issue the convenience
3997 08 Oct 20 peter 295     target:
3144 18 Dec 13 peter 296
3248 04 Jun 14 peter 297     #> make release-tag-upload sf_user=<sourceforge user id>
3144 18 Dec 13 peter 298
3144 18 Dec 13 peter 299     This will run some sanity checks, run maintainer-check and
3144 18 Dec 13 peter 300     distcheck, create an svn tag, and upload the newly created tarball
3144 18 Dec 13 peter 301     to sourceforge. The last step requires that you provide your SF password.
3144 18 Dec 13 peter 302
3144 18 Dec 13 peter 303
3144 18 Dec 13 peter 304  8. On WikiStart update links
3144 18 Dec 13 peter 305     '[source:tags/A.B.C/NEWS NEWS]' and
3144 18 Dec 13 peter 306     '[source:branches/A.B-stable/README README]'
3144 18 Dec 13 peter 307
3144 18 Dec 13 peter 308  9. Update SubversionCheckout
3144 18 Dec 13 peter 309
3144 18 Dec 13 peter 310    a) In section 'yat latest release' update command to
4110 27 Sep 21 peter 311       'svn checkout https://dev.thep.lu.se/yat/svn/tags/A.B.C yat-A.B.C
3144 18 Dec 13 peter 312       and link to
3144 18 Dec 13 peter 313       '[source:tags/A.B.C/NEWS NEWS]'
3144 18 Dec 13 peter 314       If this is a patch release jump to point 10).
3144 18 Dec 13 peter 315
3144 18 Dec 13 peter 316    b) In section 'yat stable' update command to
4110 27 Sep 21 peter 317       'svn checkout https://dev.thep.lu.se/yat/svn/branches/A.B-stable yat-A.B.x
3144 18 Dec 13 peter 318       and link to
3144 18 Dec 13 peter 319       '[source:branches/A.B-stable/NEWS NEWS]'
3144 18 Dec 13 peter 320
3144 18 Dec 13 peter 321
3144 18 Dec 13 peter 322  10. Close the milestone associated with this release.
3144 18 Dec 13 peter 323
3144 18 Dec 13 peter 324
3144 18 Dec 13 peter 325  11. Update the version list in Trac using the trac-admin tool.
3144 18 Dec 13 peter 326
3144 18 Dec 13 peter 327
3144 18 Dec 13 peter 328  12. Use file 'announcement.txt' as template and send email to
3144 18 Dec 13 peter 329     libyat-users@lists.sourceforge.net
3144 18 Dec 13 peter 330
3144 18 Dec 13 peter 331
3144 18 Dec 13 peter 332  13. Merge the release into the trunk.
3144 18 Dec 13 peter 333
3144 18 Dec 13 peter 334     a) Go to a pristine trunk WC:
3144 18 Dec 13 peter 335
3144 18 Dec 13 peter 336        #> cd /path/to/yat-trunk/
3144 18 Dec 13 peter 337        #> make check-svn-diff
3144 18 Dec 13 peter 338
3144 18 Dec 13 peter 339     b) Merge changes into trunk:
3144 18 Dec 13 peter 340
3144 18 Dec 13 peter 341        #> svn merge ^/branches/A.B-stable
3144 18 Dec 13 peter 342
3144 18 Dec 13 peter 343     c) Resolve potential conflicts. Run tests and perform all other
3144 18 Dec 13 peter 344        appropriate tests to make sure that the merge does not create
3144 18 Dec 13 peter 345        havoc. Typically changes in `m4/version.m4` are problematic so
3144 18 Dec 13 peter 346        check this file extra carefully.
3144 18 Dec 13 peter 347
3144 18 Dec 13 peter 348     d) Commit changes to the trunk branch.
3144 18 Dec 13 peter 349
3144 18 Dec 13 peter 350        #> svn commit -m "Merged release A.B.C into trunk."
3144 18 Dec 13 peter 351
3144 18 Dec 13 peter 352
3144 18 Dec 13 peter 353  14. Prepare the stable branch for the next patch release.
3144 18 Dec 13 peter 354
3144 18 Dec 13 peter 355     a) Update version number in 'm4/version.m4'. Locate and change the
4164 13 Mar 22 peter 356        below lines
3144 18 Dec 13 peter 357
3144 18 Dec 13 peter 358 8<---
3144 18 Dec 13 peter 359        MY_VERSION_early([A], [B], [C+1], [true])
4164 13 Mar 22 peter 360 8<-
4164 13 Mar 22 peter 361        m4_define([YAT_LT_VERSION_INFO], [c:r+1:a])
3144 18 Dec 13 peter 362 8<---
3144 18 Dec 13 peter 363
3144 18 Dec 13 peter 364        Run 'make all' and while waiting finalize item b) below
3144 18 Dec 13 peter 365
3144 18 Dec 13 peter 366     b) Add an entry in 'NEWS'
3144 18 Dec 13 peter 367
3144 18 Dec 13 peter 368 8<----
3144 18 Dec 13 peter 369        version A.B.[C+1] (released NOT YET)
3144 18 Dec 13 peter 370 8<----
3144 18 Dec 13 peter 371
3144 18 Dec 13 peter 372        The date is set when version A.B.[C+1] is released.
3144 18 Dec 13 peter 373
3144 18 Dec 13 peter 374
3144 18 Dec 13 peter 375  15. Commit changes to the repository:
3144 18 Dec 13 peter 376
3144 18 Dec 13 peter 377     #> svn ci -m "Bumping VERSION to A.B.[C+1]pre"
3144 18 Dec 13 peter 378
3144 18 Dec 13 peter 379
1674 22 Dec 08 peter 380 = Versioning =
1674 22 Dec 08 peter 381
2711 16 Mar 12 peter 382 We use a softened version of
2404 12 Jan 11 peter 383 [http://apr.apache.org/versioning.html APR guidelines] which in short implies
1674 22 Dec 08 peter 384
1674 22 Dec 08 peter 385 ''"The basic intent is that '''`MAJOR`''' versions are incompatible,
2404 12 Jan 11 peter 386 large-scale upgrades of the API. '''`MINOR`''' versions retain
2404 12 Jan 11 peter 387 compatibility with older minor versions, and changes in the
2404 12 Jan 11 peter 388 '''`PATCH`''' level are perfectly compatible, forwards and
2404 12 Jan 11 peter 389 backwards."''
1674 22 Dec 08 peter 390
2711 16 Mar 12 peter 391 == '''`MAJOR`''' Releases ==
1674 22 Dec 08 peter 392
1674 22 Dec 08 peter 393 No compatibility is guaranteed between '''`MAJOR`''' versions.
1674 22 Dec 08 peter 394
1674 22 Dec 08 peter 395 == '''`MINOR`''' Releases ==
1674 22 Dec 08 peter 396
1674 22 Dec 08 peter 397 '''`MINOR`''' versions should be compatible with earlier minor
1674 22 Dec 08 peter 398 versions. However, in the `0.x` line we may allow exceptions to this
2711 16 Mar 12 peter 399 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.
2711 16 Mar 12 peter 400
1674 22 Dec 08 peter 401 == '''`PATCH`''' Releases ==
1674 22 Dec 08 peter 402
1674 22 Dec 08 peter 403 Versions with same '''`MAJOR.MINOR`''' are perfectly compatible,
1674 22 Dec 08 peter 404 forwards and backwards.
2711 16 Mar 12 peter 405
1674 22 Dec 08 peter 406 This implies that only implementations can be modified in a `PATCH`
1674 22 Dec 08 peter 407 release. You cannot change the API, not even add functions or
1674 22 Dec 08 peter 408 classes because it will break forward compatibility for the previous
1674 22 Dec 08 peter 409 `PATCH` version. A `PATCH` release is a pure bug fix release
1674 22 Dec 08 peter 410
1674 22 Dec 08 peter 411 === Backward Source Compatibility ===
1674 22 Dec 08 peter 412
1674 22 Dec 08 peter 413 Backward Source Compatibility means that an application that could build
1674 22 Dec 08 peter 414 against version `x.y` shall also build without error against
1674 22 Dec 08 peter 415 `x.y+1`. An application that compiled against header files from
1674 22 Dec 08 peter 416 previous `MINOR` version shall also compile without errors against the
1674 22 Dec 08 peter 417 header files of the new version.
1674 22 Dec 08 peter 418
1674 22 Dec 08 peter 419 Specifically this implies:
1674 22 Dec 08 peter 420   - Do not remove any public, protected, or free functions.
1674 22 Dec 08 peter 421   - If you modify a function, its signature must be compatible with
1674 22 Dec 08 peter 422     previous signature, e.g., new parameters with default values may
1721 15 Jan 09 jari 423     be added to signature.
1674 22 Dec 08 peter 424   - Do not remove any class or inheritance for a class.
1674 22 Dec 08 peter 425
1674 22 Dec 08 peter 426 === Backward Binary Compatibility ===
1674 22 Dec 08 peter 427
1674 22 Dec 08 peter 428 Backward Binary Compatibility means that an application that has been
1674 22 Dec 08 peter 429 compiled against version `x.y` can be linked against version
2711 16 Mar 12 peter 430 `x.y+1`.
1674 22 Dec 08 peter 431
1674 22 Dec 08 peter 432 Specifically this implies:
1674 22 Dec 08 peter 433
1674 22 Dec 08 peter 434   - Do not remove or modify any function (except private), not even
1674 22 Dec 08 peter 435     add a parameter with default value because it will make the
1674 22 Dec 08 peter 436     function incompatible with earlier header files.
1674 22 Dec 08 peter 437
1674 22 Dec 08 peter 438   - Do not add, remove, or modify member variables, because that will
1674 22 Dec 08 peter 439     change the allocated size of the class. Therefore, to allow
1674 22 Dec 08 peter 440     modifications of the internal representation, it is preferable to
1674 22 Dec 08 peter 441     hold member variable is a ''pimpl'' that is allocated privately.
1674 22 Dec 08 peter 442     http://developer.gnome.org/doc/guides/programming-guidelines/binary.html
1674 22 Dec 08 peter 443
1674 22 Dec 08 peter 444   - Do not add or change order among virtual functions because it will
1674 22 Dec 08 peter 445     change the layout of the virtual table.
1674 22 Dec 08 peter 446
1674 22 Dec 08 peter 447
1674 22 Dec 08 peter 448
1674 22 Dec 08 peter 449
1262 08 Apr 08 jari 450 ----------------------------------------------------------------------
1262 08 Apr 08 jari 451 {{{
2119 12 Dec 09 peter 452 Copyright (C) 2003 Jari Häkkinen, Peter Johansson
2119 12 Dec 09 peter 453 Copyright (C) 2004 Jari Häkkinen
2119 12 Dec 09 peter 454 Copyright (C) 2006, 2007, 2008, 2009 Jari Häkkinen, Peter Johansson
4359 23 Aug 23 peter 455 Copyright (C) 2011, 2013, 2014, 2015, 2016, 2020, 2021, 2022, 2023 Peter Johansson
1262 08 Apr 08 jari 456
4357 23 Aug 23 peter 457 This file is part of yat library, https://dev.thep.lu.se/yat
1262 08 Apr 08 jari 458
1262 08 Apr 08 jari 459 The yat library is free software; you can redistribute it and/or
1262 08 Apr 08 jari 460 modify it under the terms of the GNU General Public License as
1486 09 Sep 08 jari 461 published by the Free Software Foundation; either version 3 of the
1262 08 Apr 08 jari 462 License, or (at your option) any later version.
1262 08 Apr 08 jari 463
1262 08 Apr 08 jari 464 The yat library is distributed in the hope that it will be useful, but
1262 08 Apr 08 jari 465 WITHOUT ANY WARRANTY; without even the implied warranty of
1262 08 Apr 08 jari 466 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
1262 08 Apr 08 jari 467 General Public License for more details.
1262 08 Apr 08 jari 468
1262 08 Apr 08 jari 469 You should have received a copy of the GNU General Public License
4357 23 Aug 23 peter 470 along with yat. If not, see <https://www.gnu.org/licenses/>.
1262 08 Apr 08 jari 471 }}}

Generated on Sat Oct 14 02:26:03 2023 (UTC) by svndigest 0.11.2pre (dev build 1672)