Skip to content

Contributing

Interested in contributing to Control Center? Adding a new, favourite feature? Say no more.

Running the development environment

This part will explain how to create a development instance of Control Center in a docker container. Our development container is based on Laravel Sail tailored for Control Center. It run a Docker Devcontainer which mounts the project inside the container. The container is built to be run on a Linux distro or using Docker Desktop with WSL2 on Windows.

Setup the container

Clone the repository to a location locally if on Linux or if on Windows clone it using git clone https://github.com/Vatsim-Scandinavia/controlcenter.git inside your WSL terminal.

When the repository has been cloned you need to create your .env file which will contain the configuration for your local environment. We recommend copying and renaming .env.example and modify it to your liking.

Once the environment has been configured you can start the development environment using ./sail up. This creates the neccesary containers to run Control Center locally. Once these are started it's recommended to run ./sail bash ./init-dev.sh to run the initial setup such as downloading/building NPM assets, running database migration etc. These commands may also be run manually inside the container if preffered.

Tip

If using Visual Code as your editor you may also use the extension Remote Explorer to run the development environment.

Resetting the containers

Should you find the need to start over. Then you can re-run the init-dev.sh script which will redo the initial setup once again.

Tooling

If you'd like better editor integration, you can generate helper definitions for Laravel.

./sail artisan ide-helper:generate

Caching

This application uses the OPCache to cache the compiled PHP code. The default setting is for production use, which means that the cache is not cleared automatically. To clear the cache, you need to restart the container if you change a file.

For development, change validate_timestamps to 1 in the /usr/local/etc/php/php.ini file to make sure that the cache is cleared automatically when a file is changed.

Run unit tests

First run

On first run you might need to setup the testing sqlite database first. Run the command ./sail artisan migrate --database sqlite-testing to setup the database.

Test

To run the PHP unit tests use:

./sail artisan test

To create new tests, you can use the helper, which by default creates feature tests rather than unit tests:

./sail artisan make:test

The tests run with the local SQLite test database, not your development database.

Quicker feedback during development

Install the pre-commit project locally and you'll be able to take advantage of our pre-commit hooks. They help you keep formatting consistent and avoid mistakes that'll be caught by the continous integration tests.

Tip

This isn't required, but recommended to get an improved feedback loop while developing.

Run formatting

To run the formatting script that ensures consistent Laravel PHP code use ./sail pint.

Conventions

Contributions are much appreciated to help everyone evolve this service with fixes and functionalities. We recommend you to fork this repository here on GitHub so you can easily create pull requests back to the main project.

To keep a collaborative project in the same style and understandable, it's important to follow some conventions:

GitHub Branches

We name branches with feat/name-here, fix/name-here or misc/name-here, for instance feat/new-api or fix/mentor-mail

Models/SQL

  • MySQL tables are named in plural e.g training_reports, not training_report
  • Models are named in singular e.g. Training, not Trainings
  • Models names don't have any specific suffix or prefix
  • Models are located in root of App/Models folder.

Controllers

  • Controllers are suffixed with Controller, for instance TrainingController
  • Controllers are named in singular e.g. TrainingController, not TrainingsController
  • The controllers should mainly consist of the methods of "7 restful controller actions" Check out this video

Other

  • We name our views with blade suffix for clarity, like header.blade.php
  • For more in-depth conventions which we try to follow, check out Laravel best practices
  • We tab with 4 spaces for increased readability
  • The service language is UK English

Contributing to the documentation

To get started with the documentation locally you will need Python and PDM installed. The docs are generated and pushed to the gh-pages branch.

To build and preview the documentation locally, here's a quick start set of instructions:

Getting started with docs tools
cd docs/  # (1)!
pdm install  # (2)!
  1. Enter the documentation folder.
  2. Install the dependencies for the documentation setup.

You'll now need to run two different commands, one in the background and one in the foreground. Open two terminals in the same docs/ folder:

Viewing the documentation locally
pdm run docs:serve

This will start a local web server, allowing you to view the current documentation via localhost:8000, together with the documentation you build locally.

Proceed to the next step after you've made changes to the documentation.

Building the documentation locally
pdm run docs:build

Re-run pdm run mike deploy dev whenever you've made any changes to the documentation. The changes will only be visible in /dev/.

You can also create multiple versions in parallel by replacing dev with something else.