[boost] Maintenance Guidelines wiki page (Revison 8)

Subject: [boost] Maintenance Guidelines wiki page (Revison 8)
From: vicente.botet (vicente.botet_at_[hidden])
Date: 2008-11-26 09:19:35

Hi,

I have updated the Maintenance Guidelines wiki page. 

I have take in account the minor proof-reading modifications from Steve Watanave which I have overridden by error (thanks Steve!),and added a lot of thinks, maybe too much :)

Please read this mail completely before jumping to the page. 
This page need to be completed and reworked. Please be free to add new sections to the page or improve the current ones directly or post your comments or suggestions to this list.

Here it is the table of contents.

[C]   1. Motivation
[C]   2. Introduction
[C]         1. User code breaking cases
[I]         2. Versioning individual Boost libraries
[O]         3. Deprecating features
[I]         4. Cross version testing
[C]   3. Documentation
[O]         1. Tag Boost library with specific library version [developer]
[O]         2. Make feature request for each feature [developer, user]
[I]         3. Include the tracked tickets on the Release notes [developer]
[I]         4. List the test cases associated to the trac system tickets [developer]
[I]         5. List the dependency upon other Boost library [developer]
[O]         6. Document behavior differences between release and debug variants 
[O]         7. Document behavior differences between toolsets [developer]
[C]   4. Coding
[O]         1. Don't use using directives [user]
[C]         2. Avoid the use of include all features files at the /boost level [user]
[C]         3. Be careful with the use of using namespace header files [developer]
[C]         4. Don't overload functions that are used by the TR1 (using using)[developer]
[O]         5. Avoid include-all-features files at the /boost level
[C]         6. Don't refine functions overloading without ensuring the same behavior
[C]         7. Avoid the inclusion of symbols at the boost or boost::detail namespace
[C]         8. Avoid different external behavior depending on the variant release or debug
[O]         9. Avoid to change interfaces [developer]
[O]               1. Don't delete files prematurely [developer]
[O]               2. Don't delete namespaces prematurely [developer]
[O]               3. Don't delete classes/functions/variables prematurely [developer]
[O]               4. Don't modify functions prototypes prematurely [developer]
[O]               5. Remove the deprecated features on a given release [developer]
[C]   5. Test
[C]         1. Test headers [developer]
[C]               1. Include each header files twice [developer]
[I]               2. include each couple of header files in both orders
[C]               3. Include all header files
[C]               4. link all the header files twice
[C]         2. Don't forget to test
[C]               1. The implicitly generated member functions
[C]               2. The removed default member functions when you declare a constructor
[C]               3. The deleted (private) default member functions
[C]               4. The explicit constructors
[C]               5. The implicit constructors or conversions
[C]               6. The const-ness of variables, function parameters and function return types 
[I]         3. Separate the functional test from the unit test (implementation test)
[I]         4. Track regression test on the trac system tickets
[I]         5. Preserve the functional test from the preceding versions [developer]
[C]   6. Inspections
[O]         1. Announce new library features [developer]
[C]         2. Inspect the code [developer, user, RM]
[C]         3. Check that every modification has been documented [developer, user, RM]
[C]         4. Check that every modification has been tested [developer, user, RM]
[U]   7. Developer guidelines
[U]   8. User guidelines
[U]   9. Release manager guidelines

Tasks I plan to do:
1* Add the motivation
2* Add other examples of user code break in 2.1
3* Update the Developer, User and Release manager guidelines cross reference (7,8,9)
4* Separate on 4 pages. Main, Documentation, Coding, Test and Inspections
5* Complete incomplete guidelines [C] and improve some of them [I]

Note that some guidelines applied to the developer library could be done by other people that would need SVN writtig permission. In particular the Functional Test and some documentation reports. (See below points C and E)

Other points I see:

A* See if the Jamfile to test the headers from Steve can be adapted to tests (Steve?)
5.1.2 Include each couple of header files in both orders

B* See if the difference between source and binary compatibility is desirable (ALL)

C* See if the functional test can be written by a team of interested users to don't overload the developers. These tests could in addition include multi-library tests and be stored in a directory independent from the developers one (Interested users?)

D* See which configurations (deprecated or not) could be tested by the current test team. (Release Manager Team?)

E* See how the following points can be automated and where this information can be included in the documentation. A separated page make possible that this task could be done by other people than the developer. (Some one knowing the Track system?)
         3.3. Include the tracked tickets on the Release notes
         3.4. List the test cases associated to the trac system tickets

F* See how the dependencies between libraries can be automated (Release Manager Team?, CMAKE project?)
         3.5. List the dependency upon other Boost library

In order to know if I'm going on the right direction, I would like the interested people reply to this post stating for each section, if it is OK[O], must be completed[C]/improved [I], must be updated [U], must be removed [R] and of course any idea is welcome.

You can access it directly at
"https://svn.boost.org/trac/boost/wiki/Guidelines/MaintenanceGuidelines"
or at "https://svn.boost.org/trac/boost/wiki" >Guidelines >Maintenance Guidelines 

Best regards,
Vicente