Maintenance Guidelines wiki page (Revison 8)
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
on Wed Nov 26 2008, "vicente.botet"
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.
That page looks like a great start.
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
IMO you really need separate pages for the three audiences (Developer, User, Release Manager). There's no way users are going to read a page full of developer maintenance guidelines except as a point of interest. Frankly I think you _might_ be being a little too ambitious; I didn't expect anything other than guidelines for developers. If we end up with more than that, it's wonderful, but that's the most urgent need.
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?)
I don't know what that means.
5.1.2 Include each couple of header files in both orders
Testing all possible orderings seems impractical. I could be wrong of course...
B* See if the difference between source and binary compatibility is desirable (ALL)
I don't know what that means.
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?)
Not a bad idea. Spreading the work around is always good. However, a very thorough developer is likely to write tests that exercise much more than users can, and looks at the corner cases. If we end up with redundant tests it will simply soak the testing resources to little benefit.
D* See which configurations (deprecated or not) could be tested by the current test team. (Release Manager Team?)
What does "configuration" mean in this context?
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
Those are great ideas. The more cross-references, the better.
F* See how the dependencies between libraries can be automated
I don't know what an "automated dependency" might be. Can you be more explicit about what you mean to do automatically?
(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.
Hum, that will take me a little while. Will try to get to it in the next few days, but in the US we're beginning the Thanksgiving holiday. That will cut down substantially on peoples' availability (definitely my availability) in the near term.
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
_______________________________________________ Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
-- Dave Abrahams BoostPro Computing http://www.boostpro.com
Hi,
----- Original Message -----
From: "David Abrahams"
on Wed Nov 26 2008, "vicente.botet"
wrote: 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.
That page looks like a great start.
Thanks.
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
IMO you really need separate pages for the three audiences (Developer, User, Release Manager). There's no way users are going to read a page full of developer maintenance guidelines except as a point of interest.
Yes. Robert R. has already signaled the same. I 'll see what I can do.
Frankly I think you _might_ be being a little too ambitious; I didn't expect anything other than guidelines for developers. If we end up with more than that, it's wonderful, but that's the most urgent need.
IMO, the user have an important role to play, they are the more interested in.
Other points I see:
A* See if the Jamfile to test the headers from Steve can be adapted to tests (Steve?)
I don't know what that means.
See in libs/units/test/test_header. I'll add some explanation on the guidelines.
5.1.2 Include each couple of header files in both orders
Testing all possible orderings seems impractical. I could be wrong of course...
I don't know. What seems impractical for you? If it is the time, this can be reduced to the files of a library. But the interesting test is multi-library.
B* See if the difference between source and binary compatibility is desirable (ALL)
I don't know what that means.
Extract from http://apr.apache.org/versioning.html "Source Compatibility We define "source compatible" to mean that an application will continue to build without error, and that the semantics will remain unchanged. Applications that write against a particular version will remain source-compatible against later versions, until the major number changes. However, if an application uses an API which has become available in a particular minor version, it (obviously) will no longer build or operate against previous minor versions. Binary Compatibility We define "binary compatible" to mean that a compiled application can be linked (possibly dynamically) against the library and continue to function properly. Similar to source compatibility, an application that has been compiled against a particular version will continue to be linkable against later versions (unless the major number changes). It is possible that an application will not be able to successfully link against a previous minor version."
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?)
Not a bad idea. Spreading the work around is always good. However, a very thorough developer is likely to write tests that exercise much more than users can, and looks at the corner cases. If we end up with redundant tests it will simply soak the testing resources to little benefit.
You are right. How I see that. If I were to start the functional test of a library, I will start from the current unit test of the library, and remove the parts concerning the implementation details. Test that are double, i.e. unit tests that are completly functional, the developer could remove them from its unit test list if he want. Otherwise, functional tests (regression tests) could be run in alternation with unit tests.
D* See which configurations (deprecated or not) could be tested by the current test team. (Release Manager Team?)
What does "configuration" mean in this context?
If we introduce deprecation, we could need to run the tests with and without deprecation, as we do now with variant release and debug.
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
Those are great ideas. The more cross-references, the better.
Is someone interested to see how this coud be done?
F* See how the dependencies between libraries can be automated
I don't know what an "automated dependency" might be. Can you be more explicit about what you mean to do automatically?
I've see that the CMAKE team has do something to get the dependencies between the Boost.Libraries. If we add the Boost libraries versions we will have automaticaly what we are locking for.
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.
Hum, that will take me a little while. Will try to get to it in the next few days, but in the US we're beginning the Thanksgiving holiday. That will cut down substantially on peoples' availability (definitely my availability) in the near term.
Take the time you need. Thanks for your comments and have a good Thanksgiving dinner, Vicente
participants (3)
-
David Abrahams -
Vicente Botet -
vicente.botet