Difference between revisions of "WebIssues/Guidelines"

From MiMec
Jump to: navigation, search
(Project Philosophy)
Line 35: Line 35:
 
: 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.
 
: 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
 
; 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. It means that only new commands can be added to the protocol and existing ones must not be changed except for major versions (see [[./Protocol|protocol description]] for more information). Also when changing the database structure take into account that it must be possible to easily upgrade existing installations.
+
: Adding a new field to the WebIssues protocol may be tempting but will force all users to install a new version of the client. It means that only new commands can be added to the protocol and existing ones must not be changed except for major versions (see [[../Protocol|protocol description]] for more information). Also when changing the database structure take into account that it must be possible to easily upgrade existing installations.
 
; Keep it multi-platform
 
; Keep it multi-platform
 
: Another important rule is that WebIssues should support both Linux and Windows and several databases, currently ySQL, PostgreSQL, Firebird 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.
 
: Another important rule is that WebIssues should support both Linux and Windows and several databases, currently ySQL, PostgreSQL, Firebird 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
 
; 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 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 any of the above rules.
 
: The three rules mentioned above make WebIssues a general platform for creating customized solutions for particular purposes. If someone is willing to pay 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 any of the above rules.

Revision as of 14:16, 16 March 2009

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

Wiki

Please use the subpage feature to split a page into a hierarchy of pages if there is a lot of information. All pages should related to WebIssues should be located under the WebIssues page in the hierarchy. 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

Make sure committing to trunk won't break anything and consult all non-trivial changes with the project maintainer. For bigger changes use a separate branch which can be reviewed and merged back 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. It means that only new commands can be added to the protocol and existing ones must not be changed except for major versions (see protocol description for more information). 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 several databases, currently ySQL, PostgreSQL, Firebird 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 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 any of the above rules.