CM3 Configuration Management Rules

The CM3 Modula-3 software distribution is a huge collection of software packages containing tools and solutions for lots of different problems and application domains. Many people, companies, and organizations have contributed to it over more than a decade of years, resulting in certain variations of style, quality, and usability. The overall goal should always be to improve the software by making it more usable, readable, general applicable, and maintainable, while respecting the original ideas, intention, and style. Please bear that in mind when working on CM3 code.

In order to make CM3 development as little chaotic as possible, the following rules have been set up. While this is only the first suggestion, and everything is open for discussion and change, they should nonetheless be heeded until all (or the majority) of those working on the code have agreed to change them.

Everybody may apply for repository access by sending email with a short description of the intended work and providing an ssh key. Usually, access will be granted within a few days. However, elego Software Solutions GmbH reserves the right to revoke the permission and deny repository access at any time without any notice, and will certainly do so in cases of damage or misuse.

General Rules

1. Always try to improve the package or system you are working on. Do not remove functionality unless absolutely unavoidable.
2. Try to avoid duplication of work and conflicting work by early communiation with other developers. (I suggest to setup two mail aliases or lists, cm3-devel for general discussions, and, cm3-commit to distribute the CVS commit logs).
3. Do not misuse your access to the repository server or the repository itself. Do not tamper with other sub-systems on the server machine. Do not edit or change the repository directly.

Software Configuration Management

1. Only commit consistent and compilable versions of a package (unless, of course, the package was broken before and your changes are an improvement anyway).
2. Test your changes within the package and in the context of other packages of the CM3 distribution. Try to build the whole cm3 standard distribution from scratch containing the changes, if at all possible (scripts/cm3-std.sh, scripts/do-cm3-core.sh).
3. Always commit whole packages. Add concise and meaningful log messages. Tag consistent configurations after every commit with a tag of the form

   devel_pkgname_dmajor_minor_patchlevel

   or

   release_pkgname_major_minor_patchlevel,

   depending on whether it is a development commit or a package release. Add tag and log message to the PkgTags file present in every package root. (This is the scheme that Elego ComPact implements by default, which has been used to maintain CM3 during the last year.) (Note: release tags have not really been used until now, but the consistent development configurations are nonetheless helpful.)
4. Use CVS vendor branches to import third-party software.
5. If you are about to begin a non-trivial project, multi-package changes, or branch development for one or more packages, announce it early to other developers, so that at least somebody may shout his `Veto'.
6. When working on a fix for one of the problems contained in the cm3 problem database at Elego, please note the request number in the log message like this: `request id: 24' or `request id 24'.
7. Do not use cvs admin.
8. Never remove existing versions from the repository.
9. Do not move files in the repository.

Style and other Conventions

1. If working on existing code, heed the style used by the original author(s). Do not reformat whole sections of code, as this makes diffs and change propagation much more complex and sometimes impossible.
2. When writing new code, use an indentation of two blanks for every logical block level.
3. Try to follow the conventions of the M3 standard libraries, like providing one main type per module (named Module.T), providing quake macros for generics, etc.
4. Provide complete overrides for all imports relative to the ROOT variable defined in the CM3 scripts, so that package builds with and without use of the globally installed package pool are possible.
5. Use combined Upper/lower-case identifiers instead of ALL_UPPER_CASE or all_lower_case names. Try to choose meaningful names that describe the semantics and pragmatics of the named entity.
6. Document all exported entities (constants, types, variables, procedures) next to their declaration in the source code.

Doubtless these rules will have to be extended and/or changed, but, as already mentioned, we should all adhere to them until we have agreed on something better.