Changes between Version 12 and Version 13 of Guidelines/MaintenanceGuidelines


Ignore:
Timestamp:
Jun 13, 2009, 11:43:46 PM (13 years ago)
Author:
Steven Watanabe
Comment:

partial proof-reading

Legend:

Unmodified
Added
Removed
Modified

  • Guidelines/MaintenanceGuidelines

    v12 v13  
    33'''MAINTENANCE GUIDELINES'''
    44
    5 WARNING: The contents of this page is not the result of a consensus on the Boost community.
    6 
    7 Please be free to improve this page directly or post on the Boost mailing list [mailto:boost-AT-lists.boost.org] and [mailto:boost-users-AT-lists.boost.org].
     5WARNING: The contents of this page are not the result of a consensus of the Boost community.
     6
     7Please feel free to improve this page directly or post on the Boost mailing lists [mailto:boost-AT-lists.boost.org] and [mailto:boost-users-AT-lists.boost.org].
    88
    99-----------------------------------------------------------------------------------------------
    … …  
    1313-----------------------------------------------------------------------------------------------
    1414= Introduction =
    15 Nobody wants to completely disallow changes, we need them.
     15Nobody wants to completely disallow changes. We need them.
    1616
    1717Everybody wants to avoid breaking changes, but sometimes these are also necessary.
    1818
    19 This page describes guidelines that could help the Boost community to get stable libraries and as consequence  '''to avoid user code breaking when the user upgrades to a more recent Boost release'''.
    20 
    21 The difference between '''breaking changes''' and '''bugs''' concerns documentation. A documented modification breaking user code cannot be considered as a bug while the same undocumented modification could be a bug.
     19This page describes guidelines that could help the Boost community to get stable libraries and as a consequence  '''to avoid user code breaking when the user upgrades to a more recent Boost release'''.
     20
     21The difference between '''breaking changes''' and '''bugs''' concerns documentation. A documented modification breaking user code cannot be considered a bug while the same undocumented modification could be a bug.
    2222
    2323-----------------------------------------------------------------------------------------------
    2424== User code breaking cases ==
    25 But why can user code break when the user upgrades to a more recent Boost release.
    26 While this do not pretends to be exhaustive, some examples are given.
    27 
    28  * '''Syntactical''' breaking: detected at compile time
     25Why can user code break when the user upgrades to a more recent Boost release?
     26Here are some examples which demonstrate the most common problems, although they
     27do not pretend to be exhaustive.
     28
     29 * '''Syntactic''' breaking: detected at compile time
    2930It is evident that the removal of files, namespaces, classes, function, variables or macros could break user code. What it is less evident is  that the addition of namespaces, classes, functions, variables at the namespace level or macros can also break user code. Note that
    3031modifications can be considered as deletion+addition.
    … …  
    8384
    8485Adding macros
    85 We shouldn't have user code breaking if we preserve the macro naming rule BOOST_LIBNAME_NAME.
    86 
    87  * '''Semantical''' breaking: detected at runtime
    88 Some times the user code will compile with the upgraded Boost release, but the code will not behave as before. The kind of changes that could lead to this situation must be over documented because the compiler can not help the user to catch the breaking code.
     86Use code should not break if we preserve the macro naming rule BOOST_LIBNAME_NAME.
     87
     88 * '''Semantic''' breaking: detected at runtime
     89Sometimes user code will compile with the upgraded Boost release, but the code will not behave as before.  Changes that can lead to this situation must be documented particularly prominently because the compiler can not help the user to catch the broken code.
    8990
    9091The following code example
    … …  
    114115
    115116
    116 These guidelines are not only addressed to the Boost library developers, but also to the users and the release manager team (RM). Every member of the Boost community has his role to play. Note that the author plays also the role of user of all libraries on which his library depends and on his library depends and on its own library when writing the library tests.
    117 
    118 
    119 The key issue to get stable libraries are:
    120  * Versioning individual Boost.Libraries.
     117These guidelines are not only addressed to Boost library developers, but also to users and the release manager team (RM). Every member of the Boost community has his role to play. Note that the author also plays the role of a user of all the libraries on which his library depends and of his own library when writing the library tests.
     118
     119
     120The key issues to get stable libraries are:
     121 * Versioning individual Boost libraries.
    121122 * Using a deprecation period to give users notice that a breaking change is coming.
    122123 * Documenting and tracking the changes.