Difference between revisions of "WebIssues/Guidelines"

Revision as of 11:35, 26 February 2008

This page contains a brief list of standards, conventions and guidelines used within the WebIssues project.

Wiki

Please put all pages related to WebIssues in the WebIssues namespace. In addition, please use the subpage feature to split a page into a hierarchy of pages if there is a lot of information. Try to follow the existing structure of pages when adding new content. Put a short summary on top of each page and next to links to sub-pages.

Use the discussion pages for comments, opinions and suggestions, especially before making non-trivial changes to the main pages. This Wiki is accessible to everyone so it should be clean and representative. The main pages should contain only relevant and up to date information.

SVN Repository

Please do not commit non-trivial changes directly to trunk. Instead use an appropriate branch. All users should have a directory in the repository (for example /users/pedro) for their changes, which are then reviewed and merged into trunk.

Coding Conventions

There are no enforced general conventions other than respecting the existing conventions in code which you are modifying. People responsible for particular projects may use whatever conventions they prefer as long as they are internally consistent.

That said, it's obvious that all code that goes into trunk must be readable and well formatted. Always use meaningful names and avoid putting too much code into one line (for example, avoid nested function calls like a(b(c()))). Use comments describing the most important classes and functions (preferably in a way that API documentation can be automatically generated from it). Avoid meaningless comments in code - good code should be self-documenting.

As for the client and server, the most important rules are:

• don't use tabs - indent code with four spaces
• put opening { brackets in the same line in statements (if, for, etc.) but in the next line in declarations (classes, functions)
• use spaces inside () and [] brackets, after commas and around binary operators, for example foo( bar + 3, "hello" )

Project Organization

The WebIssues system is divided into several separate projects and each of them has a maintainer who is responsible for technical design (defining modules, classes, patterns, practices etc.) and organization of the code (directory structure, building, conventions etc.). The maintainer is free to make decisions on his own as long as they do not affect other projects and do not conflict with the WebIssues philosophy.

The system also has a single leader responsible for making all strategic decisions (the scope of each project, important features, technologies used), defining the release schedule and organization of the entire system. The leader also coordinates tasks which require cooperation between various projects (for example, when a change in the server affects the client). All decisions made by the leader are consulted with the entire team, but once made they are final.

Project Philosophy

WebIssues is an open source system created by volunteers and the currently available manpower is very limited. The general principle of the project is trying to achieve maximum effect with minimum effort. In order to accomplish this, several rules must be followed:

Keep it simple

The system should consist of a large number of simple, easy to use and generic features. Avoid creating features designed for only a small group of users or making complex solutions that no one will take full advantage of and will just make using and developing harder. Try to reuse existing concepts.

Keep it backward compatible

Adding a new field to the WebIssues protocol may be tempting but will force all users to install a new version of the client. More details are TBD, but that basically means that only new commands can be added to the protocol and existing ones must not be changes. Of course if the reasons are important enough we may decide to make a new version of the protocol which is no longer backward compatible. Also when changing the database structure take into account that it must be possible to easily upgrade existing installations.

Keep it multi-platform

Another important rule is that WebIssues should support both Linux and Windows and at least three databases: MySQL, PostgreSQL and SQL Server. There should be no exception for that. Features that only work in a particular environment can be offered as extensions or customizations but should never go into core releases.

Keep it customizable

The three rules mentioned above make WebIssues a general platform for creating customized solutions for particular purposes. If someone is willing to pay enough money for integrating WebIssues with a lawnmower controller, we can do it, as long as we keep the required changes fully separated from the core version so that we don't have to violate and of the above rules.