Developer Guide

1. Development Process

1.1. Issue Resolution

1. Issue is identified: Anyone can identify an issue whether it be a bug, a tweak, or a new feature.

2. Identifier analyzes and reports the issue: Once the issue is identified, the person who identified the issue must collect as much information as possible to submit a complete report in the tracker.

3. Issue is confirmed: Once the issue is reported, a lead developer will review the report and confirm the issue if it is valid, adding any useful information to the report.

4. Issue is discussed: If the issue is not a straightforward bug fix, the issue will be discussed by the developers to determine an appropriate solution.

5. Issue is assigned to a developer: Based on the urgency of the issue, a lead developer will decide when and to whom to assign the issue.

6. Developer makes changes to development repository: Once a developer has been assigned to an issue, the developer will make the necessary changes to the development repository and test the changes. After the developer is satisfied with the changes, the developer will notify the maintainer by sending a reminder from the issue tracker. The reminder should include any information which will help the maintainer understand the changes.

7. Changes are reviewed by the maintainer: The maintainer will review the changes and determine if the changes have resolved the issue and ensure that it conforms with the coding standards. If more work is needed, the maintainer will inform the developer by adding notes to the report. This process will repeat until the maintainer determines the changes are complete.

8. Changes are merged with the main repository: The maintainer will then merge the developer's changes to the main Trellis repository including a message summarizing the changes applied.

9. Issue is resolved: The maintainer will then update the report to show a resolution has been committed.

1.2. Reporting Issues

In order to properly document and facilitate issue resolution, effective reports must be written. An effective report is precise, clear, and differentiates fact from speculation. Reports should address only one issue regardless of how trivial it may seem. Reports that are not feature requests should always include: what you did, what you wanted to happen, and what actually happened. The following table explains the different fields one fills out when submitting a new report.

For more information regarding best practices when reporting issues, check out the following resources.

• PHP Bugs: How to Report a Bug

• Bug writing guidelines - MDC

• How To Ask Questions The Smart Way

2. Coding Standards

2.1. Naming Conventions

In general, names should be descriptive and abbreviations should be avoided.

• Classes
  • Joined capitalized words
  • Trellis classes prefixed with "Trellis"

  • Examples: TrellisAuth, TrellisCourseObject

• Methods/Functions
  • All lowercased words separated by underscores
  • Examples: trellis_log
• Variables
  • Local
    • All lowercase words separated by underscores
  • Global
    • Similar to local variables except with the addition of a "TRELLIS_" prefix
    • Examples: TRELLIS_us_states
• Constants
  • All uppercase words separated by underscores
  • Prefixed with "TRELLIS_"

2.2. Indentation

All indentation is done with spaces. Each indent consists of four spaces. There should not be any tab characters in files. If you would like to use a tab in a string, use "\t".

2.3. Control Structures

Generally, braces used in control structures should appear on their own line with the same indentation as the control structures keyword. Parenthesized parameters should be spaced one space from the keyword, but there should be no space between the parentheses and their contents.

2.3.1. IF

if ($x == $y)
{
    return true;
}
else
{
    return false;
}

2.3.2. FOR

for ($i = 0; $i < $end; $i++)
{
    echo $array[$i];
}

2.3.3. SWITCH

switch ($color)
{
    case 'blue':
        $hex = '#0000FF';
        break;
    case 'red':
        $hex = '#FF0000';
        break;
    default:
        $hex = '#000000';
}

2.4. Arrays

An array can be formatted in one of two ways. The first is reserved for simple or small arrays. A simple array is one where none of the values of the array are other arrays. A small array is one that fits reasonably well on a single line. The format is as follows:

$array_simple_numeric     = array('item1', 'item2', 'item3');

$array_simple_associative = array('key1' => 'item1', 'key2' => 'item2', 'key3' => 'item3');

If the array is not simple or short, the secondary format is used.

$array_complex_numeric = array(
    'item1',
    'item2',
    'item3',
    'item4',
    'item5',
    'item6',
    'item7',
    'item8',
    'item9',
    );

$array_complex_associative = array(
    'key1' => 'item1',
    'key2' => 'item2',
    'key3' => array(
        'key3-1' => 'item3-1',
        'key3-2' => 'item3-2',
        'key3-3' => 'item3-3',
        ),
    );

• Remember: In associative arrays, the => should be aligned at each depth.

2.5. Comments