Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
181 lines (126 loc) · 5.1 KB

CONTRIBUTING.md

File metadata and controls

181 lines (126 loc) · 5.1 KB

How to contribute

You want to contribute to this project? Well thank you! That's very much appreciated! 🥰

In this page, we'll see how to setup the project so you can edit it in your IDE.

If you have doubts, questions or suggestions, you can contact us on Matrix at #mesamatrix:matrix.org.

Install locally

Prerequisites

Mesamatrix requires the following software:

Install steps

Clone the Mesamatrix repository:

git clone git@github.com:MightyCreak/mesamatrix.git

Jump into the directory and install all the dependencies with Composer:

cd mesamatrix
composer install

Configuration (optional)

There is a default config file in config/config.default.php. It provides default values for the application, but is overridden by the optional config/config.php.

For instance, to change the log level: create a config/config.php file and copy this contents:

<?php

use Monolog\Level;

$CONFIG = array(
  "info" => array(
    "log_level" => Level::Debug,
  ),
);

Initial setup

For the initial setup, run the mesamatrixctl tool to clone the Mesa Git repository and generate the XML file:

./mesamatrixctl setup

Update Mesa data

Once setup is done, you can run the two commands that are needed to get the latest information from Mesa:

./mesamatrixctl fetch
./mesamatrixctl parse

These commands can be put into a crontab or similar scheduling facility, for automated operation of your Mesamatrix installation.

Run the PHP server

As a developer, an easy way to spawn up a PHP server is by running this command:

php -S 0.0.0.0:8080 -t public

How to use the CLI tool

The mesamatrixctl tool can be used to administer your Mesamatrix installation. It outputs very little by default, but can become more verbose when passed -v, -vv or -vvv for normal output, verbose output or debug output respectively.

Run ./mesamatrixctl list to see the available commands, or ./mesamatrixctl help <command_name> for more detailed help.

setup command

Initializes Mesamatrix: clones the mesa repository. Must be called once.

fetch command

Pulls the latest commits from the Mesa git repository. Call it regularly to always be up to date.

parse command

Parses the latest commits and generates the XML used by the website.

Options:

  • -f/--force: Force to parse all the commits again
  • -r/--regenerate-xml: Regenerate the XML based on the already parsed commits

Coding style

Following the coding style of a project is important. It allows to have a more readable and maintainable code base. It's also useful for code reviews since there is no preference here, you simply have to follow the guidelines. And remember, you control your IDE and not the other way around! 😉

PHP

For PHP the project follows the PSR-12 coding style (except for the line limit, which was too constraining).

Javascript

  • Always use var for your variables
  • Use ' for strings

HTML

  • Use " for attributes

CSS

  • Don’t bind your CSS too much to your HTML structure and try to avoid IDs

IDE configuration

VSCode

The recommended extensions for this project are in .vscode/extensions.json. You don't have to install them all, it's simply recommended.

List of recommended extensions: