Changes between Version 10 and Version 11 of Guidelines/MaintenanceGuidelines

Timestamp:

Nov 30, 2008, 4:22:33 PM (14 years ago)

Author:

viboes

Comment:

Separate sections for the three audiences

Guidelines/MaintenanceGuidelines

@@ -182 +182 @@
 
 Another approach consist in preserving the test of the older releases and run them on the current release.
-If the developer needs to change the tests while he evolves his library this is a symptom the interface have been changed and the same way the tests are broken, the user code can also be broken. If the developer forbids himself to modify the test, he will be able to identify breaking changes early on.
-
------------------------------------------------------------------------------------------------
-= Documentation =
-
------------------------------------------------------------------------------------------------
-== Tag Boost library with specific library version [developer] == #version
-Tagging each library release with a version, is the better way to signal possible incompatibilities to the user.
+If the developer needs to change the tests while she/he evolves his library this is a symptom the interface has been changed and the same way the tests are broken, the user code can also be broken. If the developer forbids himself to modify the test, he will be able to identify breaking changes early on.
+
+
+
+
+-----------------------------------------------------------------------------------------------
+= Developer Guidelines =
+
+-----------------------------------------------------------------------------------------------
+== Announce new library features == #announce
+It is a good idea the developer 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. 
+
+-----------------------------------------------------------------------------------------------
+== Make feature request for each feature == #feature_request
+Each modification deprecated/suppressed/modified/new feature should be tracked with a ticket on the Trac system.
+
+-----------------------------------------------------------------------------------------------
+== Document ==
+
+-----------------------------------------------------------------------------------------------
+=== Tag Boost library with specific library version === #version
+Tagging each library release with a version, is the more visible way to signal possible incompatibilities to the user.
 
 For example the thread library could have:
@@ -200 +214 @@
 
 -----------------------------------------------------------------------------------------------
-== Make feature request for each feature [developer, user] == #feature_request
-Each modification deprecated/suppressed/modified/new feature should be tracked with a ticket on the trac system.
-
------------------------------------------------------------------------------------------------
-== Include the tracked tickets on the Release notes [developer] == #release_note
+=== Include the tracked tickets on the Release notes === #release_note
 The release notes should include 
     * the list of all the bug tickets that have been solved
@@ -223 +233 @@
 
 -----------------------------------------------------------------------------------------------
-== List the test cases associated to the trac system tickets [developer] == #ticket_test_case_map
+=== List the test cases associated to the trac system tickets === #ticket_test_case_map
 
 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.   
@@ -230 +240 @@
 ||#XXXX||foo foo foo bar bar bar ||test_foo_bar||
 
-
------------------------------------------------------------------------------------------------
-== List the dependency upon other Boost library [developer] == #dependency
+-----------------------------------------------------------------------------------------------
+=== List the dependency upon other Boost library  === #dependency
 Each library lists the other libraries it depends upon and the minimum 
 version # - as it does with compilers now
@@ -240 +249 @@
 
 -----------------------------------------------------------------------------------------------
-== Document behavior differences between release and debug variants [developer] == #debug
+=== Document behavior differences between release and debug variants === #debug
 Document the differences in behavior that depends on the user defines, in particular the release and debug variants.
 
 
 -----------------------------------------------------------------------------------------------
-== Document behavior differences between toolsets [developer] == #toolsets
+=== Document behavior differences between toolsets === #toolsets
 Document the differences in behavior that depends on the toolsets.
 
 
------------------------------------------------------------------------------------------------
-= Coding =
-
-
------------------------------------------------------------------------------------------------
-== Don't use using directives [user] ==#dont_using
-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. 
-
-Instead of doing
-
-{{{
-#!cpp
-   using namespace boost::interprocess;
-
-   shared_memory_object::remove("MySharedMemory");
-}}}
-
-do
-
-
-{{{
-#!cpp
-    namespace bip = boost::interprocess;
-
-    bip::shared_memory_object::remove("MySharedMemory");
-}}}
-
------------------------------------------------------------------------------------------------
-== Avoid the use of include all features files at the /boost level [user] ==
-Avoid the use of include all features files at the /boost level use instead specific files at boost/lib/file.hpp. Including less code reduce your user code breaking chances.
-
------------------------------------------------------------------------------------------------
-== Be careful with the use of using namespace header files [developer] ==
+== Coding ==
+-----------------------------------------------------------------------------------------------
+=== Be careful with the use of using namespace header files ===
 To import symbols from another namespace the developer can use the using directive '''using namespace''' but limited to the function level. 
 
 -----------------------------------------------------------------------------------------------
-== Don't overload functions that are used by the TR1 (using using)[developer] ==
+=== Don't overload functions that are used by the TR1 ===
 Overloading imported Boost.TR1 functions is equivalent to overload the std functions.
 
 -----------------------------------------------------------------------------------------------
-== Avoid include-all-features files at the /boost level ==
+=== Avoid include-all-features files at the /boost level ===
 Avoid include-all-file at the /boost level including all the functionalities of the library. Provide instead specific files at boost/lib/file.hpp. 
 
@@ -295 +274 @@
 
 -----------------------------------------------------------------------------------------------
-== Don't refine functions overloading without ensuring the same behavior ==
+=== Don't refine functions overloading without ensuring the same behavior ===
 
 If you need document them and warm the user.
 
 -----------------------------------------------------------------------------------------------
-== Avoid the inclusion of symbols at the boost or boost::detail namespace ==
+=== Avoid the inclusion of symbols at the boost or boost::detail namespace ===
 These symbols can collide with symbols of other libraries. 
 
@@ -306 +285 @@
 
 -----------------------------------------------------------------------------------------------
-== Avoid different external behavior depending on the variant release or debug without documenting it ==
+=== Avoid different external behavior depending on the variant release or debug without documenting it ===
 
 Providing different external behavior depending on the variant release or debug could be a surprise for the user. 
@@ -313 +292 @@
 
 -----------------------------------------------------------------------------------------------
-== Avoid to change interfaces [developer] == #dont_change_interfaces
+=== Avoid to change interfaces === #dont_change_interfaces
 When you change the interface, you can see the changes that are needed at the Boost level, but you can not evaluate the cost induced by this change for the users. So before to change an interface deprecate it and let the user enough time to migrate to the new one. 
 
 -----------------------------------------------------------------------------------------------
-=== Don't delete files prematurely [developer] === #dont_delete_files 
+=== Don't delete files prematurely === #dont_delete_files 
 
 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
@@ -333 +312 @@
 
 -----------------------------------------------------------------------------------------------
-=== Don't delete namespaces prematurely [developer] === #dont_delete_namespaces
+=== Don't delete namespaces prematurely  === #dont_delete_namespaces
 Use the using sentence to import from the new namespace to the old one.
 
 -----------------------------------------------------------------------------------------------
-=== Don't delete classes/functions/variables prematurely [developer] === #dont_delete_cpp_symbols
+=== Don't delete classes/functions/variables prematurely  === #dont_delete_cpp_symbols
 Instead of deleting a class or a public/protected function/variable on the next version protect its declaration by any of the DONT_INCLUDE_DEPRECATED macros.
 
@@ -385 +364 @@
 
 -----------------------------------------------------------------------------------------------
-=== Don't modify functions prototypes prematurely [developer] === #dont_modify_prototypes
+=== Don't modify functions prototypes prematurely  === #dont_modify_prototypes
+
+
 Modifying an existing function prototype, if you were deleting it and adding the new one. Instead add the new when possible.
 
@@ -391 +372 @@
 
 -----------------------------------------------------------------------------------------------
-=== Remove the deprecated features on a given release [developer] === #deprecated_removal
+=== Remove the deprecated features on a given release  === #deprecated_removal
 Once the deprecated period is expired the developer sould remove them. 
 
@@ -397 +378 @@
 
 -----------------------------------------------------------------------------------------------
-= Test =
------------------------------------------------------------------------------------------------
-== Test headers [developer] ==
+== Test ==
+=== Test headers  ===
 Steve Watanabe has written a Jamfile that make easier this task. See /boost/libs/units/test/test_header for an example.
 
-=== Include each header files twice [developer] ===
+'''Include each header files twice'''
 The inclusion of a header file  twice ensure that the file is self contained, and that it is well protected
 
@@ -414 +394 @@
 
 -----------------------------------------------------------------------------------------------
-=== Include all header files in both orders [developer] ===
+'''Include all header files in both orders'''
 One more test could be useful, include all the Boost Headers files on both orders
 {{{
@@ -433 +413 @@
 
 -----------------------------------------------------------------------------------------------
-=== link all the header files twice [developer] ===
+'''Link all the header files twice'''
 This ought to catch non-inlined functions and other duplicate definitions
 
 -----------------------------------------------------------------------------------------------
-== Don't forget to test  ==
------------------------------------------------------------------------------------------------
-=== The implicitly generated member functions ===
+=== Don't forget to test  ===
+-----------------------------------------------------------------------------------------------
+==== The implicitly generated member functions ====
 The implicitly generated member functions are part of your interface. 
 
@@ -445 +425 @@
 
 -----------------------------------------------------------------------------------------------
-=== The removed default member functions when you declare a constructor ===
+==== The removed default member functions when you declare a constructor ====
 When you declare a constructor the other default constructors are not generated, so 
 
 -----------------------------------------------------------------------------------------------
-=== The deleted (private) default member functions  ===
+==== The deleted (private) default member functions  ====
 The default member functions =deleted (or declared private) are not part of the interface. 
 
@@ -455 +435 @@
 
 -----------------------------------------------------------------------------------------------
-=== The explicit constructors ===
-
------------------------------------------------------------------------------------------------
-=== The implicit constructors or conversions ===
-
------------------------------------------------------------------------------------------------
-=== The const-ness of variables, function parameters and function return types and functions ===
+==== The explicit constructors ====
+
+-----------------------------------------------------------------------------------------------
+==== The implicit constructors or conversions ====
+
+-----------------------------------------------------------------------------------------------
+==== The const-ness of variables, function parameters and function return types and functions ====
 When a variable, function parameter or function return type is non-const, test that you can modify them.
 
@@ -467 +447 @@
 
 -----------------------------------------------------------------------------------------------
-== Separate the functional test from the unit test (implementation test) ==
+=== Separate the functional test from the unit test (implementation test) ===
 Functional test should take in account only the documented behavior. They can be used as regression test for new re-factorings of the implementation.
 
 Implementation test can be used to test details in the implementation but not as regression tests.
 
------------------------------------------------------------------------------------------------
-== Track regression test on the trac system tickets == #ticket_test_case [user]
+
+-----------------------------------------------------------------------------------------------
+=== Preserve the functional test from the preceding versions === #released_tests
+While doing modifications to the library the developer can find some regressions on some tests of the preceding versions. It seems natural to change them to make the test succeed. This is not a good idea. The failing test is a symptom that the new modifications could break user code. 
+
+If the modification don't pretended to be an interface break, the developer should modify the library until the preceding test cases pass.
+
+If the break is intentional move the tests to the failing tests compile_fail or run_fail on the Jamfile. The developer can copy the test and adapt it to the new interface. It could be a good idea to state explicitly on the test file name on which version they were included.
+
+In order to avoid erroneous modification of the the released tests files the developer could change the rights of the test files. If the developer has no permission to do that on the SVN repository as a last resort he could change the permission in its own SVN copy.
+
+-----------------------------------------------------------------------------------------------
+= User guidelines =
+
+-----------------------------------------------------------------------------------------------
+== Don't use using directives == #dont_using
+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. 
+
+Instead of doing
+
+{{{
+#!cpp
+   using namespace boost::interprocess;
+
+   shared_memory_object::remove("MySharedMemory");
+}}}
+
+do
+
+
+{{{
+#!cpp
+    namespace bip = boost::interprocess;
+
+    bip::shared_memory_object::remove("MySharedMemory");
+}}}
+
+-----------------------------------------------------------------------------------------------
+== Avoid the use of include all features files at the /boost level  ==
+Avoid the use of include all features files at the /boost level use instead specific files at boost/lib/file.hpp. Including less code reduce your user code breaking chances.
+
+-----------------------------------------------------------------------------------------------
+== Help tracking regression test on the Trac system tickets == #ticket_test_case 
 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 and propose a new test case reproducing the bug otherwise [user]
-
------------------------------------------------------------------------------------------------
-== Preserve the functional test from the preceding versions [developer] == #released_tests
-While doing modifications to the library the developer can find some regressions on some tests of the preceding versions. It seems natural to change them to make the test succeed. This is not a good idea. The failing test is a symptom that the new modifications could break user code. 
-
-If the modification don't pretended to be an interface break, the developer should modify the library until the preceding test cases pass.
-
-If the break is intentional move the tests to the failing tests compile_fail or run_fail on the Jamfile. The developer can copy the test and adapt it to the new interface. It could be a good idea to state explicitly on the test file name on which version they were included.
-
-In order to avoid erroneous modification of the the released tests files the developer could change the rights of the test files. If the developer has no permission to do that on the SVN repository as a last resort he could change the permission in its own SVN copy.
-
------------------------------------------------------------------------------------------------
-= Inspections  =
------------------------------------------------------------------------------------------------
-== Announce new library features [developer] == #announce
-It would be great if the developer 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 the code [developer, user, RM] == #review
-Inspect the code to check that the new modifications don't include user code breaks. Tools comparing the contents of the current release and the preceding one could help.
-
------------------------------------------------------------------------------------------------
-== Check that every modification has been documented [developer, user, RM] == #coherent_doc
-Inspect that every modification has been reported on the documentation. Tools comparing the contents of the current release and the preceding one could help.
-
------------------------------------------------------------------------------------------------
-== Check that every modification has been tested [developer, user, RM] == #test_coverage
-Inspect that every modification has been tested. Tools comparing the contents of the current release and the preceding one could help.
-
-
------------------------------------------------------------------------------------------------
-= Developer guidelines =
-||'''Kind'''||'''Guideline'''||
-||Documentation||[wiki:Guidelines/MaintenanceGuidelines#versionTag Boost library with specific library version ]||
-||Documentation||[wiki:Guidelines/MaintenanceGuidelines#feature_request Feature Request for each deprecated/suppressed/modified/new feature]||
-||Documentation||[wiki:Guidelines/MaintenanceGuidelines#release_note Release note and trac system traceability]||
-||Documentation||[wiki:Guidelines/MaintenanceGuidelines#ticket_test_case_map Trac ticket and test cases association]||
-||Code||[wiki:Guidelines/MaintenanceGuidelines#dont_using Don't use using sentences in test programs]||
-||Code||[wiki:Guidelines/MaintenanceGuidelines#dont_delete_files Don't delete files prematurely ]||
-||Code||[wiki:Guidelines/MaintenanceGuidelines#dont_delete_cpp_symbols Don't delete classes/functions/variables prematurely]||
-||Code||[wiki:Guidelines/MaintenanceGuidelines#deprecated_removal Remove the deprecated features on a given release]||
-||Code||[wiki:Guidelines/MaintenanceGuidelines#dont_modify_prototypes Don't modify functions prototypes prematurely]||
-||Test||[wiki:Guidelines/MaintenanceGuidelines#ticket_test_case Regression Test and trac system traceability]||
-||Test||[wiki:Guidelines/MaintenanceGuidelines#released_tests Preserve the test from the preceding versions]||
-||Inspections||[wiki:Guidelines/MaintenanceGuidelines#announce Announce new library features]||
-||Inspections||[wiki:Guidelines/MaintenanceGuidelines#review Inspect the code].||
-||Inspections||[wiki:Guidelines/MaintenanceGuidelines#coherent_doc Check that every modification has been documented]||
-||Inspections||[wiki:Guidelines/MaintenanceGuidelines#test_coverage Check that every modification has been tested]||
-
------------------------------------------------------------------------------------------------
-= User guidelines =
-||'''Kind'''||'''Guideline'''||
-||Documentation||[wiki:Guidelines/MaintenanceGuidelines#feature_request Feature Request for each deprecated/suppressed/modified/new feature]||
-||Code||[wiki:Guidelines/MaintenanceGuidelines#dont_using Don't use using sentences]||
-||Test||[wiki:Guidelines/MaintenanceGuidelines#ticket_test_case Regression Test and trac system traceability]||
-
-||Inspections||[wiki:Guidelines/MaintenanceGuidelines#review Inspect the code].||
-||Inspections||[wiki:Guidelines/MaintenanceGuidelines#coherent_doc Check that every modification has been documented]||
-||Inspections||[wiki:Guidelines/MaintenanceGuidelines#test_coverage Check that every modification has been tested]||
-
------------------------------------------------------------------------------------------------
-= Release manager guidelines =
-||'''Kind'''||'''Guideline'''||
-||Inspections||[wiki:Guidelines/MaintenanceGuidelines#review Inspect the code]||
-||Inspections||[wiki:Guidelines/MaintenanceGuidelines#coherent_doc Check that every modification has been documented]||
-||Inspections||[wiki:Guidelines/MaintenanceGuidelines#test_coverage Check that every modification has been tested]||
-
+State clearly which test cases reproduce the bug it they exists and propose a new test case reproducing the bug otherwise.
+
+-----------------------------------------------------------------------------------------------
+= Boosters guidelines =
+
+-----------------------------------------------------------------------------------------------
+== Inspect the code == #review
+Inspect the code to check that the new modifications don't include user code breaks. 
+Tools comparing the contents of the current release and the preceding one could help.
+Discuss the issue on the ML and do a ticket on the Trac system if there is something to improve.
+
+-----------------------------------------------------------------------------------------------
+== Check that every modification has been documented == #coherent_doc
+Inspect that every modification has been reported on the documentation. 
+Tools comparing the contents of the current release and the preceding one could help.
+Discuss the issue on the ML and do a ticket on the Trac system if there is something to improve.
+
+-----------------------------------------------------------------------------------------------
+== Check that every modification has been tested == #test_coverage
+Inspect that every modification has been tested. 
+Tools comparing the contents of the current release and the preceding one could help.
+Discuss the issue on the ML and do a ticket on the Trac system if there is something to improve.
+