The CHICKEN Development Process
Introduction
This document defines a set of rules with the intention of making the development process of the core system more reliable and more transparent and to maximize the information flow between those that intend to enhance and maintain it. The core system is defined as the compiler (chicken, csc), the interpreter (csi), the core library units and the setup tools (chicken-install, chicken-status and chicken-uninstall). This also applies to the build system. Since interoperability of the basic extension-installation tools with the CHICKEN infrastructure is crucial, the process will touch issues that are not directly related to the core source code but also to external subsystems like chickadee, henrietta and salmonella.
Developer Roles
Some developers have commit rights to the CHICKEN git(1) repository for the core system, in the following description designated as the committers. Core developers or users interested in submitting patches to the core system will be called contributors.
Branches
The master branch of the CHICKEN git(1) repository represents the current state of development. Releases and development snapshots will be made from this branch (see the release policy for more details). Committers may create further branches as desired (particularly inventive branch names are much appreciated).
Patches
Committers or interested users may submit patches to the chicken-hackers mailing list that provide bug-fixes or enhancements. This will allow core maintainers and other users to review the patch before it is applied to the master branch. After a certain period (which is not explicitly defined, but it should be long enough to give people an opportunity to comment on the change, possibly 3 of more days) and if the patch is accepted (see below for a definition of "accepted"), the patch is applied to the "master" branch by someone with commit access. If the contributors does not have commit access, he/she will have to ask for application by one who has. The contributor has to take care of getting the patch committed, otherwise it may happen that patches add up with nobody feeling responsible. As an alternative to the patch, a ticket can be created in the bug-tracker and an URL of the ticket or patch be posted. Also, if a patch needs longer testing or review, or if the change needs more consideration, it may be of advantage to create a ticket to simplify keeping track of the issue.
A patch is accepted if one (in case of a patch by a committer) or two (in case of a patch by a normal, sane person) comitters sign it off.
A committer may always veto a patch, with statement of reason. This is to prevent a small group from pushing controversial ideas without going through a proper up-front discussion, and to ensure that non-breaking changes which turn out to be breaking changes after all are rolled back and move through the CR process.
If the patch is rejected, further handling of the change has to be discussed (normally on the chicken-hackers mailing list) and further actions should be decided upon on a case-by-case basis, with a modified patch being resubmitted or with the patch being completely withdrawn.
Trivial changes and documentation fixes should not require patch submission to the mailing list. It should be possible to commit such changes right away, but these changes should be really trivial.
(It would be a good idea to collect rejected patches somewhere, just in case)
Incompatibilities
Changes that may break backward-compatibility with the most recently released CHICKEN version should be submitted as change requests. See change-requests for more information.
Changes that break C-level compatibility (for example by modifying the signature of an exported C routine) will require bumping up the "binary compatibility version" (BINARYVERSION in defaults.make).
It must always be possible to bootstrap CHICKEN from a publicly-accessible release or development snapshot. Changes that would make it impossible to bootstrap from the most recent of these should not be applied until a suitable snapshot is published.
Deprecations
Removal of functionality or of parts of the officially documented external API should go through a deprecation phase: it should be clearly marked as deprecated and retained until after the next official release of the core system (an X.X.0 release). After the release the deprecated functionality can be removed, unless the change is so fundamental or touches many extensions that it is considered vital to keep it longer to avoid breaking eggs or code written for older release. Still deprecations should go through the patch submission process (the change in the core system would then be normally just a comment indicating the relevant code as deprecated).
Once something is deprecated, it is a good idea to add a note to the development roadmap when the functionality is planned to be actually removed.
API deprecations should be marked as such in types.db and any documentation removed in the manual in the git(1) repository.
Emergency fixes
Sometimes it may be necessary to apply "emergency" bugfixes or fixes for security problems instantly without going through the whole process of submission. In such a case the change should be clearly described on the mailing list and possibly be taken back and replaced later by an official patch, if the original patch is insufficient or a dirty hack.
Documentation
Changes to the core system should be reflected in the manual, preferably in the manual files contained in the repository. Changes therein will be merged into the official wiki manual on the next release.
Development snapshots
After major changes it is advisable to make a development snapshot available, which involves updating the NEWS file and putting a tag on master. Once the snapshot is available for download, it should be announced on chicken-users together with a list of changes since the last snapshot. The NEWS sections for all development snapshots since the last official release will be merged before the next release takes place. After a snapshot is released, the version should be bumped up in all places where this is necessary. Please see the release policy for more detail.
Keeping things reasonable
There may be situations where critical fixes are necessary or when the build breaks due to silly little bugs and typos. It should be ok to fix this without going through the whole process of submitting a patch. Large-scale "cleanup" patches and rewrites should be avoided or, when necessary, be done in tight collaboration with some or all of the core maintainers.
List of committers
The following people currently have commit rights to the git(1) repository: