Deployment


Filling the form in the Library Submission Page fulfills the requirements for deployment of a library. When the form is submitted, it is checked by a human to verify that all the information is properly filled in and that the submission fulfils all the requirements of this website.

The form contains links to where the required facilities such as reviews, documentation, download, code repository, and issue tracking. That is, this website does not implement all the facilities required. For example, we require an issue tracking system, but don't implement one here. Even if we do provide such an implementation in the future, library submissions will not be required to use it. This policy/design provides a number of benefits:

  • Library authors can use their preferred set of resources. In many cases, library authors have these things already set up there is nothing to do but to link to them.

  • Libraries differ greatly in their requirements. A very small header library may not need a full featured/elaborate revision tracking system while a larger complex library might require such a system. This model permits each library to choose the best set of resources.

  • As time passes, better facilities become available. If a library author wants to migrate his revision control system from one to another he can do that without having to get permission from some higher coordinating authority.

  • Library modularization is encouraged. Users will download the libraries which interest them - not necessarily some whole set. For a library to be successful, it will have to minimize unnecessary coupling to other libraries. This is a good thing.

  • We expect users who download libraries on this site to run the regression/acceptance tests on their local platform and report their results to a central site. This distributes testing among users in way that will always scale.

This deployment model contrasts starkly with that of Boost itself. Boost is distinguished by

  • The libraries are distributed all at once in one large zip file or tarball. Once one downloads and installs this package, he has all he boost libraries available. Any decision to change the composition of this package - e.g. Deprecation of a library, is arrived at by consensus of boost developers. Since testing occurs every day on the whole distribution, users can be confident that everything will work even if libraries have been coupled together - inadvertently or otherwise.

  • libraries don't have their own version numbers. Version numbers are assigned to each boost distribution. Note that the recent Boost modularization requires per library version numbers, but this requirement is not yet enforced.

  • All libraries use the same system for code repositories, reviews, issue tracking and the like. Any change in the selection of these facilities can only occur by reaching a consensus of boost developers.

  • Test are run on all the whole boost distribution every day. The system works amazingly well. But it takes quite a bit of resources at the testing sites.

Links

The Library Submission Page contains links to point to implementations of required facilities.

LinkFunction
Reviewslink to browseable online library HTML documentation
Documentationlink to browse able online library HTML documentation
Downloadlink to a page from which the library can downloaded. Typically such a page would offer one or more common formats such as ZIP and/or Tarball files.
Code Repositorylink to a source code repository. This code repository should include the whole project directory structure.
Issueslink to a page where users can post problems and they can be discussed with the library author.

Options

There are multitudes of online services for hosting a library. I've spent some time investigating some of the more popular one. They all provide some of the services described above - but none of them provides them all. Of course there is no reason that a library has to depend on only one of these services. One can just as well register his library on more than one service and use the Library Submission Page as a gateway to the various facilities used.

Here is my short assessment of some of the more popular services. For illustrative purposes we've used the safe numerics library to show how links should be filled for on each service on our Library Submission Page .

Google Code

  • Reviews - not supported. It does have a configurable Wiki which could be "made to work", but this option would be more effort that it's probably worth.

  • Documentation - No special facilities for reading HTML documentation prepared in accordance with our requirements. Using the configurable Wiki would require hand converting to the Wiki format - not a practical option.

  • Code repository - supports Git, Subversion and Mercurial. - an example of a link to browse code would be http://code.google.com/p/safe-numerics/source

  • Download - project download supports any files you upload. The link for this page would be http://code.google.com/p/safe-numerics/downloads/list

  • Issues - has a serviceable issue tracking page which can be accessed by http://code.google.com/p/safe-numerics/issues/list

Google Code doesn't have all we want/need but it may be worth using in some circumstances.

SourceForge.net

GitHub

  • Reviews - not supported. Git does have a facility named "code review" but it's not the same as what we've called "formal review". Git also has a Wiki which might be made to work - but it's a little bit crude for our purposes.

  • Documentation - Includes the facility to browse HTML files in the project via any java script compatible browser. Since libraries on this site are required to provide browsable documentation in HTML, this is an incredibly convenient facility. The only thing we have to do is specify the correct link on our Library Submission Page . The Using safe_numerics library as an example, the link would be:

    http://htmlpreview.github.com/?https://raw.github.com/robertramey/safe_numerics/master/safe_numerics/doc/html/index.html

    Now we don't have to find a separate place to load our documentation so that potential users may review the documentation prior to downloading the library. Whenever we push our local copy to the repository, the documentation is automatically synchronized with the code.

  • Code repository - Uses Git (naturally)

  • Download - Includes a download facility for any project loaded. The correct link would be https://github.com/robertramey/safe_numerics/archive/master.zip

  • Issues - Includes a simple Issues facility automatically for any project loaded. The correct link to paste into the Library Submission Page would be https://github.com/robertramey/safe_numerics/issues

All in all, GitHub is almost a perfect match for our purposes. In addition, Boost itself has modularized it's libraries and each one has it's own separate repository on GitHub. Experience with this has been very positive. Given all this, GitHub would have to be the preferred choice unless there are some very compelling reasons to choose something else.

zv7qrnb
There are 0 comments

Comment on This Page