Context Navigation

Changes between Version 2 and Version 3 of Guidelines/MaintenanceGuidelines

Timestamp:: Nov 22, 2008, 9:46:21 PM (14 years ago)
Author:: viboes
Comment:: --

Legend:

: Unmodified
: Added
: Removed
: Modified

Guidelines/MaintenanceGuidelines

-              v2
+              v3
 This 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'''.
 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.
 The key issues are:
+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.
+The key issue are:
  * Documenting and tracking the changes.
  * Avoiding completely silent breakage by a deep inspection of code changes.
 …
  * Versioning individual Boost.Libraries.
 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 also contains some guidelines related to the code itself.
 But, why can user code break when upgrading Boost?
+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.
+But, why user code can break when upgrading Boost?
  * '''Syntactical''' breaking: detected at compile time
 It 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.
+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.
 The following user code example
 …
 Adding macros
 We shouldn't have user code breaking if we preserve the macro naming rule BOOST_LIBNAME_NAME.
+We should don't have user code breaking until we preserve the macro naming rule BOOST_LIBNAME_NAME.
  * '''Semantical''' breaking: detected at runtime
 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.
+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.
 ''Add an example on overloading''
 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 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.
+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.
 = Deprecating features =
+''To be added''
+C++ do not have deprecated attributes, so the author needs to emulate a warning when some deprecated feature is used.
+The #warning directive can be used to this purpose
+{{{
+  #warning "name is deprecated, please use new_name instead"
+}}}
+The main problem is that this warning will appear independently of whether the user code uses or not the deprecated feature. In order to palliate to this the inclusion of the deprecated feature could be accessible conditionally and only when included the warning will be reported or not.
+For compatibility purposes deprecated features should be included by default.
+If a user don't want to include a deprecated feature he/she can define one of the following macros:
+'''BOOST_DONT_INCLUDE_DEPRECATED''': don't include any deprecated feature.
+'''BOOST_DONT_INCLUDE_DEPRECATED_ON_X_Y''': don't include any deprecated feature to be removed on version X.Y.
+'''BOOST_LIBX_DONT_INCLUDE_DEPRECATED''': don't include any deprecated feature for library Boost.LIBX.
+'''BOOST_LIBX_DONT_INCLUDE_DEPRECATED_ON_X_Y''': don't include any deprecated feature for libarary Boost.LIBX  to be removed on version X.Y.
+'''BOOST_LIBX_DONT_INCLUDE_DEPRECATED_NAME''': don't include the deprecated feature name.
+Once one of this macros is defined the author can define another macro to make easier the work.
+'''BOOST_LIBX_NAME_DONT_DECLARED''': states that the deprecated feature name has not been declared
+Deprecated warning are not reported by default. If the user wants this deprecated warnings to appear he/she can define one of the macros:
+'''BOOST_WARMS_DEPRECEATED''': warms on all deprecated features
+'''BOOST_WARMS_DEPRECEATED_ON_X_Y''': warms on all deprecated features to be removed on version X.Y
+[wiki:Guidelines/MaintenanceGuidelines#delete_files See the examples below].
 = Cross version testing =
 Running the regression tests from the _previous_ major release against the current release is a way to automatically detect and flag interface/behavioral changes. Sure, there are many potential problems with such an approach:
 …
 == Tag Boost library with specific library version [author] ==
 Tagging each library release with a version, is the better way to signal possible incompatibilities to the user.
+Tagging each library release with a version, is the better way to signal to the user of possible incompatibilities.
 == Create a Feature Request ticket for each deprecated/suppressed/modified/new  feature [author, user] ==
 Each modification should be tracked with a ticket on the trac system.
 == Release notes and trac system traceability [author] ==
 The release notes should include
+Each modification should be tracked with a ticket on the track system.
+== Release note and track system traceability [author] ==
+The release note should include
     * the list of all the bug tickets that have been solved
     * the list of all deprecated/suppressed/modified/new features with their associated tickets.
+    * the list of all deprecated/suppressed/modified/new features with its associated ticket.
 == Include a diff file showing the modification respect to the previous release [author, RM] ==
 This 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).
 = Coding =
 == Do not use using directives [user] ==
 As 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.
+= Codding =
+== Do not use using sentences [user] ==
+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.
 Instead of doing
 …
+== Do not delete files prematurely [author] ==
+Before 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
+== Do not delete files prematurely [author] == #delete_files
+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
 {{{
 …
 // boost/old_header_file.hpp
 // include whatever file is needed to preserve the old file contents
 #if defined(BOOST_WARNS_DEPRECATED) || defined(BOOST_WARNS_DEPRECATED_ON_1_40)
+#if defined(BOOST_WARMS_DEPRECEATED) || defined(BOOST_WARMS_DEPRECEATED_ON_1_40)
 #warning "boost/old_header_file.hpp is deprecated, please include boost/new_header_file.hpp instead
 #endif
 }}}
 It 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.
+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.
 == Do not delete namespaces prematurely [author] ==
 Use the using sentence to import from the new namespace to the old one.
 == Do not delete classes/functions/variables prematurely [author] ==
 Instead of deleting a class on the next version protect its definition by BOOST_DONT_INCLUDE_DEPRECATED or BOOST_LIBX_DONT_INCLUDE_DEPRECATED.
+== Do not delete classes/functions/variables prematurely [author] ==  #delete_cpp_symbols
+Instead of delete a class or a public/protected function/variable on the next version protect its declaration by any of the DONT_INCLUDE_DEPRECATED macros.
 {{{
 …
 namespace libx {
+#if defined(BOOST_DONT_INCLUDE_DEPRECATED) || defined(BOOST_DONT_INCLUDE_DEPRECATED_ON_1_41) || defined(BOOST_LIBX_DONT_INCLUDE_DEPRECATED)  || defined(BOOST_LIBX_DONT_INCLUDE_DEPRECATED_ON_1_41) || defined(BOOST_LIBX_DONT_INCLUDE_DEPRECATED_NAME)
+  #define BOOST_LIBX_NAME_DONT_DEFINED
+#if defined(BOOST_DONT_INCLUDE_DEPRECATED) || defined(BOOST_DONT_INCLUDE_DEPRECATED_ON_1_41) \
+ || defined(BOOST_LIBX_DONT_INCLUDE_DEPRECATED)  || defined(BOOST_LIBX_DONT_INCLUDE_DEPRECATED_ON_1_41) \
+ || defined(BOOST_LIBX_DONT_INCLUDE_DEPRECATED_NAME)
+  #define BOOST_LIBX_NAME_DONT_DECLARED
 #else
+  #warning "name is deprecated, please use new_name instead"
+  #if defined(BOOST_WARMS_DEPRECEATED) || defined(BOOST_WARMS_DEPRECEATED_ON_1_40)
+    #warning "name is deprecated, please use new_name instead"
+  #endif
   class name {
+    name::name();
     // as before
   };
 …
+}
+}
+}}}
+The same applies to functions and variables.
+== Do not modify functions prototype prematurely [author] ==
+Instead 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.
+}}}
+When the declaration should not been included, the author could define a BOOST_LIBX_NAME_DONT_DECLARED, which could be used on the class/function/variable definition. E.g.
+{{{
+#!cpp
+// boost/libx/header_file.cpp
+namespace boost {
+namespace libx {
+#if defined(BOOST_LIBX_NAME_DONT_DECLARED)
+#else
+  name::name() {
+    // as before
+  }
+  // as before
+#endif
+}
+}
+}}}
+== Do not modify functions prototypes prematurely [author] ==
+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.
 …
 = Test and Inspections =
+== Regression Test and trac system traceability ==
+A 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.
+ * State clearly which test cases prove the bug it it exists [user]
+ * Propose a new test case reproducing the bug [user]
+== Preserve the test from the preceding versions as much as possible ==
+The 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.
+== Regression Test and track system traceability ==
+A bug ticket should be associated to one or several test cases, either the test cases exists already and we are in face of a regression for some toolset, or a new toolset is considered, or a new test case is needed to reproduce the bug and the modification solve the problem.
+ * State clearly which test cases reproduce the bug it they exists [user]
+ * Propose a new test case reproducing the bug otherwise [user]
+== Preserve the test from the preceding versions as much as possible [author] ==
+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. Old tests that should fail can be moved to the compile_fail or run_fail tests on the Jamfile.
+= Release Management =
+== Announce new features on a library [author] ==
+It would be great if the author announce to the Boost mailing lists the new features just before committing in the release branch. This will let the time to the Boost community to inspect the modifications introduced.
+== Inspect announced modifications match the real ones [author, user, RM] ==
+The use of the diff file will help to inspect that the modifications introduced have been correctly included on the documentation and a good test coverage has been done. This will result in a non official mini-review of the library.