- Motivation
- Introduction
-
Developer Guidelines
- Announce new library features
- Make feature request for each feature
-
Document
- Tag Boost library with specific library version
- Include the tracked tickets on the Release notes
- List the test cases associated to the trac system tickets
- List the dependency upon other Boost library
- Document behavior differences between release and debug variants
- Document behavior differences between toolsets
-
Coding
- Be careful with the use of using namespace header files
- Don't overload functions that are used by the TR1
- Avoid include-all-features files at the /boost level
- Don't refine functions overloading without ensuring the same behavior
- Avoid the inclusion of symbols at the boost or boost::detail namespace
- Avoid different external behavior depending on the variant release or …
- Avoid to change interfaces
- Don't delete files prematurely
- Don't delete namespaces prematurely
- Don't delete classes/functions/variables prematurely
- Don't modify functions prototypes prematurely
- Remove the deprecated features on a given release
- Test
- User guidelines
- Boosters guidelines
MAINTENANCE GUIDELINES
WARNING: The contents of this page are not the result of a consensus of the Boost community.
Please feel free to improve this page directly or post on the Boost mailing lists boost-AT-lists.boost.org and boost-users-AT-lists.boost.org.
Motivation
To be added
Introduction
Nobody wants to completely disallow changes. We need them.
Everybody wants to avoid breaking changes, but sometimes these are also necessary.
This 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.
The 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.
User code breaking cases
Why can user code break when the user upgrades to a more recent Boost release? Here are some examples which demonstrate the most common problems, although they do not pretend to be exhaustive.
- Syntactic 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, functions, variables at the namespace level or macros can also break user code. Note that modifications can be considered as deletion+addition.
The following code example
#include <boost/file.hpp> using namespace boost; class foo { // ... }; void bar() { // ... }
breaks when
- we add the namespace foo in file.hpp
// boost/file.hpp namespace boost { namespace foo { // ... } }
- we add the class foo in file.hpp
// boost/file.hpp namespace boost { class foo { // ... }; }
- we add the function bar in file.hpp
// boost/file.hpp namespace boost { void bar() { // ... } }
Adding macros Use code should not break if we preserve the macro naming rule BOOST_LIBNAME_NAME.
- Semantic breaking: detected at runtime
Sometimes 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.
The following code example
#include <boost/file.hpp> using namespace boost; void bar(int i) { // ... }
breaks when
- we add the function bar in one of the files included by the user program
// boost/file.hpp namespace boost { void bar(char c) { // ... } }
These 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.
The key issues to get stable libraries are:
- Versioning individual Boost libraries.
- Using a deprecation period to give users notice that a breaking change is coming.
- Documenting and tracking the changes.
- Avoiding completely silent breakage by a deep inspection of code changes and running the regression tests (functional tests) from the _previous_ major release against the current release as a way to automatically detect and flag interface/behavioral changes.
These guidelines are related mainly to how to document changes, how breaking changes can be detected either by test or by inspections, and of course guidelines related to the code itself.
Versioning individual Boost libraries
This page don't 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 MAJOR.MINOR.PATCH has already the informational advantage.
Versions are denoted using a standard triplet of integers: MAJOR.MINOR.PATCH. The basic intent is that MAJOR versions are incompatible, large-scale upgrades of the API. MINOR versions retain source and binary compatibility with older minor versions, and changes in the PATCH level are perfectly compatible, forwards and backwards.
Deprecating features
C++ don't have deprecated attributes, so the developer 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. So the library behaves as if the features were 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 developer can define another macro to make easier the work.
- BOOST_LIBX_NAME_DECLARED: states that the deprecated feature name has been declared
Deprecated warnings are not reported by default, so the library behaves as if the features were not been deprecated. If the user wants this deprecated warnings to appear he/she can define one of the macros:
- BOOST_WARNS_DEPRECATED: warms on all deprecated features
- BOOST_WARNS_DEPRECATED_ON_X_Y: warms on all deprecated features to be removed on version X.Y
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).
- ...
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 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
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
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
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:
- 2.1.0 Changes since boost 1.35
- 2.0.0 Changes since boost 1.34
- 1.0.0 Initial release on 1.25
Include the tracked tickets on the Release notes
The release notes 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.
URL: https://svn.boost.org/svn/boost/website/public_html/beta/feed/history
There will be a file in that directory named boost_n_nn_n.qbk, where n_nn_n is the release number. Edit the [section Updated Libraries] portion of that file to add a description of changes to your library. For example:
* [phrase library..[@/libs/interprocess/index.html Interprocess]:] * Updated documentation to show rvalue-references functions instead of emulation functions. * More non-copyable classes are now movable. * Move-constructor and assignments now leave moved object in default-constructed state instead of just swapping contents. * Several bug fixes: *[@https://svn.boost.org/trac/boost/ticket/2391 #2391] interprocess_recursive_mutex doesn't work interprocess, *[@https://svn.boost.org/trac/boost/ticket/2431 #2431] A Few More Corrections for the Interprocess Documentation, *[@https://svn.boost.org/trac/boost/ticket/1390 #1390] managed shared memory failing completely under OSX, *[@https://svn.boost.org/trac/boost/ticket/2570 #2570] boost::interprocess::message_queue::timed_send and timed_receive bug, *[@https://svn.boost.org/trac/boost/ticket/2528 #2528] Missing include of iostream in interprocess tests.
or
* [phrase library..[@/libs/functional/hash/index.html Hash]:]
* `boost/functional/detail/container_fwd.hpp` has been moved to
`boost/detail/container_fwd.hpp`.
The current location is deprecated.
* For more detail, see the
[@/doc/html/hash/changes.html#hash.changes.boost_1_38_0
library changelog].
List the test cases associated to the trac system tickets
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 |
List the dependency upon other Boost library
Each library lists the other libraries it depends upon and the minimum version # - as it does with compilers now
| Library | Version # | Build & Link | Comment |
| Thread | 2.1.0 | link | generic lock() |
Document behavior differences between release and debug variants
Document the differences in behavior that depends on the user defines, in particular the release and debug variants.
Document behavior differences between toolsets
Document the differences in behavior that depends on the toolsets.
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
Overloading imported Boost.TR1 functions is equivalent to overload the std functions.
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.
If you provide such files ensure that your tests works when you include them directly or include the specific ones.
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
These symbols can collide with symbols of other libraries.
Announce them on the Boost mailing list when you think this is the best choice.
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.
If you need them document it and warm the user.
Avoid to 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
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
// 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) #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_DEPRECATED_ON_1_40 when the user wants to be warmed for deprecated features on Boost or on the Boost version 1.40 respectively.
Don't delete namespaces prematurely
Use the using sentence to import from the new namespace to the old one.
Don't delete classes/functions/variables prematurely
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.
// boost/libx/header_file.hpp namespace boost { 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) #else #define BOOST_LIBX_NAME_DECLARED #if defined(BOOST_WARNS_DEPRECATED) || defined(BOOST_WARNS_DEPRECATED_ON_1_40) #warning "name is deprecated, please use new_name instead" #endif class name { name::name(); // as before }; #endif } }
When the declaration should been included, the developer could define a BOOST_LIBX_NAME_DECLARED, which could be used on the class/function/variable definition. E.g.
// boost/libx/header_file.cpp namespace boost { namespace libx { #if defined(BOOST_LIBX_NAME_DECLARED) name::name() { // as before } // as before #endif } }
Don't modify functions prototypes prematurely
Modifying an existing function prototype, if you were deleting it and adding the new one. Instead add the new when possible.
As both prototypes should coexist for some releases, check if this overloading could cause user code breaks.
Remove the deprecated features on a given release
Once the deprecated period is expired the developer sould remove them.
Don't forget to change the major version number.
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 The inclusion of a header file twice ensure that the file is self contained, and that it is well protected
#include <file.hpp> #include <file.hpp> int main() {return 0;}
Include all header files in both orders One more test could be useful, include all the Boost Headers files on both orders
#include <file1.hpp> #include <file2.hpp> ... #include <filen.hpp>
#include <filen.hpp> ... #include <file2.hpp> #include <file1.hpp>
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
The implicitly generated member functions are part of your interface.
Add some simple tests that prove its correct behavior.
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 default member functions =deleted (or declared private) are not part of the interface.
Add some simple tests that prove the compilation fails when you use them.
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.
When a variable, function parameter or function return type is const, test that you try to modify them the compilation fails.
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.
Preserve the functional test from the preceding versions
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
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
using namespace boost::interprocess; shared_memory_object::remove("MySharedMemory");
do
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
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.
Boosters guidelines
Inspect the code
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
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
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.
Guidelines on compiler warnings have been moved to a new section.
