Code style fixes (Documentation).

This commit is contained in:
Dmitry Khomutov 2017-07-18 20:54:24 +07:00
parent 1914ec177c
commit 80b7a368b1
No known key found for this signature in database
GPG key ID: 7EB36C9576F9ECB9
29 changed files with 115 additions and 54 deletions

View file

@ -1,9 +1,11 @@
Environments
============
A environment can include several branches - base branch (default project branch) and optional additional branches (which merge into base).
A environment can include several branches - base branch (default project branch) and optional additional branches
(which merge into base).
When you commit to a branch, builds all environments in which branch included (base branch implicitly included to all environments).
When you commit to a branch, builds all environments in which branch included (base branch implicitly included to all
environments).
When you build a environment, additional branches merged into base branch.

View file

@ -1,7 +1,8 @@
Injecting variables into messages
=================================
Most strings used in the build configuration can have variables related to the build inserted into them with the following syntax:
Most strings used in the build configuration can have variables related to the build inserted into them with the
following syntax:
"My important message is about %SOMETHING%"

View file

@ -11,7 +11,8 @@ Configuration
- **args** [string, optional] - Allows you to pass command line arguments to Atoum.
- **config** [string, optional] - Path to an Atoum configuration file.
- **directory** [string, optional] - Path in which to run Atom (defaults to the build root).
- **executable** [string, optional] - Allows you to provide a path to the Atom binary (defaults to PHP Censor root, vendor/bin, or a system-provided Atom binary).
- **executable** [string, optional] - Allows you to provide a path to the Atom binary (defaults to PHP Censor root,
vendor/bin, or a system-provided Atom binary).
### Examples
```yml

View file

@ -8,7 +8,8 @@ Configuration
### Options
- **executable** [string, optional] - Allows you to provide a path to the Behat binary (defaults to PHP Censor root, vendor/bin, or a system-provided Behat binary).
- **executable** [string, optional] - Allows you to provide a path to the Behat binary (defaults to PHP Censor root,
vendor/bin, or a system-provided Behat binary).
- **features** [string, optional] - Provide a list of Behat features to run.
### Examples

View file

@ -1,7 +1,8 @@
Plugin Campfire
===============
This plugin joins a [Campfire](https://campfirenow.com/) room and sends a user-defined message, for example a "Build Succeeded" message.
This plugin joins a [Campfire](https://campfirenow.com/) room and sends a user-defined message, for example a
"Build Succeeded" message.
Configuration
-------------

View file

@ -1,7 +1,8 @@
Plugin Clean build
==================
Works through a list of files to remove from your build. Useful when used in combination with Copy Build or Package Build.
Works through a list of files to remove from your build. Useful when used in combination with Copy Build or Package
Build.
Configuration
-------------

View file

@ -8,9 +8,13 @@ Configuration
### Options
* **config** - Required - Can be either a single string pointing to a Codeception configuration file, or an array of configuration file paths. By default this is called `codeception.yml` and will be in the root of your project.
* **config** - Required - Can be either a single string pointing to a Codeception configuration file, or an array of
configuration file paths. By default this is called `codeception.yml` and will be in the root of your project.
* **args** - Optional - The string of arguments to be passed to the run command.**Important**, due to the assumption made on line 132 regarding the value of `--xml` being the next argument which will not be correct if the user provides arguments using this config param, you must specify `report.xml` before any user input arguments to satisfy the report processing on line 146.
* **args** - Optional - The string of arguments to be passed to the run command.**Important**, due to the assumption
made on line 132 regarding the value of `--xml` being the next argument which will not be correct if the user provides
arguments using this config param, you must specify `report.xml` before any user input arguments to satisfy the report
processing on line 146.
* **path** - Optional - The path from the root of your project to the root of the codeception `_output` directory

View file

@ -1,7 +1,8 @@
Plugin Composer
===============
Allows you to run Composer within your build, to install dependencies prior to testing. Best run as a "setup" stage plugin.
Allows you to run Composer within your build, to install dependencies prior to testing. Best run as a "setup" stage
plugin.
Configuration
-------------
@ -10,10 +11,13 @@ Configuration
* **directory** [optional, string] - Directory within which you want Composer to run (default: build root)
* **action** [optional, string, update|install] - Action you wish Composer to run (default: 'install')
* **prefer_dist** [optional, bool, true|false] - whether Composer should run with the `--prefer-dist` flag (default: false)
* **prefer_source** [optional, bool, true|false] - whether Composer should run with the `--prefer-source` flag (default: false)
* **prefer_dist** [optional, bool, true|false] - whether Composer should run with the `--prefer-dist` flag
(default: false)
* **prefer_source** [optional, bool, true|false] - whether Composer should run with the `--prefer-source` flag
(default: false)
* **no_dev** [optional, bool, true|false] - whether Composer should run with the `--no-dev` flag (default: false)
* **ignore_platform_reqs** [optional, bool, true|false] - whether Composer should run with the `--ignore-platform-reqs` flag (default: false)
* **ignore_platform_reqs** [optional, bool, true|false] - whether Composer should run with the `--ignore-platform-reqs`
flag (default: false)
### Examples
@ -28,7 +32,9 @@ setup:
Warning
-------
If you are using a Composer private repository like Satis, with HTTP authentication, you must check your username and password inside the ```auth.json``` file. PHP Censor uses the ```--no-interaction``` flag, so it will not warn if you must provide that info.
If you are using a Composer private repository like Satis, with HTTP authentication, you must check your username and
password inside the ```auth.json``` file. PHP Censor uses the ```--no-interaction``` flag, so it will not warn if you
must provide that info.
For more info, please check the Composer documentation.

View file

@ -1,7 +1,8 @@
Plugin Copy Build
=================
Copies all files from your build, with the exception of those in the "ignore" build settings property, to a directory of your choosing.
Copies all files from your build, with the exception of those in the "ignore" build settings property, to a directory
of your choosing.
Configuration
-------------

View file

@ -10,7 +10,8 @@ Configuration
* **webhook_url** [required, string] - The URL to your Deployer WebHook
* **reason** [optional, string] - Your deployment message. Default - PHP Censor Build #%BUILD% - %COMMIT_MESSAGE%
* **update_only** [optional, bool, true|false] - Whether the deployment should only be run if the currently deployed branches matches the one being built. Default - true
* **update_only** [optional, bool, true|false] - Whether the deployment should only be run if the currently deployed
branches matches the one being built. Default - true
### Examples

View file

@ -14,7 +14,8 @@ Configuration
* **cc** - A list of addresses that will receive a copy of every emails sent.
* **template** - The template to use, options are short and long. Default is short on success and long otherwise.
**Note:** _This plugin will only work if you configured email settings during installation or configured them later in [`config.yml`](../configuring.md)._
**Note:** _This plugin will only work if you configured email settings during installation or configured them later in
[`config.yml`](../configuring.md)._
### Examples
See [Adding PHP Censor Support to Your Projects](../configuring_project.md) for more information about how to configure plugins.

View file

@ -9,7 +9,8 @@ Configuration
### Options
- **directory** [string, optional] - The directory in which to run Grunt (defaults to build root.)
- **grunt** [string, optional] - Allows you to provide a path to Grunt (defaults to PHP Censor root, vendor/bin, or a system-provided Grunt).
- **grunt** [string, optional] - Allows you to provide a path to Grunt (defaults to PHP Censor root, vendor/bin, or a
system-provided Grunt).
- **gruntfile** [string, optional] - Gruntfile to run (defaults to `Gruntfile.js`).
- **task** [string, optional] - The Grunt task to run.

View file

@ -1,7 +1,8 @@
Plugin Hipchat Notify
=====================
This plugin joins a [HipChat](https://www.hipchat.com/) room and sends a user-defined message, for example a "Build Succeeded" message.
This plugin joins a [HipChat](https://www.hipchat.com/) room and sends a user-defined message, for example a
"Build Succeeded" message.
Configuration
-------------
@ -11,10 +12,12 @@ Configuration
| Field | Required? | Description |
|-------|-----------|-------------|
| `authToken` | Yes | Your HipChat API authentication token (v1) |
| `room` | Yes | Your Hipchat room name or ID number. This can also be an array of room names or numbers, and the message will be sent to all rooms. |
| `room` | Yes | Your Hipchat room name or ID number. This can also be an array of room names or numbers, and the
message will be sent to all rooms. |
| `message` | No | The message to send to the room. Default - `%PROJECT_TITLE% built at %BUILD_URI%` |
| `color` | No | Message color. Valid values: yellow, green, red, purple, gray, random. Default - `yellow`|
| `notify` | No | Whether or not this message should trigger a notification for people in the room (change the tab color, play a sound, etc). Default - `false`. |
| `notify` | No | Whether or not this message should trigger a notification for people in the room (change the tab
color, play a sound, etc). Default - `false`. |
Message can be formatted via HTML. Example:
```html

View file

@ -10,7 +10,8 @@ Configuration
- **directory** [string, optional] - A single path in which you wish to lint files.
- **directories** [array, optional] - An array of paths in which you wish to lint files. This overrides `directory`.
- **recursive** [bool, optional] - Whether or not you want to recursively check sub-directories of the above (defaults to true).
- **recursive** [bool, optional] - Whether or not you want to recursively check sub-directories of the above (defaults
to true).
### Examples

View file

@ -22,7 +22,8 @@ Configuration
### Examples
Simple example where PHPCS will run on app directory, but ignore the views folder, and use PSR-1 and PSR-2 rules for validation:
Simple example where PHPCS will run on app directory, but ignore the views folder, and use PSR-1 and PSR-2 rules for
validation:
```yml
test:
php_code_sniffer:

View file

@ -12,7 +12,8 @@ Configuration
### Example
Run PHPLoc against the app directory only. This will prevent inclusion of code from 3rd party libraries that are included outside of the app directory.
Run PHPLoc against the app directory only. This will prevent inclusion of code from 3rd party libraries that are
included outside of the app directory.
```yml
test:

View file

@ -8,11 +8,14 @@ Configuration
### Options
- **allowed_warnings** [int, optional] - The warning limit for a successful build (default: 0). -1 disables warnings. Setting allowed_warnings in conjunction with zero_config will override zero_config.
- **allowed_warnings** [int, optional] - The warning limit for a successful build (default: 0). -1 disables warnings.
Setting allowed_warnings in conjunction with zero_config will override zero_config.
- **suffixes** [array, optional] - An array of file extensions to check (default: 'php')
- **ignore** [array, optional] - An array of files/paths to ignore (default: build_settings > ignore)
- **path** [string, optional] - Directory in which PHPMD should run (default: build root)
- **rules** [array, optional] - Array of rulesets that PHPMD should use when checking your build or a string containing at least one slash, will be treated as path to PHPMD ruleset. See http://phpmd.org/rules/index.html for complete details on the rules. (default: ['codesize', 'unusedcode', 'naming']).
- **rules** [array, optional] - Array of rulesets that PHPMD should use when checking your build or a string containing
at least one slash, will be treated as path to PHPMD ruleset. See http://phpmd.org/rules/index.html for complete
details on the rules. (default: ['codesize', 'unusedcode', 'naming']).
- **zero_config** [bool, optional] - Suppresses build failure on errors and warnings if set to true. (default: false).
### Examples

View file

@ -1,7 +1,8 @@
Plugin PHP Parallel Lint
========================
Similar to the [standard PHP Lint plugin](lint.md), except that it uses the [PHP Parallel Lint](https://github.com/JakubOnderka/PHP-Parallel-Lint) project to run.
Similar to the [standard PHP Lint plugin](lint.md), except that it uses the
[PHP Parallel Lint](https://github.com/JakubOnderka/PHP-Parallel-Lint) project to run.
Configuration
-------------

View file

@ -16,7 +16,8 @@ Its activated if you have phpunit.xml file in your build path, `tests/` subfolde
* **config** - Optional - Path to a PHP Unit XML configuration file.
* **run_from** - Optional - When running PHPUnit with an XML config, the command is run from this directory
* **coverage** - Optional - Value for the `--coverage-html` command line flag.
* **path** - Optional - In cases where tests files are in a sub path of the /tests path, allows this path to be set in the config.
* **path** - Optional - In cases where tests files are in a sub path of the /tests path, allows this path to be set in
the config.
#### Running Tests By Specifying Directory
@ -39,8 +40,10 @@ test:
Troubleshooting
---------------
If standard logging of PHP Censor is not enough, to get standard output from any command, including PHPUnit, edit `BaseCommandExecutor::executeCommand()` to see what exactly is wrong
If standard logging of PHP Censor is not enough, to get standard output from any command, including PHPUnit, edit
`BaseCommandExecutor::executeCommand()` to see what exactly is wrong
* Run `composer update` in phpunit plugin directory of PHP Censor to get all of its dependencies
* If phpunit is inside of the project's composer.json, it might interfere with PHP Censor's phpunit installation
* Make sure you have XDebug installed.`The Xdebug extension is not loaded. No code coverage will be generated.`
Otherwise test report parsing in `TapParser` will fail, wanting coverage report as well `Invalid TAP string, number of tests does not match specified test count.`
Otherwise test report parsing in `TapParser` will fail, wanting coverage report as well `Invalid TAP string, number of
tests does not match specified test count.`

View file

@ -12,7 +12,8 @@ Configuration
### Example
Run PHPLoc against the app directory only. This will prevent inclusion of code from 3rd party libraries that are included outside of the app directory.
Run PHPLoc against the app directory only. This will prevent inclusion of code from 3rd party libraries that are
included outside of the app directory.
```yml
test:

View file

@ -1,7 +1,8 @@
Plugin Slack Notify
===================
This plugin joins a [Slack](https://www.slack.com/) room and sends a user-defined message, for example a "Build Succeeded" message.
This plugin joins a [Slack](https://www.slack.com/) room and sends a user-defined message, for example a "Build
Succeeded" message.
Configuration
-------------
@ -13,8 +14,10 @@ Configuration
| `webhook_url` | Yes | The URL to your Slack WebHook |
| `room` | No | Your Slack room name. Default - #php-censor |
| `username` | No | The name to send the message as. Default - PHP Censor |
| `icon` | No | The URL to the user icon or an emoji such as :ghost:. Default - The value configured on Slack's WebHook setup |
| `message` | No | The message to send to the room. Default - `<%PROJECT_URI%|%PROJECT_TITLE%> - <%BUILD_URI%|Build #%BUILD%> has finished for commit <%COMMIT_URI%|%SHORT_COMMIT% (%COMMIT_EMAIL%)> on branch <%BRANCH_URI%|%BRANCH%>` |
| `icon` | No | The URL to the user icon or an emoji such as :ghost:. Default - The value configured on Slack's
WebHook setup |
| `message` | No | The message to send to the room. Default - `<%PROJECT_URI%|%PROJECT_TITLE%> - <%BUILD_URI%|Build
#%BUILD%> has finished for commit <%COMMIT_URI%|%SHORT_COMMIT% (%COMMIT_EMAIL%)> on branch <%BRANCH_URI%|%BRANCH%>` |
| `show_status` | No | Whether or not to append the build status as an attachment in slack. Default - true
### Examples

View file

@ -7,8 +7,10 @@ Configuration
-------------
### Options
* **allowed_errors** [int, optional] - The error limit for a successful build (default: 0). -1 disables errors. Setting allowed_errors in conjunction with zero_config will override zero_config.
* **allowed_errors** [int, optional] - The error limit for a successful build (default: 0). -1 disables errors. Setting
allowed_errors in conjunction with zero_config will override zero_config.
* **suffixes** [array, optional] - An array of file extensions to check (default: 'php')
* **directory** [string, optional] - directory to inspect (default: build root)
* **ignore** [array, optional] - directory to ignore (default: inherits ignores specified in setup)
* **searches** [array, optional] - Optional - Case-insensitive array of terms to search for. Defaults to TODO, TO DO, FIXME and FIX ME.
* **searches** [array, optional] - Optional - Case-insensitive array of terms to search for. Defaults to TODO, TO DO,
FIXME and FIX ME.

View file

@ -9,7 +9,7 @@ Requirements
Installation
------------
1. On debian system (for example) use aptitude command to install sendxmpp
1. On debian system (for example) use aptitude command to install `sendxmpp`
2. Add XMPP plugin in "complete" section of your `php-censor.yml`
Configuration
@ -17,13 +17,14 @@ Configuration
### Options
- username : Username of your XMPP sender account. (example : login@server.com)
- username : Username of your XMPP sender account. (example : "login@server.com")
- password : Password of your XMPP sender account.
- recipients : List of your XMPP recipents account.
- server : If your server is not the same that your login server (optional, example : gtalk.google.com)
- tls : Set 1 to enable TLS connection or 0 to disable it. (optional, default is 0)
- alias : Alias of your sender account. (optional)
- date_format : strftime mask date format display in notification message. (optional, default is %c of strftime function)
- date_format : `strftime` mask date format display in notification message. (optional, default is %c of strftime
function)
### Examples

View file

@ -1,7 +1,8 @@
Automatically building commits pushed to Bitbucket
==================================================
If you would like your builds to run automatically whenever there is a commit or other similar activity in your Bitbucket repository, perform the following steps:
If you would like your builds to run automatically whenever there is a commit or other similar activity in your
Bitbucket repository, perform the following steps:
1. Log into PHP Censor.
2. Click on your Bitbucket project.

View file

@ -10,7 +10,8 @@ Requirements
Installation
------------
1. Create a new file `post-receive` inside the [git `hooks` directory](http://www.git-scm.com/book/en/Customizing-Git-Git-Hooks) with the following content:
1. Create a new file `post-receive` inside the
[git `hooks` directory](http://www.git-scm.com/book/en/Customizing-Git-Git-Hooks) with the following content:
```shell
#!/bin/sh

View file

@ -1,7 +1,8 @@
Automatically building commits pushed to GitLab
===============================================
If you would like your builds to run automatically whenever there is a commit or other similar activity in your GitLab repository, perform the following steps:
If you would like your builds to run automatically whenever there is a commit or other similar activity in your
GitLab repository, perform the following steps:
1. Log into PHP Censor.
2. Click on your Gitlab project.
@ -10,5 +11,6 @@ If you would like your builds to run automatically whenever there is a commit or
5. Click the "settings" tab in the top right corner of the page.
6. Click on "Web Hooks".
7. Paste the link you copied from PHP Censor into the "URL" textbox.
8. Select the events which you want to trigger a PHP Censor build. The default and recommended setup is to only enable "push events."
8. Select the events which you want to trigger a PHP Censor build. The default and recommended setup is to only enable
"push events."
9. Click "Add Web Hook," and verify that the test was successful.

View file

@ -4,11 +4,14 @@ Project Status Images and Status Page
Status Image
------------
Most Continuous Integration systems provide a simple image URL that you can use to display your project status on other web sites (like Github) - PHP Censor is no different.
Most Continuous Integration systems provide a simple image URL that you can use to display your project status on other
web sites (like Github) - PHP Censor is no different.
You can find the status image at the following location: `http://{PHP_CENSOR_URL}/build-status/image/{PROJECT ID}`
So for example, our instance of PHP Censor is at `php-censor.local`, and our PHP Censor project ID is `2`, so the image URL is: `http://php-censor.local/build-status/image/2`.
So for example, our instance of PHP Censor is at `php-censor.local`, and our PHP Censor project ID is `2`, so the image
URL is: `http://php-censor.local/build-status/image/2`.
You can use additional parameters:
* style: plastic | flat (default) | flat-squared | social
@ -36,7 +39,8 @@ http://php-censor.local/build-status/view/2
### Where do I find my project ID?
Go to your instance of PHP Censor, and open the project you are interested in. The project ID is the number in the last part of the URL in your browser.
Go to your instance of PHP Censor, and open the project you are interested in. The project ID is the number in the last
part of the URL in your browser.
Example:
http://php-censor.local/project/view/2 ~> PROJECT ID: `2`

View file

@ -31,7 +31,8 @@ server {
Apache Example
--------------
For Apache, you can use a standard virtual host, as long as your server supports PHP. All you need to do is add the following to a `.htaccess` file in your PHP Censor `/public` directory.
For Apache, you can use a standard virtual host, as long as your server supports PHP. All you need to do is add the
following to a `.htaccess` file in your PHP Censor `/public` directory.
```
<IfModule mod_rewrite.c>

View file

@ -23,18 +23,25 @@ Setting up the PHP Censor worker
### On a new installation
Setting up the worker on a new installation of PHP Censor is as simple as entering the appropriate values for your Beanstalkd server hostname and queue name when running the PHP Censor installer. By default, the installer assumes that you'll be using beanstalkd on `localhost` and will use the queue name `php-censor-queue`.
Setting up the worker on a new installation of PHP Censor is as simple as entering the appropriate values for your
Beanstalkd server hostname and queue name when running the PHP Censor installer. By default, the installer assumes that
you'll be using beanstalkd on `localhost` and will use the queue name `php-censor-queue`.
### On an existing installation
On an existing installation, to set up the worker, you simply need to add the beanstalkd host and queue names directly into your `config.yml` file. You should add a `worker` key beneath the `php-censor` section, with the properties `host` and `queue` as outlined in the screenshot below:
On an existing installation, to set up the worker, you simply need to add the beanstalkd host and queue names directly
into your `config.yml` file. You should add a `worker` key beneath the `php-censor` section, with the properties `host`
and `queue` as outlined in the screenshot below:
Running the PHP Censor worker
-----------------------------
Once you've set up PHP Censor to add your jobs to a beanstalkd queue, you need to start the worker so that it can pick up and run your builds. On most servers, it is best to manage this using supervisord. The following instructions work on Ubuntu, but will need slight amendments for other distributions.
Once you've set up PHP Censor to add your jobs to a beanstalkd queue, you need to start the worker so that it can pick
up and run your builds. On most servers, it is best to manage this using supervisord. The following instructions work
on Ubuntu, but will need slight amendments for other distributions.
Using your preferred text editor, create a file named `php-censor.conf` under `/etc/supervisor/conf.d`. In it, enter the following config:
Using your preferred text editor, create a file named `php-censor.conf` under `/etc/supervisor/conf.d`. In it, enter
the following config:
```
[program:php-censor]
@ -49,9 +56,12 @@ environment=HOME="/home/php-censor",USER="php-censor"
numprocs=2
```
You'll need to edit the '/path/to/php-censor', the `user` value and the `environment` value to suit your server. The user needs to be an actual system user with suitable permissions to execute PHP and PHP Censor.
You'll need to edit the '/path/to/php-censor', the `user` value and the `environment` value to suit your server.
The user needs to be an actual system user with suitable permissions to execute PHP and PHP Censor.
Once you've created this file, simply restart supervisord using the command `service supervisor restart` and 2 instances of PHP Censor's worker should start immediately. You can verify this by running the command `ps aux | grep php-censor`, which should give you output as follows:
Once you've created this file, simply restart supervisord using the command `service supervisor restart` and 2
instances of PHP Censor's worker should start immediately. You can verify this by running the command
`ps aux | grep php-censor`, which should give you output as follows:
```
➜ ~ ps aux | grep php-censor
@ -65,6 +75,7 @@ Also you can simple daemonise worker by `nohup`:
nohup /path/to/php-censor/bin/console php-censor:worker &> /var/log/php-censor-worker.log </dev/null & # and you can save pid in pidfile with echo "$!" > /var/run/php-censor-worker.pid, but it's not really necessary
```
But keep in mind: it won't restart your worker if it fails and can be inconvenient to manage worker process in contrast with other solutions. So, it's good for debug purposes or as temporary solution.
But keep in mind: it won't restart your worker if it fails and can be inconvenient to manage worker process in contrast
with other solutions. So, it's good for debug purposes or as temporary solution.
That's it! Now, whenever you create a new build in PHP Censor, it should start building immediately.