SourceCode

the source code repository

RackTables project uses git as version control system for the source code. The git repository that is used to make "tar.gz" releases is currently hosted on GitHub. It includes the following notable branches:

master

The main development branch, that is, the default branch for all new changes.

maintenance-0.16.x

maintenance-0.17.x

maintenance-0.18.x

maintenance-0.19.x

Maintenance branches, that is, stable branches that serve as the base for RackTables releases.

Use the floowing commands to get a working copy of the repository:

# from the RackTables project repository
git clone git://github.com/RackTables/racktables.git
# or
git clone https://github.com/RackTables/racktables.git
# or
git clone ssh://git@github.com:RackTables/racktables.git

# from a GitHub fork (of your own or not)
git clone git://github.com/username/racktables.git
# or
git clone https://github.com/username/racktables.git
# or
git clone ssh://git@github.com:username/racktables.git

Note that the first two schemas (git:// and https://) are always read-only and the third (ssh://) may be read-only or read-write.

code style guide

RackTables source code consists of files in several programming languages with two main cases being PHP and JavaScript. Almost all PHP source code in RackTables is original and the following style guide applies:

use Allman indent style.

Why: Allman style is very diff-friendly when it comes to nested operators. In Allman style replacement of an inner operator with a code block (and vice versa) leaves both the inner and the outer operator untouched:

 for ($i = 0; $i < 10; $i++)
+{
 	doSomething ($i);
+	doSomethingElse();
+}

This works seamlessly at any indentation level and for all control operators (if/for/foreach/while), however deeply nested. With careful indentation of case within switch it will work same well:

switch ($var)
{
        case 1:
                doSomething();
                break;
        case 2:
                return 3;
        case 3:
        {
                doSomethingElse();
                return 4;
        }
}

Exception: inline (PHP heredoc) HTML, SQL and JS code.

use tabs for indentation

Use exactly one tab for one indentation level. Tabs are much better than spaces in that everyone can configure their own editor to display tab as N (2, 4, 8...) spaces.

Exception: inline (PHP heredoc) HTML, SQL and JS code.

things to consider when adding a new function

• First, is it possible to use one of the existing functions or a combination of these?
• Carefully decide which file the function should be in (depends on its purpose and relation to other functions).
• Consider headlessCamelCase for the function name.
• Try to keep functions focused, that is, small, doing just one thing but doing it very well.

---

Here is an example of a function:

// take port list with order applied and return uplink ports in the same format
function produceUplinkPorts ($domain_vlanlist, $portlist)
{
	$ret = array();
	$employed = array();
	foreach ($domain_vlanlist as $vlan_id => $vlan)
		if ($vlan['vlan_type'] == 'compulsory')
			$employed[] = $vlan_id;
	foreach ($portlist as $port_name => $port)
		if ($port['vst_role'] != 'uplink')
			foreach ($port['allowed'] as $vlan_id)
				if (!in_array ($vlan_id, $employed))
					$employed[] = $vlan_id;
	foreach ($portlist as $port_name => $port)
		if ($port['vst_role'] == 'uplink')
		{
			$employed_here = array();
			foreach ($employed as $vlan_id)
				if (matchVLANFilter ($vlan_id, $port['wrt_vlans']))
					$employed_here[] = $vlan_id;
			$ret[$port_name] = array
			(
				'vst_role' => 'uplink',
				'mode' => 'trunk',
				'allowed' => $employed_here,
				'native' => 0,
			);
		}
	return $ret;
}

examining local unsaved changes

git status
git diff

submitting work

In the case of a GitHub fork of RackTables publishing changes is as simple as using git push. To merge your changes into the upstream RackTables notify the dev team by any convenient mean (GitGub pull request or email).

In the case of a private repository use a git format-patch command to produce a patch and send it to the developers.