Re: [boost] Maintenance Guidelines wiki page (Revison 8)

Subject: Re: [boost] Maintenance Guidelines wiki page (Revison 8)
From: David Abrahams (dave_at_[hidden])
Date: 2008-11-26 11:42:10

on Wed Nov 26 2008, "vicente.botet" <vicente.botet-AT-wanadoo.fr> 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.

> 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