Project Conventions

Introduction

This document describes the organization of the project Cronos Control. This includes which comments should be in document headers, how the subversion repository is structured, where bug reports and feature requests go, how the code is licensed and organizational things like that. It's not intended to contain details of programming even if they are conventions, too, like file formats etc. They should be specified elsewhere.

Language

CC started as an idea of few Costa Rican engineers. We spent hours of discussion all in Spanish, but decided to make everything regarding the project in English, since it's some kind of world language and the one most populated in computer business. Comments in source code, mailing lists, homepage and documentation should all be in English. This should make it possible to join this project from all over the world.

License

We decided to publish CC under not decided yet license.

The license of this document itself is not decided yet.

If you want to set your part under GPL, please use one of the following headers to include in your source code.

English

This file is part of CC (Cronos Control).
CC is free software; you can redistribute it and/or modify it under the terms of the not decided yet license.
You should have received a copy of the not decided yet license along with CC; if not, write to the info@cronoscontrol.net

Disclaimer
CC is distributed in the hope that it will be useful, but without any warranty; without even the implied warranty of merchantability or fitness for a particular purpose. See the not decided yetlicense for more details.

Document State

This document is, like the whole project, in planning and development state. Any statement might be subject to change and cannot be relied on.

Subversion

Short Introduction

Subversion is a version control system. We put nearly everything regarding the project in our subversion repository. Information about accessing this Subversion repository may be found in the document "Subversion (Version Control for Source Code)".

Repository Folder Structure

Although subversion itself doesn't care about folder names, it's recommend to specify a commitment on a uniform structure. In daily programming a structure of subprojects has proven to be useful. These subproject folders then contain the subfolders branches, tags and trunk. The current development takes place in trunk, releases are copied to tags. These tags mark fix levels of development and are usually not changed in folder tags again. Alternative development branches are put to folder branches. It's possible to merge these branches back to main development branch in trunk. See section Short Introduction and cited references for details.

You can see an example of a folder structure of CC subversion repository below. It only shows the structure itself. Some parts are already used in this way or will be created (e.g. the folders homepage and docs). Other folder names like the ones for libs or clients are freely thought up examples. Create folders with the real names of these parts when you need it.

The folder docs should contain documents like this one. It should contain things like diagrams, concepts, conventions, licensing stuff and so on.

/svnroot
 +- homepage
 |  +- branches
 |  +- tags
 |  |  +- 060919_first_launch
 |  +- trunk
 |     +- de
 |     +- en
 |     +- img
 |     +- include
 |     +- template
 +- docs
 |  +- branches
 |  +- tags
 |  +- trunk
 |- daemons
 |  +- impulsd
 |     +- branches
 |     +- tags
 |     +- trunk
 |        +- src
 |        |  +- transport
 |        |     +- httpd
 |        +- test
 +- libs
 |  +- perlclientlib
 |  |  +- branches
 |  |  +- tags
 |  |  +- trunk
 |  +- somefancydaemonlib
 |     +- branches
 |     +- tags
 |     +- trunk
 +- cr
    +- imperlc
    |  +- branches
    |  |  +- first_micq_client
    |  +- tags
    |  +- trunk
    |     +- conf
    |     +- Impuls
    |        +- Plugin
    |           +- CenterIcq
    |           +- Climm
    |           +- Psi
    +- qt-reader
       +- branches
       +- tags
       +- trunk

Properties

Beside files and folders itself subversion supports so called properties for each of these elements. They can be used to paste dynamic text as done in this document. This can be the author who last changed the file, revision of file or similar stuff. There are also properties specifying the mime-type [1] or marking a file as executable.

On text files (e.g. source code or LaTeX documents) please always set the property svn:mime-type to "text/plain" or anything better matching starting with "text". Subversion distinguishes text files from binary files with this property. (In fact subversion tries to recognize binary files automatically and sets them to "application/octet-stream". Files without svn:mime-type set are treated as text files.)

Please also set svn:eol-style to "native" on all text files. CC parts are intended to be portable to different operating systems and this prevents from problems with line termination characters in text files.

Commit Messages

The intention of commit messages is not to bother you. They are really helpful to find a certain point of development later. It helps to find the point of time when a certain bug was fixed, the start of a branch, the introduction of a new feature and so on. So please make commit messages which shortly explain what you did and where! This saves time and in many cases searching directly through the code shouldn't be necessary.

Source Code

This is about things which should be in source code beside program logic.

Copyright, License, Headers

Please put copyright and license notes as comment at the beginning of each file. Copyright should always be on "The Cronos Control-Team". How the license part looks in detail depends on the license used. A short overview of what is done in this specific file is also useful at the beginning of each file.

Please avoid putting your name in the copyright notice. We want to avoid some kind of "possession" of files. There should be no "This is my project or tool and nobody else should change it." However you are free to write your own tools with your own license playing together with CC outside of impuls-toolset.org.

Comments and Indentation

First and only rule: Do it! Comments are really cool for other developers reading your code and indentation makes it lot easier to read.

Communication

We are using the mailing lists of sourceforge.net for our project. Everything besides bugs, tasks and feature requests, which are done here, is discussed on the mailing lists.