From dc87616e12c232a0a68445ec4fc111970dbf61c6 Mon Sep 17 00:00:00 2001 From: Dmitry Khomutov Date: Mon, 16 Apr 2018 22:35:44 +0700 Subject: [PATCH] Added more russian docs and small fixes. --- docs/en/README.md | 15 +++--- docs/en/environments.md | 18 ++++--- docs/en/interpolation.md | 45 +++++++++++------ docs/en/status.md | 8 +-- docs/ru/README.md | 106 +++++++++++++++++++++++++++++++++++++++ docs/ru/environments.md | 81 ++++++++++++++++++++++++++++++ docs/ru/interpolation.md | 40 +++++++++++++++ docs/ru/screenshots.md | 14 ++++++ docs/ru/status.md | 50 ++++++++++++++++++ 9 files changed, 345 insertions(+), 32 deletions(-) create mode 100644 docs/ru/README.md create mode 100644 docs/ru/environments.md create mode 100644 docs/ru/interpolation.md create mode 100644 docs/ru/screenshots.md create mode 100644 docs/ru/status.md diff --git a/docs/en/README.md b/docs/en/README.md index 3b71e9dc..e5a8e0c9 100644 --- a/docs/en/README.md +++ b/docs/en/README.md @@ -1,4 +1,4 @@ -PHP Censor documentation +PHP Censor Documentation ======================== Getting Started @@ -24,14 +24,14 @@ Using PHP Censor * Mercurial/Hg * Bitbucket (Hg) * Subversion/Svn -* [Injecting variables into messages](interpolation.md) -* [Project Status Images and Status Page](status.md) -* [Build environments](environments.md) +* [Injecting Variables into Messages](interpolation.md) +* [Project Public Status Image and Page](status.md) +* [Project Environments](environments.md) Plugins ------- -### Internal plugins +### Internal Plugins #### Dependencies @@ -46,7 +46,7 @@ Plugins * [PHP Unit](plugins/php_unit.md) - `php_unit` * [PHP Spec](plugins/php_spec.md) - `php_spec` -#### Code style +#### Code Style * [Lint](plugins/lint.md) - `lint` * [PDepend](plugins/pdepend.md) - `pdepend` @@ -97,9 +97,10 @@ Plugins * [Shell](plugins/shell.md) - `shell` * Wipe - `wipe` -### Third-party plugins +### Third-party Plugins * [Telegram](https://github.com/php-censor/php-censor-telegram-plugin) - Telegram plugin by [@LEXASOFT](https://github.com/LEXASOFT) + * [Deployer](https://github.com/php-censor/php-censor-deployer-plugin) - Plugin for [Deployer](http://deployer.org) by [@ketchoop](https://github.com/ketchoop) diff --git a/docs/en/environments.md b/docs/en/environments.md index 2c46d583..b02d85fe 100644 --- a/docs/en/environments.md +++ b/docs/en/environments.md @@ -1,5 +1,5 @@ -Environments -============ +Project Environments +==================== A environment can include several branches - base branch (default project branch) and optional additional branches (which merge into base). @@ -11,6 +11,7 @@ When you build a environment, additional branches merged into base branch. For example, it can be useful when you delay merging into master or test some branches at once. Or deploy. + Config example and explanation ------------------------------ Configuration is specified on project edit page. @@ -56,9 +57,12 @@ Webhooks to include branches in the environment Prepare project in GOGS web-admin: -* Create webhook -* Set "Payload URL" to php-censor webhook URL `http://domain.tld/webhook/gogs/project` -* Enable triggering "Pull request" -* Create labels for your environments in the format: "env:environment-name", for example "env:test" +* Create webhook. -After creating the pull request, to include the branch in the environment, add the appropriate labels. +* Set "Payload URL" to php-censor webhook URL like: `http://php-censor.local/webhook/gogs/`. + +* Enable triggering "Pull request". + +* Create labels for your environments in the format: `env:` (For example `env:test`). + +* After creating the pull request, to include the branch in the environment, add the appropriate labels. diff --git a/docs/en/interpolation.md b/docs/en/interpolation.md index 5be4f178..5d7b8683 100644 --- a/docs/en/interpolation.md +++ b/docs/en/interpolation.md @@ -4,19 +4,36 @@ 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: -"My important message is about %SOMETHING%" +``` +"My important message is about %VARIABLE%" +``` -Where something can be one of the following: +Where `VARIABLE` can be one of the following: -* **COMMIT** - The commit hash -* **SHORT_COMMIT** - The shortened version of the commit hash -* **COMMIT_EMAIL** - The email address of the committer -* **COMMIT_MESSAGE** - The message written by the committer -* **COMMIT_URI** - The URL to the commit -* **BRANCH** - The name of the branch -* **BRANCH_URI** - The URL to the branch -* **PROJECT** - The ID of the project -* **BUILD** - The build number -* **PROJECT_TITLE** - The name of the project -* **BUILD_PATH** - The path to the build -* **BUILD_URI** - The URL to the build in PHP Censor +* **COMMIT** - The commit hash. + +* **SHORT_COMMIT** - The shortened version of the commit hash. + +* **COMMIT_EMAIL** - The Email address of the committer. + +* **COMMIT_MESSAGE** - The message written by the committer. + +* **COMMIT_URI** - The URL to the commit. + +* **BRANCH** - The name of the branch. + +* **BRANCH_URI** - The URL to the branch. + +* **ENVIRONMENT** - Build environment (See [environments](environments.md)). + +* **PROJECT** - The ID of the project. + +* **BUILD** - The build number. + +* **PROJECT_TITLE** - The name of the project. + +* **PROJECT_URL** - The URL to the project in PHP Censor. + +* **BUILD_PATH** - The path to the build. + +* **BUILD_URI** - The URL to the build in PHP Censor. diff --git a/docs/en/status.md b/docs/en/status.md index e4991a05..925ce8c7 100644 --- a/docs/en/status.md +++ b/docs/en/status.md @@ -1,7 +1,7 @@ -Project Status Images and Status Page -===================================== +Project Public Status Image and Page +==================================== -Status Image +Status image ------------ Most Continuous Integration systems provide a simple image URL that you can use to display your project status on other @@ -27,7 +27,7 @@ Example: ![](http://php-censor.local/build-status/image/2?style=flat-squared&maxAge=3600) -Status Page +Status page ----------- PHP Censor also provides a public project status page, that is accessible for everyone. diff --git a/docs/ru/README.md b/docs/ru/README.md new file mode 100644 index 00000000..674c3ec3 --- /dev/null +++ b/docs/ru/README.md @@ -0,0 +1,106 @@ +Документация PHP Censor +======================= + +Для начала +---------- + +* Установка PHP Censor (Смотри [README](../../README.md)) + * [Настройка веб-интерфейса](virtual_host.md) + * [Запуск сборок с помощью демона (Worker-а)](workers/worker.md) + * [Запуск сборок с помощью переодической задачи (Cronjob)](workers/cron.md) +* [Настройка проекта для сборки в PHP Censor](configuring_project.md) +* Обновление PHP Censor (Смотри [README](../../README.md)) +* [Настройка PHP Censor](configuring-application.md) + +Использование +------------- + +* Автоматическая сборка при пуше коммитов в репозиторий для: + * [Git](sources/git.md) + * [Github (Git)](sources/github.md) + * [Bitbucket (Git)](sources/bitbucket.md) + * [GitLab (Git)](sources/gitlab.md) + * Gogs (Git) + * Mercurial/Hg + * Bitbucket (Hg) + * Subversion/Svn +* [Использование переменных в конфигурации проекта](interpolation.md) +* [Бейдж (изображение) со статусом проекта и публичная страница статуса проекта](status.md) +* [Использование окружений для проекта](environments.md) + +Плагины +------- + +### Плагины, включенные в поставку + +#### Зависимости + +* [Composer](plugins/composer.md) - `composer` +* [Security Checker](plugins/security_checker.md) - Плагин для проверки наличия незакрытых уязвимостей в зависимостях +проекта с помощью SensioLabs Security Checker (`security_checker`). + +#### Тесты + +* [Atoum](plugins/atoum.md) - `atoum` +* [Behat](plugins/behat.md) - `behat` +* [Codeception](plugins/codeception.md) - `codeception` +* [PHP Unit](plugins/php_unit.md) - `php_unit` +* [PHP Spec](plugins/php_spec.md) - `php_spec` + +#### Стиль кода + +* [Lint](plugins/lint.md) - `lint` +* [PDepend](plugins/pdepend.md) - `pdepend` +* [PHP Code Sniffer](plugins/php_code_sniffer.md) - `php_code_sniffer` +* [PHP Copy/Paste Detector](plugins/php_cpd.md) - `php_cpd` +* [PHP Coding Standards Fixer](plugins/php_cs_fixes.md) - `php_cs_fixer` +* [PHP Docblock Checker](plugins/php_docblock_checker.md) - `php_docblock_checker` +* [PHP Loc](plugins/php_loc.md) - `php_loc` +* [PHP Mess Detector](plugins/php_mess_detector.md) - `php_mess_detector` +* [PHP Parallel Lint](plugins/php_parallel_lint.md) - `php_parallel_lint` +* PHP Tal Lint - `php_tal_lint` +* [Technical Debt](plugins/technical_debt.md) - `technical_debt` + +#### Базы данных + +* [MySQL](plugins/mysql.md) - `mysql` +* [PostgreSQL](plugins/pgsql.md) - `pgsql` +* [SQLite](plugins/sqlite.md) - `sqlite` + +#### Деплой + +* [Mage](plugins/mage.md) - `mage` +* [Mage v3](plugins/mage3.md) - `mage3` +* [Phing](plugins/phing.md) - `phing` +* [Deployer](plugins/deployer.md) - `deployer` + +#### Оповещение + +* [Campfire](plugins/campfire.md) - `campfire` +* [Email](plugins/email.md) - `email` +* FlowDock - `flowdock_notify` +* [HipChat](plugins/hipchat_notify.md) - `hipchat_notify` +* [IRC](plugins/irc.md) - `irc` +* [Slack](plugins/slack_notify.md) - `slack_notify` +* [XMPP](plugins/xmpp.md) - `xmpp` + +#### Другое + +* [Clean Build](plugins/clean_build.md) - `clean_build` +* [Copy Build](plugins/copy_build.md) - `copy_build` +* [Env](plugins/env.md) - `env` +* Git - `git` +* [Grunt](plugins/grunt.md) - `grunt` +* Gulp - `gulp` +* [Package Build](plugins/package_build.md) - `package_build` +* [Phar](plugins/phar.md) - `phar` +* [Shell](plugins/shell.md) - `shell` +* Wipe - `wipe` + +### Сторонние плагины, не включенные в поставку + +* [Telegram](https://github.com/php-censor/php-censor-telegram-plugin) - Плагин для оповещения о результатах сборки +проекта в Telegram (Автор: [@LEXASOFT](https://github.com/LEXASOFT)). + +* [Deployer](https://github.com/php-censor/php-censor-deployer-plugin) - Плагин для деплоя приложения с помощью +библиотеки [Deployer](http://deployer.org) (Автор: [@ketchoop](https://github.com/ketchoop)). diff --git a/docs/ru/environments.md b/docs/ru/environments.md new file mode 100644 index 00000000..914f69dc --- /dev/null +++ b/docs/ru/environments.md @@ -0,0 +1,81 @@ +Использование окружений для проекта +=================================== + +Окружение может включать несколько веток: основная ветка (ветка проекта по-умолчанию) и опционально дополнительные +ветки, которые будут влиты в основную ветку при клонировании репозитория (Дополнительных веток может быть больше +одной, все они будут влиты в основную по очереди). + +Когда код пушится в какую-либо ветку, создаются сборки со всеми окружениями, включающими данную ветку (Основная ветка +неявно связана со всеми окружениями). + +Это может быть полезно например, когда нужно отложить вливание ветки в `master`-ветку в репозитории или +необходимо протестировать несколько веток вместе. Так же это может пригодится при деплое. + + +Примеры конфигурации и пояснения +-------------------------------- + +Конфигурирование окружений производится через веб-интерфейс на странице создания/редактирования проекта. + +Ниже пример для проекта с 3мя окружениями: + +* Production (`pr`) - Связан с веткой проекта по-умолчанию (Например: `master`. По сути обычная сборка без слияния +веток). + +* Release candidate (`rc`) - В основную ветку (`master`) вливается ветка `feature-A`. + +* Test (`test`) - В основную ветку (`master`) вливается ветка `feature-B` + +```yml +pr: +rc: + - feature-A +test: + - feature-B +``` + +Если код пушится в ветку `master`, то создается 3 сборки по одной на каждое окружение. + +Если код пушится в ветку `feature-A`, то создается одна сборка с окружением `rc` (То же самое произойдет и для ветки +`feature-B`, только сборка будет с окружением `test`). + +Если код пушится в ветку `feature-C`, которая не связаны ни с одним окружением, то создастся одна обычная сборка (Так +же как, если бы окружения не были настроены вовсе). + + +Использование переменной %ENVIRONMENT% в конфигурации проекта +------------------------------------------------------------- + +Вы можете получить и использовать текущее окружение с помощью переменной `%ENVIRONMENT%` (Смотри [Использование +переменных в конфигурации проекта](interpolation.md)). Например: + +```yml +setup: + mysql: + - "DROP DATABASE IF EXISTS project_name_%ENVIRONMENT%;" + - "CREATE DATABASE project_name_%ENVIRONMENT%;" +test: + ... +deploy: + mage: + env: %ENVIRONMENT% +``` + + +Добавление веток в окружение с помощью webhook-а +------------------------------------------------ + +### Gogs + +Необходимо подготовить проект в веб-интерфейсе Gogs: + +* Создать webhook для проекта. + +* Установить в поле "Payload URL" URL-адрес webhook-а для Gogs из PHP Censor (Например: +`http://php-censor.local/webhook/gogs/`). + +* Включить отправку события "Pull request". + +* Создать метки (labels) для ваших окружений в формате: `env:` (Например: `env:test`). + +* После создания запроса на слияние для добавления ветки в окружение, добавьте необходимые метки. diff --git a/docs/ru/interpolation.md b/docs/ru/interpolation.md new file mode 100644 index 00000000..4beeea91 --- /dev/null +++ b/docs/ru/interpolation.md @@ -0,0 +1,40 @@ +Использование переменных в конфигурации проекта +=============================================== + +Большое количество строковых параметров, используемых при сборке проекта имеют соответствующие переменные. Эти +переменные можно использовать в различных сообщениях и параметрах сборки, используя следующий синтаксис: + +``` +"Важное сообщение о %VARIABLE%" +``` + +Где `VARIABLE` может принимать следующее название: + + +* **COMMIT** - Идентификатор коммита сборки (Хэш коммита). + +* **SHORT_COMMIT** - Укороченная версия идентификатор коммита сборки (Укороченный хэш коммита). + +* **COMMIT_EMAIL** - Email-адрес автора коммита. + +* **COMMIT_MESSAGE** - Сообщение коммита. + +* **COMMIT_URI** - URL-адрес коммита. + +* **BRANCH** - Название ветки сборки. + +* **BRANCH_URI** - URL-адрес ветки. + +* **ENVIRONMENT** - Окружение сборки (Смотри [окружения](environments.md)). + +* **PROJECT** - ID проекта в PHP Censor. + +* **BUILD** - ID сборки в PHP Censor. + +* **PROJECT_TITLE** - Название проекта. + +* **PROJECT_URL** - URL-адрес проекта в PHP Censor. + +* **BUILD_PATH** - Путь к директории сборки. + +* **BUILD_URI** - URL-адрес сборки в PHP Censor. diff --git a/docs/ru/screenshots.md b/docs/ru/screenshots.md new file mode 100644 index 00000000..eb4befde --- /dev/null +++ b/docs/ru/screenshots.md @@ -0,0 +1,14 @@ +Скриншоты +========= + +[![Страница логина](../screenshots/login.png)](../screenshots/login.png) + +[![Панель управления](../screenshots/dashboard.png)](../screenshots/dashboard.png) + +[![Страница проекта](../screenshots/project.png)](../screenshots/project.png) + +[![Лог сборки](../screenshots/build-log.png)](../screenshots/build-log.png) + +[![Ошибки сборки](../screenshots/build-errors.png)](../screenshots/build-errors.png) + +[![Дополнительная информация сборки](../screenshots/build-information.png)](../screenshots/build-information.png) diff --git a/docs/ru/status.md b/docs/ru/status.md new file mode 100644 index 00000000..01c6074e --- /dev/null +++ b/docs/ru/status.md @@ -0,0 +1,50 @@ +Project Status Image 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. + +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`. + +You can use additional parameters: + +* style: plastic | flat (default) | flat-squared | social +* label: build (default) +* logo +* logoWidth +* link +* maxAge + +[See more on shields.io site](http://shields.io) + +Example: + +![](http://php-censor.local/build-status/image/2?style=flat-squared&maxAge=3600) + +Status Page +----------- + +PHP Censor also provides a public project status page, that is accessible for everyone. + +You can find the status page at the following location: `http://{PHP_CENSOR_URL}/build-status/view/{PROJECT ID}` + +Example: +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. + +Example: +http://php-censor.local/project/view/2 ~> PROJECT ID: `2` + +### Enable/disable status image and page + +You can enable or disable access to the public status image and page in your project's settings.