Developers guide

1. Intro

One of ways contributing to the Bacularis is preparing patches with bug fixes or new functions. If you decided to contribute to the project this way, below you can find couple of advises about how to prepare proposed changes.

2. General advices

The general advices refer to all type of files (.php, .js, .tpl, .page …others).

End of lines

The EOL (end of line) characters are always for every type of Bacularis files LF \n, not CRLF \r\n.

Indents

We use tabs \t for indentation, not spaces.

Comments

We document important parts of the code especially if they are not obvious at first glance.

3. PHP code

The PHP code advices refers to PHP files only.

Static code analysis

Before preparing pull request please execute static code analysis tests by running PHPStan command. Example below is to run in the main directory of the bacularis-web repository, but it needs to be run on every repository where are prepared new changes:

phpstan analyse Web

Coding style

Check if the code is compatible with the PSR-12 extended coding style standard. You can easily do it by using php-cs-fixer and running the command below in the main repo directory in which we prepared new changes.

php-cs-fixer fix -vvv --dry-run

We provide ready php-cs-fixer configuration file in the main directory of each base repository. It is a file .php-cs-fixer.dist.php.

If you use Composer to get Bacularis, both the static code analyse and coding style checkings can be done by running:

composer analyse

Documentation

PHP functions and classes need to be documented in the code by comments.

For one line comments in methods body we use //:

// My important comment

For multiple line comments we use /**/:

/**
 * My three lines very long comment.
 * It requires using multi-line comment type.
 * Here is something else.
 */

For documenting classes, methods and functions we use the PHPDoc style.

Function example:

/**
 * Get XYZ elements by given type.
 *
 * @param str $type element type
 * @return array XYZ elements
 */
 function getElementsByType($type)
 {
     ...
 }

Class example:

/**
 * Manage XYZ configuration.
 *
 * @author YOUR_FIRST_NAME YOUR_LAST_NAME <YOUR_EMAIL@ADDRESS>
 * @category SomeCategory
 */
 class XYZManager
 {
 }

License and copyright

New PHP files in the pull request starts with the following license statement:

/*
 * Bacularis - Bacula web interface
 *
 * Copyright (C) YEAR YOUR_FIRST_NAME YOUR_LAST_NAME
 *
 * You may use this file and others of this release according to the
 * license defined in the LICENSE file, which includes the Affero General
 * Public License, v3.0 ("AGPLv3") and some additional permissions and
 * terms pursuant to its AGPLv3 Section 7.
 */

Please put your first and last name in place YOUR_FIRST_NAME and YOUR_LAST_NAME. Also please replace YEAR in the current year.

If you add new PHP changes to existing files, please add in header your copyright note after existing copyright note, for example (for John Xyz):

Copyright (C) 2021-2023 Marcin Haba
Copyright (C) 2023 John Xyz

Pull requests

The pull requests can be prepared in the Bacularis project on GitHub using the GitHub flow described here:

https://docs.github.com/en/get-started/quickstart/github-flow

Thank you in advance for all your contributions!