Skip to content

Commit b4ab929

Browse files
author
Marius Burkard
committed
Merge branch '6049-update-the-contributing-doc' into 'develop'
Resolve "Update the contributing doc" Closes #6049 See merge request ispconfig/ispconfig3!1408
2 parents e2e795a + 6f7aa4f commit b4ab929

File tree

1 file changed

+282
-64
lines changed

1 file changed

+282
-64
lines changed

‎CONTRIBUTING.md‎

Lines changed: 282 additions & 64 deletions
Original file line numberDiff line numberDiff line change
@@ -1,99 +1,318 @@
1-
# Which code branch to use
1+
# Contributing to ISPConfig
2+
ISPConfig is a open source project and community contributions are very welcome. To contribute, please stick to the guidelines.
23

3-
The master branch is used for code (mostly new features) that shall go into the next major release (e.g. 3.2, 3.3 and so on). The stable branch (e.g. stable-3.1, stable-3.2) is the branch for the current intermediate and bugfix releases. Bugfixes shall be committed to the current stable branch and not the master branch. The stable branch is merged to the master automatically from time to time, please do not submit bugfixes a second time against the master.
4+
This document is under development and will be continuously improved.
5+
6+
# Issues
7+
* Before opening a new issue, use the search function to check if there isn't a bug report / feature request already.
8+
* If you are reporting a bug, please share your OS and PHP (CLI) version.
9+
* If you want to report several bugs or request several features, open a separate issue for each one of them.
10+
11+
# Branches
12+
* Please create an issue for each contribution you want to make.
13+
* Do not put multiple contributions into a single branch and merge request. Each contribution should have it's own branch.
14+
* Do not use the develop branch in your forked project for your contribution. Create a separate branch for each issue.
15+
* Give your branch a name, e. g. `6049-update-the-contributing-doc ` where 6049 is the issue number.
16+
17+
# Merge requests
18+
Please give your merge request a description that shortly states what it is about. Merge requests without a good title or with missing description will get delayed because it is more effort for us to check the meaning of the changes made.
19+
Once again: Do not put multiple things into a single merge request. If you for example fix two issues where one affects apache and one mail users, use separate issues and separate merge requests.
20+
You can group multiple issues in a single merge request if they have the same specific topic, e. g. if you have one issue stating that a language entry in mail users is missing and a second issue that a language entry for server config is missing, you can put both issues into a single branch and merge request. Be sure to include all issue ids (if multiple) into the merge request's description in this case.
21+
* Open a issue for the bug you want to fix / the feature you want to implement
22+
* After opening the issue, commit your changes to your branch
23+
* Note the issue # in every commit
24+
* Update the documentation (New devs will not have access to this. Please send a email to docs@ispconfig.org)
25+
* Add translations for every language
26+
* Use a short title
27+
* Write a clear description - for example, when updating the contributing guidelines with issue #6049: \
28+
"Update of our contributing guidelines \
29+
Closes #6049"
30+
* Please be aware that we are not able to accept merge request that do not stick to the coding guidelines. We need to insist on that to keep the code clean and maintainable.
431

532
# Some guidelines for web development with php.
633
-----------------------------------------------------
7-
* Unix Line Breaks Only, NO windows breaks please.
8-
* Tabs to indent lines, NO spaces
9-
* no accidental _<?php space before, within or after a file
10-
* every PHP file starts and end with <?php ?> no spaces before or after
11-
* error_reporting(E_ALL|E_STRICT), yep PHP 5
12-
* Magic quotes is gone, get used to it now. config = magic_quotes_gpc() Everything must be quoted
13-
* Don't use ereg, split and other old function -> gone in PHP 5.4
14-
* Don't use features that are not supported in PHP 5.3, for compatibility with LTS OS releases, ISPConfig must support PHP 5.3+
15-
* Don't use shorttags. A Shorttag is <? and that is confusing with <?xml -> always use <?php
34+
* Don't use features that are not supported in PHP 5.4, for compatibility with LTS OS releases, ISPConfig must support PHP 5.4+
35+
* Don't use shorttags. A Shorttag is `<?` and that is confusing with `<?xml` -> always use `<?php`
1636
* Don't use namespaces
1737
* Column names in database tables and database table names are in lowercase
1838
* Classes for the interface are located in interface/lib/classes/ and loaded with $app->uses() or $app->load() functions.
1939
* Classes for the server are located in server/lib/classes/ and loaded with $app->uses() or $app->load() functions.
20-
* please mark any section that need review or work on with /* TODO: short description */
21-
* Make function / var names on the following way, first word lower, next word(s) first letter upper like. getFirstResult();
22-
* always a space but NO newline before opening braces, e. g.
23-
```
24-
class abc {
25-
public function cde() {
26-
if($a == $b) {
27-
return false;
28-
}
29-
}
40+
41+
### Indentations
42+
43+
Indentations are always done with tabs. Do **not** use spaces.
44+
It is recommended to set your IDE to display tabs with a width of 4 spaces.
45+
46+
### Variable and method / function names
47+
48+
Methods and functions should always be written in camel-case. Variables and properties should always be lowercase instead.
49+
50+
**Correct:**
51+
```php
52+
class MyClass {
53+
private $issue_list = [];
54+
55+
private function getMyValue() {
56+
57+
}
3058
}
3159
```
32-
* no spaces after function/method or control names, e. g.
33-
```
34-
function abc($x, $y) {
35-
if($condition == true) {
36-
$x = 2;
37-
}
60+
61+
**Wrong:**
62+
```php
63+
class my_class {
64+
private $IssueList = [];
65+
66+
private function get_my_value() {
67+
68+
}
3869
}
3970
```
40-
and NOT
71+
72+
### Blocks
73+
74+
#### Curly braces
75+
76+
Opening curly braces always have to be in the same line as the preceding condition. They are separated by a single space from the closing paranthesis.
77+
Closing curly braces are always on a separate line after the last statement in the block. The only exception is a do-while block where the logic is inverted.
78+
79+
Curly braces are **always** to be used. Do not leave them out, even if there is only a single statement in the corresponding block.
80+
81+
**Correct:**
82+
```php
83+
if($variable === true) {
84+
85+
}
86+
87+
while($condition) {
88+
89+
}
90+
91+
do {
92+
93+
} while($condition);
4194
```
42-
function abc ($x, $y) {
43-
if ( $condition == true ) {
44-
45-
}
95+
96+
**Wrong:**
97+
```php
98+
if($variable === true){
99+
100+
}
101+
102+
if($variable === true)
103+
{
104+
46105
}
106+
107+
if($variable === true)
108+
$x = 'no braces';
109+
110+
while($condition) { }
47111
```
48112

49-
# Commenting style
113+
#### Short style
114+
115+
The short style of conditional assignments is allowed to be used, but it must not affect readability, e. g. they shall not be nested.
116+
117+
**Allowed:**
118+
```php
119+
$a = 0;
120+
if($condition === true) {
121+
$a = 1;
122+
}
50123

51-
The comments break down into the following types
124+
$a = ($condition === true ? 1 : 0);
52125
```
53-
// is uses for removing lines and debug dev etc
54-
/*
55-
is used to comment out blocks
56-
*/
57126

58-
/** is used to create documentaion
59-
* thats over
60-
* lines
61-
*/
127+
**Disallowed:**
128+
```php
129+
$x = ($condition === true ? ($further == 'foo' ? true : false) : true);
62130
```
63-
If you need to block out a section then use
131+
132+
133+
#### Spaces and paranthesis
134+
135+
The rules for using spaces are:
136+
- no space after `if`/`while` etc. and the following opening paranthesis
137+
- single space after closing paranthesis and before opening curly brace
138+
- no spaces at the end of a line
139+
- no spaces after opening paranthesis and before closing paranthesis
140+
- single space before and after comparators
141+
142+
**Correct:**
143+
```php
144+
if($variable === $condition) {
145+
146+
}
147+
148+
while(($condition !== false || $condition2 === true) && $n <= 15) {
149+
$n++;
150+
}
64151
```
65-
/*
66-
function redundant_code(){
67-
something here
152+
153+
**Wrong:**
154+
```php
155+
if ($variable===$condition) {
156+
157+
}
158+
159+
while(($condition!==false||$condition2===true))&&$n<=15){
160+
68161
}
69-
*/
70162
```
71-
To block out single lines use // and all // are assumed to be redundant test code and NOT comments
72163

73-
// print_r($foo);
164+
#### Newlines inside of conditions
165+
166+
Breaking up conditions into separate lines can be done if it positively affects readability.
167+
168+
```php
169+
if($condition === true && ($state === 'completed' || $state === 'pending') && ($processed_by !== null || $process_time < time())) {
74170

75-
Do not use the phpdoc on every function, eg
171+
}
76172
```
77-
/**
78-
* Login a user
79-
* @param string user username
80-
* @param string password of user
81-
*/
82-
function login($user, $pass){
83-
173+
can also be written as
174+
```php
175+
if($condition === true
176+
&& ($state === 'completed' || $state === 'pending')
177+
&& ($processed_by !== null || $process_time < time())
178+
) {
179+
84180
}
85181
```
86-
as this function is self-explaining, the following clean code will suffice
182+
This must not be abused, e. g. the following is not allowed:
183+
184+
```php
185+
if($a == 1
186+
|| $b == 2) {
187+
188+
}
87189
```
88-
function login($user, $pass){
89-
90-
}
190+
191+
### Arrays
192+
193+
#### Short syntax
194+
195+
Please **do** use short array syntax. We have deprecated the old-style array syntax.
196+
197+
**Correct**:
198+
```php
199+
$var = [];
200+
201+
$var2 = [
202+
'conf' => [
203+
'setting1' => 'value1'
204+
]
205+
];
91206
```
92207

93-
# Where to store custom settings
208+
**Wrong:**
209+
```php
210+
$var = array();
94211

95-
## Interface settings
212+
$var2 = array(
213+
'conf' => array(
214+
'setting1' => 'value1'
215+
)
216+
);
217+
```
218+
219+
#### Spaces and newlines
220+
221+
When defining an empty array, both brackets shall be on the same line. When defining an array with values, the style depends on the values you are going to assign.
222+
223+
##### List of values
224+
225+
When defining an array with a list of values, e. g. numbers or names, they should be on the same line as the brackets without using new lines, as long as the line does not exceed a total number of characters of about 90. After each comma there has to be a single space.
226+
227+
##### Nested array
228+
229+
When defining a nested array onle the opening bracket is to be on the same line. The closing bracket has to be on a separate line indented by `tabs * level of array`.
230+
231+
##### Examples
232+
233+
```php
234+
// empty array
235+
$a = [];
96236

237+
// array with list of values
238+
$array = [4, 3, 76, 12];
239+
240+
// array with long list of values
241+
$array = [
242+
'This is one entry', 'This is a second one', 'Another one', 'Further entries', 'foo', 'bar', 34, 42, $variable, // newline here for better readability
243+
'Next entry', 'the last entry'
244+
];
245+
246+
// nested array
247+
$array = [
248+
'conf' => [
249+
'level' => 1,
250+
'settings' => [
251+
'window' => 'open',
252+
'door' => 'closed
253+
]
254+
]
255+
];
256+
```
257+
258+
**Not-to-dos:**
259+
```php
260+
$array=[
261+
];
262+
263+
$array = [
264+
1,
265+
4,
266+
35,
267+
23,
268+
345,
269+
11,
270+
221,
271+
'further',
272+
'...'
273+
];
274+
275+
$array=['conf'=>['settings'=>['window' => 'open', 'door' => 'closed]]];
276+
```
277+
278+
### Strings
279+
280+
Whenever possible use single quotes `'` instead of double qoutes `"`. Try not to embedd variables in string. Concatenate them instead.
281+
282+
**Correct:**
283+
```php
284+
// simple text
285+
$var = 'This is a text';
286+
287+
// array index
288+
$array['index'] = 'value';
289+
290+
// text with variables
291+
$var = 'This is a text with ' . $value . ' values inside and at the end: ' . $sum_value;
292+
293+
// dynamic array index
294+
$idx = 'index' . $key;
295+
$value = $array[$idx];
296+
```
297+
298+
**Wrong:**
299+
```php
300+
// simple text
301+
$var = "This is a text";
302+
303+
// array index
304+
$array["index"] = 'value';
305+
306+
// text with variables
307+
$var = "This is a text with $value values inside and at the end: {$sum_value}";
308+
309+
// dynamic array index
310+
$value = $array['index' . $key];
311+
$value = $array["index{$key}"];
312+
```
313+
314+
# Where to store custom settings
315+
## Interface settings
97316
The recommended place to store global interface settings is the ini style global config system
98317
(see system.ini.master file in install/tpl/ to set defaults). The settings file
99318
gets stored inside the ispconfig database. Settings can be accessed with the function:
@@ -109,7 +328,6 @@ fields to the file interface/web/admin/form/system_config.tform.php and the corr
109328
tempalte file in the templates subfolder of the admin module.
110329

111330
## Server settings
112-
113331
Server settings are stored in the ini style server config system (see server.ini.master template file)
114332
The settings file gets stored inside the ispconfig database in the server table. Settings can be
115333
accessed with the function $app->getconf->get_server_config(....)

0 commit comments

Comments
 (0)