Getting new libraries into cpp-netlib.

This document outlines how we get new libraris accepted as part of cpp-netlib

The maintainers and members of the community generally like seeing well-prepared proposals for libraries to be included. The reason for this is so that we waste as little time from everyone who's going to be involved in the process as possible. Therefore we ask that before you bring an idea to the table, please prepare the following information (even only when sending an email to the mailing list).

  • Problem Statement. It's surprisingly hard to evaluate proposals without a problem being solved. To make it easier to evaluate proposals, please define what problem you're intending to solve with the library you're proposing to include (if it's already there, that's good — if it's going to be developed from scratch, it's easier to know what the problem is before we start).
  • User Stories. We generally like to evaluate libraries based on how easy it is for users to use. It is then paramout that you present a vision on how users of the library will be using the library. Examples of user code would be most appreciated.
  • Scope and Goals. Knowing what the scope of your library will be is better generally so that interested parties who want to help in development and maintenance can see whether they can help or whether you can do it all on your own. Knowing what you want to accomplish and sharing those with the community of users and developers gives everyone the same ideas as to what to expect.
  • Design Documentation. API design is hard, and having a high level idea of how things will be implemented in your library makes it easier to see the bigger picture. This document need not be too formal but it should be something self-contained and easily modified/commented-on for a lower collaboration bar. Please do not put your design document as an email — a Wiki document, shared Google Document, or a GitHub repository is much easier to discuss than an email.

Once you have these things, fire off an email to the mailing list citing the above four preparation sections.

All discussions should occur in the mailing list for issues not related to the design documentation. If the design doc is a shared Google Document comments will be made on the document itself. For everything else, the discussions should be done on the mailing list.

The discussion will be considered concluded when all the maintainers of the library agree that the proposal makes sense and that it's something the community wants to have in the library. The process will be tracked by a formal survey on the mailing list run by one of the maintainers.

Once everybody's convinced that things should move forward, then maintainers and interested contributors hunker down to start collaborating on the development of the library.

The collaboration process is intended to be much simpler: all discussions on progress and questions to clarify happen on the mailing list. Matters affecting progress — developers missing in action, thorny implementation details, blockers, and style questions should be discussed all in the open. We encourage this so that everyone in the community is involved in the process where we exclude nobody's opinion and contributions.

As far as development is concerned, there are two main ways of getting the development done. Each one has its merits so we present both.

Fork of cpp-netlib

The fork process is straight-forward — whoever proposed the library and those who have pledged to contribute to the implementation shall fork the main repository and develop in parallel as the main repository. They can send progress reports to the main developer list and have the partially complete work merged into the master branch as it gets completed. All changes can be isolated to an external fork where changes are meant to be integrated before being submitted in bulk to the main repo as a single PR.

This process effectively promotes whomever is driving and owning the process as a maintainer of cpp-netlib. The downside to this is that it's a lot of responsibility and may be time consuming.

Submodule to cpp-netlib

The submodule approach is much more decoupled and allows for having the implemented library be as stand-alone as possible. Some libraries in cpp-netlib are already submodules and are maintained separately by the corresponding maintainer.

The problem with this approach is that coordinating breaking changes on multiple interacting submodules will be much harder. It also makes the release/development process much more cumbersome than the fork model. It also makes it harder to enforce the style guide and development processes on the submodule.

Preferred Mode

The preferred mode of development is the fork model, where coordination is much closer and much more explicit. It also allows the maintainers to easily cut releases and maintain a single repository unto which all changes and history can be kept.

Only in rare circumstances will a submodule actually be preferred — for instance, if the project has already been in existence before being accepted into cpp-netlib or if it's made sufficiently stand-alone for purposes of inclusion into the standard library.

Inclusion entails three specific things which will differentiate any other library from an accepted cpp-netlib library.

  • Maintainership. All current maintainers of cpp-netlib get maintainership over the library that's accepted, and the proposer and main developers of the library become maintainers of cpp-netlib as well. We usually defer library-specific issues to the main library maintainer/developer but in case of whole-library and community decisions all maintainers get the same responibilities.
  • Support. Any included library shall be supported by the community and maintainers until it is either removed or retired.
  • Distribution. Any library included into cpp-netlib shall be distributed as part of the main distribution.

On the note about maintainership — once someone is promoted to maintainer of cpp-netlib, that person gets administrative rights to the project repository. In the event that someone becomes inactive or relinquishes the role, only then will that person be considered an ex-maintainer.

This means, once someone is deemed a maintainer, he'll always be considered a maintainer unless he becomes inactive or relinquishes that role.