DCVS Configuration Management Rules

The DCVS software distribution is a collection of software packages containing tools and solutions for distributed configuration management with open source code. Many people, companies, and organizations have contributed to it, as it is based on the well-known version control system CVS and the file and repository replication package CVSup. The overall goal should always be to improve the software by making it more usable, readable, generally applicable, and maintainable, while respecting the original ideas, intention, and style. Please bear that in mind when working on DCVS code.

In order to make DCVS 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.

General Rules

  1. Always try to improve the package or system you are working on. Do not remove functionality unless absolutely unavoidable. Do not add functionality unless absolutely needed. Keep it simple (if one can say that at all about a distributed configuration management system).
  2. Try to avoid duplication of work and conflicting work by early communiation with other developers. There are three mail aliases or lists, dcvs{at}elego.de for general discussions and internal support and maintenance, dcvs-test{at}elego.de for DCVS testing issues, and dcvs-commit{at}elego.de , 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 DCVS distribution. Try to build the whole DCVS standard distribution from scratch containing the changes:
    cd prod
    make clean
    make all
    Use the regression tests to verify that everything works as expected:
    cd prod
    make run-tests
  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 DCVS.) You can easily adhere to this scheme by using the package version manager of Elego ComPact for commits, e.g.
    pkgvm -commit major|minor|patch
  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 DCVS 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.

Documentation, Style, Tests, 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. DCVS is a collection of packages, which should always be in a consistent state and tagged a consistent configuration as described above. Currently, the top-level packages are
    dcvs
    the modified and extended CVS source code base
    cvsup
    the modified and extended CVSup code base
    doc
    documentation and notes
    packages
    directory for specific operating system (OS) packages
    prod
    the production directory for build management and regression tests
    test
    test scripts, libraries, and data
    tkdcvs
    the modified and extended tkCVS code base (no longer actively maintained)
    If you make changes to one of these packages, tag it appropriately, and provide a meaningful change log comment. Then add the change log comment to the file doc/CHANGES, heading the layout used by the other entries. Commit the doc package as well (a log comment of 'update CHANGES' is sufficient here :-).
  3. If you add functionality, please also add a regression test to test it. This will greatly facilitate the maintenance of the code. Use the existing regression test framework in the test package, and add an appropriate target to the Makefile in directory prod.
  4. If you know of an existing problem and perhaps a work-around that is not yet documented, please add an appropriate section to doc/KNOWN_ISSUES.
  5. If you think you have a question and perhaps even an appropriate answer to it of general interest, please add it to the FAQ in file doc/faq.faq. All other file formats are generated from this file.

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.


dcvs{at}elego.de