Re: [boost] General advice needed for new maintainers.

Subject: Re: [boost] General advice needed for new maintainers.
From: Andrey Semashev (andrey.semashev_at_[hidden])
Date: 2014-02-14 03:08:02

The following is mostly my understanding and my personal workflow.

On Thursday 13 February 2014 20:05:37 Fletcher, John P wrote:
> I have been maintaining Boost Phoenix for several weeks.
> 
> To start with I was mainly attempting to fix as many bugs as possible and
> also sorting out things like missing copright and licence.  I am now up to
> the more difficult bugs which take longer to fix.
> 
> I also need some more information and some actions which I cannot take
> myself.  I have asked about a number of these on this list and I am lacking
> answers to a good many of them, so I am going to summarise them here.
> 
> I think it would be a great help to people undertaking maintenance for the
> first time, without having first been an originator of a library if some
> guidelines were in a document.
> 
> 1. General guidelines on the responsibilities of a maintainer and who is
> responsible for the elements outside the developer's control.  In
> particular, what happens when there is a release of boost?

There aren't any particular actions required from the maintainer, release 
managers do all the packaging and other stuff. However, you are encouraged to 
monitor tests and hotfix bugs that get reported during the release 
preparation, as this ensures the release quality.

In the SVN age there was a protocol of merging the fixes to the release branch 
during this stage, but I believe this is no longer the case with git.

In other aspects of the workflow you either contact the superproject or other 
library maintainers through this list or pull requests. You can also create 
Trac tickets for other libraries if you feel that's more appropriate.

> 2. General guidelines on the responsibilities for bugs and who to contact if
> a bug seems to be due to a different library.

As the library maintainer, you're responsible for your library. If a ticket 
gets reported against it, you have to investigate it first. If it turns out to 
be caused by another library, you can contact that library maintainers through 
this list (or specialized one, if there is one) and reassign the ticket with a 
descriptive comment. You can also add yourself to the CC list in the ticket to 
receive updates on it.

Of course, the library maintainers would appreciate if you create a reduced 
code sample to reproduce the problem so that they don't have to dig inside 
your library to figure out the problematic case. You can attach the test case 
to the ticket before passing it.

> 3. Guidelines on the use of trac and how to get given the ability to record
> bugs as now fixed.

There aren't any official requirements to my knowledge. I typically don't 
close the ticket until the problem is solved in release (master) branch. When 
the problem is fixed in trunk (develop) I would typically post a comment with 
the reference to the commit.

> 4. Where is the archive for boost-bugs?  It would be useful to look at past
> fixes to find out what has gone on.  Someone suggested searching but I
> cannot search until I know what is there.

I don't think there is one in the public access. You can find closed Trac 
tickets by filtering and read them one by one, if you like.

> 5. A list of who is maintaining what.

libs/maintainers.txt

But in Trac, I think there is only one "default" maintainer per library, and 
that maintainer is set manually by someone with admin rights. I think, you 
should ask to set yourself the "default" maintainer for Boost.Phoenix by 
posting a separate message on this list.

When you create a ticket for a particular library, the default maintainer is 
set automatically, if you don't do it yourself. But after the ticket is 
created, the maintainer can only be changed manually (i.e. it doesn't change 
when you change the "Component" field).

> 6. Documentation.  I am trying to get to grips with boostbook and quickbook.
>  Some libraries are included in a section with indexed chapters and some
> are not. Is there a policy about this.  When I asked how Phoenix could join
> the only reply I had was not to bother.  Is there a documentation policy? 
> It would be good to be able to generate the web pages myself to check them
> when I am making changes, which may be substantial.

Basically, what you need to do is to make sure your docs build correctly 
locally by running b2 in libs/phoenix/doc. For a new library you would also 
ask Daniel James to include your library in the list and add it to his build 
scripts. Not sure if this changed since the transition to git.

When a new Boost release is prepared, Daniel would typically post a link with 
the beta documentation. You can take a look and make sure it looks correctly.

> 7. More technical.  How are things to be handled in relation to C++11.
> (a) Things which used to work which now don't with C++11?
> (b) Things which only work with C++11?
> (c) and what about C++14?
> I am fixing things in an adhoc way but it would be good to have a uniform
> approach.

Well, that's actually your choice but my preference is:

- What worked with C++03 should work with C++11 and C++14 and so on.
- If a feature required only C++03 then it should stay compatible with C++03, 
no matter what bugfixes and improvements it receives. It may have an optional 
support for C++11 and/or C++14.
- When you absolutely need to break support for C++03, think about a 
transition plan. Maybe implement a separate similar feature that is C++11 only 
and deprecate the C++03 version.

> 8. Boost predef for version numbers.  I have introduced this into Phoenix
> alongside the existing method.

Dependencies on other libraries are your choice but you have to weigh pros and 
cons considering:

- Adding a dependency may reduce the list of supported platforms/compilers.
- Adding a dependency may make your library more heavy and affect compile 
times.
- Adding a dependency makes your library more vulnerable to breakages in other 
libraries.
- Reimplementing the functionality available in another library duplicates the 
effort of maintaining it. You don't benefit from bugfixes in the library and 
you also need to create your own tests.

I don't know what exactly you're using Boost.Predef for but if it's just for 
checking compiler versions, I'd say it's not justified enough. Also, you 
should typically avoid checking compiler versions and instead use the feature 
macros defined by Boost.Config. Resort to version checks only when you know 
the bug is very specific to this particular compiler version and it's not 
worth to create a feature macro in Boost.Config.

> 9. Changelog.  As a user I have found this useful in libraries I have used
> elsewhere, so I have put one into Phoenix following the style I found in
> wave.

Changelog is useful, but most people wouldn't want to checkout the library 
from git just to see it. I think a section in the docs would be more 
appropriate. But, of course, that's your choice.

Also, Daniel prepares release notes for every Boost release in quickbook. You 
would typically add the highlights to it and add a link to the complete 
changelog in your library docs (which would correspond to the Boost release 
and not to the current state in git which may be different).