Skip to content

Contributing

This document describes the development guidelines and process for contributions to the calServer project.

Setting Up the Development Environment

Prerequisites

  • Docker and Docker Compose
  • Git
  • PHP 7.4 (for local analysis and IDE support)
  • Java 21 (only for changes to the Report Runner)

Local Setup

  1. Clone the repository:

    git clone git@bitbucket.org:calserver/calwebapp_yii1.git
cd calwebapp_yii1

  2. Configure environment variables:

    cp docker/.env.example docker/.env
# Adjust values in docker/.env

  3. Start containers:

    cd docker
docker-compose up -d

  4. Initialize the database:

    docker exec -it calserver ./httpdocs/protected/yiic migrate

The application is then accessible at the configured domain.

Git Workflow

Branch Strategy

The project uses a Git Flow-like workflow:

Branch Purpose
master Production state, only updated via releases
develop Integration branch for the next version
feature/<name> New features
bugfix/<name> Bug fixes
hotfix/<name> Urgent fixes to the production state
release/<version> Preparation of a release

Naming Conventions

  • Branch names in lowercase with hyphens: feature/dcc-xml-export
  • Issue reference in the branch name, if available: bugfix/1234-fix-grid-sorting

Commit Messages

Commit messages follow this format:

<type>: <short description>

<Optional detailed description>

Refs #<issue-number>

Types:

Type Usage
feat New feature
fix Bug fix
refactor Code restructuring without functional change
docs Documentation changes
test Adding or modifying tests
chore Build scripts, dependencies, configuration

Code Standards

PHP

  • Indentation: Tabs
  • Braces: Opening brace on the same line
  • Naming: CamelCase for classes, camelCase for methods and variables
  • Yii conventions: Controller actions as actionMethodName, models with table name
  • No unnecessary use statements -- Yii 1.1 uses import in the configuration

Database Migrations

Schema changes are made exclusively via Yii migrations:

./yiic migrate create <description>

Each migration must implement an up() and a down() method.

Frontend

  • JavaScript: jQuery (provided by the Yii framework)
  • CSS: Bootstrap 3 (via the Booster extension)
  • Templates: Yii PHP views under views/

Pull Request Process

  1. Create a feature or bugfix branch from develop
  2. Implement the changes with meaningful commits
  3. Ensure that existing tests continue to pass
  4. Create a pull request against develop
  5. Describe the change, the reason, and the test coverage in the PR
  6. Wait for a code review by at least one reviewer
  7. After approval, the branch is merged into develop

Review Criteria

  • Code adheres to the described standards
  • Database migrations are present and reversible
  • No hard-coded configuration values
  • Tenant isolation is maintained
  • Permission checks are present

Testing

Test Types

Type Tool Directory
Unit tests PHPUnit httpdocs/protected/tests/
Acceptance tests Behat httpdocs/protected/features/
API tests Behat httpdocs/protected/features/api/
Report Runner tests JUnit report-runner/src/test/

Running Tests

# PHPUnit
docker exec -it calserver ./httpdocs/protected/vendor/bin/phpunit

# Behat
docker exec -it calserver ./httpdocs/protected/vendor/bin/behat

Documentation

The documentation is built with MkDocs Material and is located under docs/. Local preview:

pip install -r requirements-docs.txt
mkdocs serve

When adding new pages, the entry must be added in mkdocs.yml under nav:.