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).