Boost logo

Boost :

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.


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
- Adding a dependency makes your library more vulnerable to breakages in other
- 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).

Boost list run by bdawes at, gregod at, cpdaniel at, john at