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.
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!
Comments¶
We document important parts of the code especially if they are not obvious at first glance.