Changes between Version 1 and Version 2 of Guidelines/MaintenanceGuidelines


Ignore:
Timestamp:
Nov 22, 2008, 7:20:22 PM (14 years ago)
Author:
Steven Watanabe
Comment:

Minor proof-reading

Legend:

Unmodified
Added
Removed
Modified

  • Guidelines/MaintenanceGuidelines

    v1 v2  
    1010This page describes guidelines that could be followed by the Boost community '''to avoid user code breaking when the user upgrades to a more recent Boost release'''.
    1111
    12 The difference between '''breaking changes''' and '''bugs''' concerns documentation. A documented modification breaking user code can not be considered as a bug while the same non documented modification could be a bug.
    13 
    14 The key issue are:
     12The 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.
     13
     14The key issues are:
    1515 * Documenting and tracking the changes.
    1616 * Avoiding completely silent breakage by a deep inspection of code changes.
    … …  
    1919 * Versioning individual Boost.Libraries.
    2020
    21 These guidelines are related mainly to how to document changes. There are also some guidelines that can be followed to detect breaking changes either by test or by inspections. And of course this pages contains also some guidelines related to the code itself.
    22 
    23 But, why user code can break when upgrading Boost?
     21These guidelines are related mainly to how to document changes. There are also some guidelines that can be followed to detect breaking changes either by test or by inspections. And of course this pages also contains some guidelines related to the code itself.
     22
     23But, why can user code break when upgrading Boost?
    2424
    2525 * '''Syntactical''' breaking: detected at compile time
    26 It is evident that the removal of files, namespaces, classes, function, variables or macros could break user code. What it is less evident is the addition namespaces, classes, function, variables at the namespace level or macros can also break user code. Note that modifications can be considered as deletion+addition.
     26It 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, function, variables at the namespace level or macros can also break user code. Note that modifications can be considered as deletion+addition.
    2727
    2828The following user code example
    … …  
    7979
    8080Adding macros
    81 We should don't have user code breaking until we preserve the macro naming rule BOOST_LIBNAME_NAME.
     81We shouldn't have user code breaking if we preserve the macro naming rule BOOST_LIBNAME_NAME.
    8282
    8383 * '''Semantical''' breaking: detected at runtime
    84 Some times the user code will compile with the upgraded Boost release, but the code will not behaves as before. This 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.
     84Some 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.
    8585
    8686''Add an example on overloading''
    8787
    88 These guidelines are not only addressed to the Boost library authors, but also to the users and the release manager team (RM). Every member of the Boost community has its role to play. Note that the author plays also the role of user of all libraries on which its library depends and on its own library when writing the library tests.
     88These guidelines are not only addressed to the Boost library authors, 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 own library when writing the library tests.
    8989
    9090
    … …  
    116116
    117117== Tag Boost library with specific library version [author] ==
    118 Tagging each library release with a version, is the better way to signal to the user of possible incompatibilities.
     118Tagging each library release with a version, is the better way to signal possible incompatibilities to the user.
    119119
    120120== Create a Feature Request ticket for each deprecated/suppressed/modified/new  feature [author, user] ==
    121 Each modification should be tracked with a ticket on the track system.
    122 
    123 
    124 == Release note and track system traceability [author] ==
    125 The release note should include
     121Each modification should be tracked with a ticket on the trac system.
     122
     123
     124== Release notes and trac system traceability [author] ==
     125The release notes should include
    126126    * the list of all the bug tickets that have been solved
    127     * the list of all deprecated/suppressed/modified/new features with its associated ticket.
     127    * the list of all deprecated/suppressed/modified/new features with their associated tickets.
    128128
    129129== Include a diff file showing the modification respect to the previous release [author, RM] ==
    130130This file is the explicit report of all the changes in the library. It could be used by the Boost community to inspect that every change has been correctly documented (see inspections bellow).
    131131
    132 = Codding =
    133 == Do not use using sentences [user] ==
    134 As seen before the use of using sentences in user code is one of the source of user code breaking, so it will be safer to use instead namespace synonyms and prefix each symbol with them.
     132= Coding =
     133== Do not use using directives [user] ==
     134As seen before, using directives in user code is one of the sources of user code breaking, so it will be safer to use namespace synonyms instead and prefix each symbol with them.
    135135
    136136Instead of doing
    … …  
    155155
    156156== Do not delete files prematurely [author] ==
    157 Before deleting a file "file.hpp" deprecate it and let the user modify its code during some versions (e.g. until 1_40). Replace it by
     157Before deleting a file, "file.hpp", deprecate it and let the user modify his code during some versions (e.g. until 1_40). Replace it by
    158158
    159159{{{
    … …  
    161161// boost/old_header_file.hpp
    162162// include whatever file is needed to preserve the old file contents
    163 #if defined(BOOST_WARMS_DEPRECEATED) || defined(BOOST_WARMS_DEPRECEATED_ON_1_40)
     163#if defined(BOOST_WARNS_DEPRECATED) || defined(BOOST_WARNS_DEPRECATED_ON_1_40)
    164164#warning "boost/old_header_file.hpp is deprecated, please include boost/new_header_file.hpp instead
    165165#endif
    166166}}}
    167167
    168 It will be up to the user to define the macros BOOST_WARMS_DEPRECEATED and BOOST_WARMS_DEPRECEATED_ON_1_40 when the user wants to be warmed for deprecated features on Boost or on the Boost version 1.40 respectively.
     168It will be up to the user to define the macros BOOST_WARNS_DEPRECATED and BOOST_WARNS_DEPRCEATED_ON_1_40 when the user wants to be warmed for deprecated features on Boost or on the Boost version 1.40 respectively.
    169169
    170170== Do not delete namespaces prematurely [author] ==
    … …  
    172172
    173173== Do not delete classes/functions/variables prematurely [author] ==
    174 Instead of delete a class on the next version protect its definition by BOOST_DONT_INCLUDE_DEPRECATED or BOOST_LIBX_DONT_INCLUDE_DEPRECATED.
     174Instead of deleting a class on the next version protect its definition by BOOST_DONT_INCLUDE_DEPRECATED or BOOST_LIBX_DONT_INCLUDE_DEPRECATED.
    175175
    176176{{{
    … …  
    198198
    199199== Do not modify functions prototype prematurely [author] ==
    200 Instead of modifying an existing function prototype, do as you were deleted it and added the new one. As both prototypes should cohabit during some releases, check if this overloading could cause user code breaks.
     200Instead of modifying an existing function prototype, do as if you were deleting it and adding the new one. As both prototypes should coexist for some releases, check if this overloading could cause user code breaks.
    201201
    202202
    … …  
    205205= Test and Inspections =
    206206
    207 == Regression Test and track system traceability ==
     207== Regression Test and trac system traceability ==
    208208A bug ticket must be associated to a test case, either the test case exists already and there is a regression for some toolset, or a new toolset is considered, or a new test case is needed to check the bug is there (problem reproducible) and the modification solve the problem.
    209209 * State clearly which test cases prove the bug it it exists [user]
    … …  
    211211
    212212== Preserve the test from the preceding versions as much as possible ==
    213 The test from the preceding versions should not be changed when the author modifies its library. These  not changed tests are a probe of compatibility with the preceding version. When these test must be changed they indicate a breaking user code issue. So instead of changing them add new ones stating explicitly on which version they were included and remove these tests from the Jamfile.
    214 
     213The tests from the preceding versions should not be changed when the author modifies its library. These unchanged tests are a probe of compatibility with the preceding version. When these tests must be changed they indicate a breaking user code issue. So instead of changing them, add new ones stating explicitly on which version they were included and remove these tests from the Jamfile.
     214