Project Conventions

  1. Project Conventions
    1. Introduction
      1. Language
      2. License
        1. German
        2. English
      3. Document State
    2. Subversion
      1. Short Introduction
      2. Repository Folder Structure
      3. Properties
      4. Commit Messages
    3. Source Code
      1. Copyright, License, Headers
      2. Comments and Indentation
    4. Communication

This document describes the organisation of the project IMPULS. 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 organisational things like that. It’s not intented to contain details of programming even if they are conventions, too, like file formats etc. They should be specified elsewhere.

Introduction

First of all I’d like to say something about the spirit of this project. At the moment it’s fully developed in free time and working for the project should be more fun than work. Nevertheless it could possibly grow in the future so we thought up some “rules”. The intention of these rules or conventions as we call it, is to make team work easier for all kinds of developers, regardless whether they founded the project or just joined the team. If you don’t understand something regarding the project, feel free to ask on the mailing lists.

Language

IMPULS started as an idea of few german university students. We spent hours of discussion all in german, 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 IMPULS under GNU General Public License (GPLv2). However this is no dogma, because IMPULS is a toolset. Feel free to put your part of the toolkit to another license as long as you take care of the GPL licensed parts.

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.

German

Diese Datei ist Teil von IMPULS (Instant Messenger Personal User Log Storage).

IMPULS ist freie Software; es darf weiterverbreitet und/oder verändert werden, solange dabei die Bedingungen der GNU General Public License, wie sie von der Free Software Foundation veröffentlicht wurde, entweder in der Version zwei oder (nach Belieben) einer späteren Version, eingehalten werden.

Eine Kopie der GNU General Public License sollte gemeinsam mit IMPULS ausgeliefert worden sein. Wenn nicht ist sie bei der Free Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110–1301 USA erhältlich.

Disclaimer

IMPULS wird in der Hoffnung verbreitet, dass es nützlich ist, jedoch ohne jegliche Garantie, auch bezogen auf die mittelbare Garantie der allgemeinen Gebrauchstauglichkeit oder Nützlichkeit für einen bestimmten Zweck. Weitere Details sind in der GNU General Public License zu finden.

English

This file is part of IMPULS (Instant Messenger Personal User Log Storage).

IMPULS is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

You should have received a copy of the GNU General Public License along with IMPULS; if not, write to the Free Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110–1301 USA

Disclaimer

IMPULS 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 GNU General Public License 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. There is a real good book about subversion in a whole. This book is online available and contains also a worth readable introduction to subversion. See Version Control with Subversion.

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 ShortIntroduction and cited references for details.

You can see an example of a folder structure of IMPULS 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 orga). 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 orga 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
 +- orga
 |  +- branches
 |  +- tags
 |  +- trunk
 +- daemon
 |  +- 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, 2] 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. IMPULS 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 I.M.P.U.L.S.-Team”. How the license part looks in detail depends on the license used. In case of GPL you can use the examples from section License. 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 IMPULS 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 more 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. See section mailing lists in this wiki.