Changes between Version 3 and Version 4 of Guidelines/MaintenanceGuidelines

Timestamp:

Nov 23, 2008, 12:14:51 AM (14 years ago)

Author:

viboes

Comment:

--

Guidelines/MaintenanceGuidelines

@@ -1 @@
-Please be free to improve this page directly or post on the Boost mailing list.
+[[PageOutline]]
+
+WARNING: The contents of this page is not the result of a consensus on the Boost community.
+
+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].
 
 = Motivation =
@@ -101 +105 @@
 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.
+For compatibility purposes deprecated features should be included by default. So the library behaves as if the features have not been deprecated. 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
+ * '''BOOST_LIBX_NAME_DECLARED''': states that the deprecated feature name has been declared
+
+
+Deprecated warning are not reported by default, so the library behaves as if the features have not been deprecated. 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:
 
-- Some library tests are likely to also exercise code at the 
-implementation/detail level.
-- Already limited testing resources (on the other hand, interface changes 
-are likely to be detected by running such tests for a single, reasonably 
-compliant, compiler).
-- ...
+ * Some library tests are likely to also exercise code at the implementation/detail level.
+ * Already limited testing resources (on the other hand, interface changes are likely to be detected by running such tests for a single, reasonably compliant, compiler).
+ * ...
 
 In order to have the better we can preserve the test of the older releases and run them on the current release.
@@ -141 +147 @@
 = Versioning individual Boost libraries =
 
-This page do not contains any advice related to individual Boost libraries packaging. There is already a project working on that. But tagging individual Boost libraries with a specific version has already some advantages.
+This page do not contains any advice related to individual Boost libraries packaging. There is already the CMake project working on that. But tagging individual Boost libraries with a specific version has already some advantages.
 
 
@@ -149 +155 @@
 Tagging each library release with a version, is the better way to signal to the user of possible incompatibilities.
 
+For example the thread library could have:
+
+ * '''2.1.0''' Changes since boost 1.35
+
+ * '''2.0.0''' Changes since boost 1.34
+
+ * '''1.0.0''' Initial release on 1.25
+
 == Create a Feature Request ticket for each deprecated/suppressed/modified/new  feature [author, user] ==
 Each modification should be tracked with a ticket on the track system.
-
 
 == Release note and track system traceability [author] ==
@@ -158 +171 @@
     * the list of all deprecated/suppressed/modified/new features with its associated ticket.
 
+For example the thread library could have (#XXXX should be replaced by the trac tickets):
+ * '''2.1.0''' Changes since boost 1.35
+    * #XXXX: New generic lock()  and try_lock()  functions for locking multiple mutexes at once.
+    * #XXXX: Rvalue reference support for move semantics where the compilers supports it.
+    * A few bugs fixed and missing functions added (including the serious win32 condition variable bug).
+        * #XXXX: bug1
+        * ...
+        * #XXXX: bugn
+    * #XXXX: scoped_try_lock types are now backwards-compatible with Boost 1.34.0 and previous releases.
+    * #XXXX: Support for passing function arguments to the thread function by supplying additional arguments to the boost::thread constructor.
+    * #XXXX: Backwards-compatibility overloads added for timed_lock and timed_wait functions to allow use of xtime for timeouts.
+
+
+
 == 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).
+
+== Trac ticket => test cases association [author] ==
+
+Each feature request or bug should have associated at least a test case. A table showing this association will help to check that each feature,bug is has the expected test coverage.   
+
+||Ticket||Synopsis||Test Case||
+||#XXXX||foo foo foo bar bar bar ||test_foo_bar||
+
+
 
 = Codding =
@@ -215 +251 @@
  || 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
+  #define BOOST_LIBX_NAME_DECLARED
   #if defined(BOOST_WARMS_DEPRECEATED) || defined(BOOST_WARMS_DEPRECEATED_ON_1_40)
     #warning "name is deprecated, please use new_name instead"
@@ -231 +267 @@
 }}}
 
-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.
+When the declaration should been included, the author could define a BOOST_LIBX_NAME_DECLARED, which could be used on the class/function/variable definition. E.g.
 
 {{{
@@ -239 +275 @@
 namespace libx {
 
-#if defined(BOOST_LIBX_NAME_DONT_DECLARED)
-#else
+#if defined(BOOST_LIBX_NAME_DECLARED)
   name::name() {
     // as before
@@ -255 +290 @@
 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.
 
-
-
+== Remove the deprecated features on a given release [author] ==
+Once the deprecated period is expired the author should remove them. 
 
 = Test and Inspections =