Contributing to CGAL: Submission, Review, and Integration
This document describes the process of integrating a new feature into the CGAL library. A feature is a clearly delimited piece of functionality that is described by
- its motivation, purpose, and intended use (user manual), and
- its API in C++ (reference manual).
Features may range from small (one new function, for example) up to large (a complex hierarchy of classes). Features may extend existing CGAL packages or form new packages.
In order for a feature to become part of CGAL, it must be
submitted to the Editorial Board of CGAL first (*).
Subsequently, the submitted feature is reviewed by the Editorial
Board (possibly with the help of external reviewers). Based on the
reviews and subsequent discussions with the authors, the Editorial
Board may reject the feature, or invite it to pursue the process after
major or minor modifications. A feature whose authors have
satisfactorily addressed all the requested modifications is invited to
the integration process. This step extensively tests its
functionality, cross-platform behavior, and interaction with other
parts of the library. Once the tests are successful and the feature is
stable, it is scheduled for release.
Submission
This is a two-stage process. The authors of a new feature first need to register it by providing a minimum amount of (mostly non-technical) information. This first stage allows the Editorial Board to check whether the intended feature is suitable for CGAL at all. The goal here is to avoid that the considerable effort of a formal submission (second stage) is wasted on out-of-scope features.
Registration
In order to register a feature, the corresponding author should send an email to the Editorial Board, using the address cgal-info AT lists-sop.inria.fr. Within this email (or on a website that you linked to from the email), the following information must be provided.
- Summary of the feature: what is its motivation, purpose,
and intended use? Which algorithmic and geometric tools does it
use and/or implement?
This information allows the Editorial Board to check whether the functionality implemented by the feature is suitable for CGAL. - Authors and maintainers of the feature.
In many cases, authors are already CGAL developers, but we also welcome external contributions. In both cases, we need to know who is going to maintain the feature in the future. - Intended license of the feature.
The feature's license should be compatible with the CGAL open source licenses (LGPL or GPL). If the feature deviates from this, the reasons should be explained. - Intended copyright owner of the feature.
By default, the copyright on the code is owned by the employer of the author(s). If the feature is an extension of an existing package, a potential transfer or sharing of copyright will be debated. Typically, this process involves reaching an agreement between the legal departments of both the author's employer and of the institute(s) that own(s) the copyright of the package(s). - State of the feature.
Is it already fully implemented (even in CGAL?), is there a prototype available, or is it in the design phase? Usually, a submission makes sense only if at least a prototype is available already.
The Review Manager acknowledges the registration. (S)he informs the corresponding author (usually within two weeks) by email whether the feature is invited for a formal submission. In case a feature is not invited, the decision will be explained to the authors. The decision process might involve further discussions with the authors.
Formal Submission
The formal submission consists of
- a user manual and a reference manual,
preferably in CGAL manual style, or similar. CGAL developers have access to the CGAL manual tools used to create CGAL manuals. For external contributions, access to the manual tools can be granted upon request. - a proposal for integration into the manual,
ie: will it be inserted into an existing chapter? or will it form a separate chapter? in an existing part, or should a new part be created?
This proposal should be sent in a separate mail (or in the CGAL wiki, for authors who already have an access).
The user manual contains the motivation, purpose, and intended use of the feature, as well as examples and pictures, and implementation details (which algorithm has been implemented? What is its runtime?). The reference manual contains the precise API of the feature, meaning its concepts, classes, and functions.
The formal submission does not involve source code, and its review is based purely on the user and reference manual. Source code will be looked at during the integration phase.
Authors whose feature has been invited should send the formal submission to the Editorial Board of CGAL, again under cgal-info AT lists-sop.inria.fr. The Review Manager acknowledges the formal submission and gets back to the corresponding author (usually within six weeks) with the initial reviews.
(*) ^ The only exception to these submission rules are for very small features (typically a slight modification in the specifications, like a new function) in an existing package, done by its maintainers. The maintainers of a package can perform such small changes under their own responsibility. However, such changes must still be announced using the wiki page dedicated to this case. Then the Editorial Board may ask for a review or object.
Review
The review process is initiated by the Review Manager who appoints a primary reviewer for the feature. The primary reviewer is a member of the Editorial Board and responsible for communication with the authors. Besides his/her own review, the primary reviewer organizes at least a secondary review. Initial reviews are neither anonymous nor final; they are expected to be followed by a discussion between authors on the one hand and the reviewers on the other hand, with the goal of efficiently sorting out the critical issues. The whole review process is documented on an appropriate wiki page that is accessible to authors, reviewers, and all CGAL developers.
The time frame for the discussion period following the initial reviews is flexible. The Review Manager makes sure that the primary reviewer remains responsive throughout the discussion. It is in the interest of the authors of the feature to remain responsive as well.
When the discussion has stabilized, the primary reviewer proposes a decision (the API is accepted or rejected) to the Editorial Board, accompanying the proposal with the main arguments supporting it. The final decision is made accordingly unless there is an objection by an editor within fifteen days.
Reasons for rejection may be insurmountable dissensions between authors and reviewers, or irresponsiveness on the side of the authors. The Review Manager will inform the corresponding author about the decision and explain it. In case of major modifications being requested, a second round of reviews may become necessary.
A feature whose API (Reference Manual) has been accepted is called a candidate feature. The authors of a candidate feature are expected to become CGAL developers, in order to access the CGAL source code management system. From this point, they must maintain their code within CGAL's source code management system in a dedicated branch referred to as a "feature branch" (aka "topic branch"). Once the feature branch is available, the authors are invited by the Release Manager to integrate their code in the testing process.
Every CGAL release has a Feature Freeze date.
The Feature Freeze, which is three months before the actual release
date, marks the date from which on the API of the library for the next
release is fixed/frozen, in particular, the reference manual should
not change after that date. Exceptions are obvious bug/typo fixes and
precisions in the specification.
Authors of a feature should take into account that it can take several
weeks until the first review arrives, which is usually followed by a
discussion with the author on issues raised by the review. Moreover,
changes need to be incorporated in a revised submission.
A feature can be candidate for integration into a CGAL release only if the authors have done all modifications to the reference manual requested during the review process, and that these modifications have again been checked by the reviewers, before the Feature Freeze of the next release.
Integration
Before a package can actually be integrated in a CGAL release, some more steps must be followed. We just sketch these steps in the current document:
- The final version of the User Manual must be approved by the reviewers.
- The package must be accompanied by a full test-suite, and the test-suite must run without errors.
Every CGAL release has a Code Freeze date.
The Code Freeze, which is one month before the actual release
date, marks the date from which on the code should not change anymore
without explicit agreement of the release manager,
in order to not disturb the final preparation of the release.
The authors of a feature which has gone through the whole process
successfully, before the Code Freeze, are invited by the Release
Manager to merge the feature branch into the main development branch
(the "next" branch).