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
-
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).
-
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.
-
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
-
Only commit consistent and compilable versions of a package
(unless, of course, the package was broken before and your
changes are an improvement anyway).
-
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
-
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
-
Use CVS vendor branches to import third-party software.
-
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'.
-
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'.
-
Do not use cvs admin.
-
Never remove existing versions from the repository.
-
Do not move files in the repository.
Documentation, Style, Tests, and other Conventions
-
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.
-
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 :-).
-
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.
-
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.
-
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