From ce1c702424296078463c769c3196bf1c2238503b Mon Sep 17 00:00:00 2001 From: Alexander Makarov Date: Fri, 10 Jan 2014 03:07:49 +0400 Subject: [PATCH] Made extensions guide more human-friendly and more specific --- docs/guide/extensions.md | 53 +++++++++++++++++----------------------- 1 file changed, 22 insertions(+), 31 deletions(-) diff --git a/docs/guide/extensions.md b/docs/guide/extensions.md index cb7cec525..3eb82dc10 100644 --- a/docs/guide/extensions.md +++ b/docs/guide/extensions.md @@ -4,19 +4,16 @@ Extending Yii Code style ---------- -- Extension code style SHOULD be similar to [core framework code style](https://github.com/yiisoft/yii2/wiki/Core-framework-code-style). -- All classes, methods and properties SHOULD be documented using phpdoc. Note that you can use markdown and link to properties and methods -using the following syntax: e.g. `[[name()]]`, `[[name\space\MyClass::name()]]`. -- If you're displaying errors to developers do not translate these (i.e. do not use `\Yii::t()`). Errors should be - translated only if they're displayed to end users. -- Extension SHOULD NOT use class prefixes (i.e. `TbNavBar`, `EMyWidget`, etc.) - +- Use [core framework code style](https://github.com/yiisoft/yii2/wiki/Core-framework-code-style). +- Document classes, methods and properties using phpdoc. Note that you can use markdown and link to properties and methods + using the following syntax: e.g. `[[name()]]`, `[[name\space\MyClass::name()]]`. +- Extension classes should not be prefixed. No `TbNavBar`, `EMyWidget`, etc. ### Namespace -- Extension MUST NOT use `yiisoft` in the namespaces used in the package. -- Extension MUST NOT have a root-namespace named `\yii`, `\yii2` or `\yiisoft`. -- Extension SHOULD use namespaces in this format `vendor-name\type` (all lowercase). +- Do not use `yiisoft` in the namespaces. +- Do not use `\yii`, `\yii2` or `\yiisoft` as root namespace. +- Use `vendor-name\type` namespace format (all lowercase). Distribution ------------ @@ -25,10 +22,8 @@ Distribution and use it. It should be written using markdown. If you want to provide translated readme, name it as `readme_ru.md` where `ru` is your language code. If extension provides a widget it is a good idea to include some screenshots. - It is recommended to host your extensions at [Github](github.com). -- Extension MUST be registered at [Packagist](https://packagist.org). Choose package name wisely since changing it leads - to losing stats and inability to install package by the old name. -- Extension MUST provide a valid autoloading configuration in `composer.json`. - +- Extension should be registered at [Packagist](https://packagist.org) in order to be installable via Composer. + Choose package name wisely since changing it leads to losing stats and inability to install package by the old name. ### Composer package name @@ -53,14 +48,15 @@ In the above: ### Versioning -- Extension SHOULD follow the rules of [semantic versioning](http://semver.org). -- Use a consistent format for your repository tags, as they are treated as version strings by composer, eg. `0.2.4`,`0.2.5`,`0.3.0`,`1.0.0`. +- Use the rules of [semantic versioning](http://semver.org). +- Use a consistent format for your repository tags, as they are treated as version strings by composer, eg. `0.2.4`, + `0.2.5`,`0.3.0`,`1.0.0`. ### composer.json -- Extension MUST use the type `yii2-extension` in `composer.json` file. -- Extension MUST NOT use `yii` or `yii2` in their composer vendor name. -- Extension MUST NOT use `yiisoft` in the composer package name or the composer vendor name. +- Use the type `yii2-extension` in `composer.json` file if your extension is Yii-specific. +- Do not use `yii` or `yii2` as composer vendor name. +- Do not use `yiisoft` in the composer package name or the composer vendor name. If your extension classes reside directly in repository root use PSR-4 the following way in your `composer.json`: @@ -100,13 +96,13 @@ Working with database --------------------- - If extension creates or modifies database schema always use Yii migrations instead of SQL files or custom scripts. -- Migrations SHOULD be DBMS agnostic. -- You MUST NOT make use of active-record model classes in your migrations. +- Migrations should be appliable to as many data storages as possible. +- Do not use active record models in your migrations. Assets ------ -- Asset files MUST be registered through Bundles. +- Register assets [through bundles](assets.md). Events ------ @@ -116,16 +112,11 @@ TBD i18n ---- -- Extension SHOULD provide at least one message catalogue with either source or target language in English. -- Extension MAY provide a configuration for creating message catalogues. - -Authorization -------------- - -- Auth-items for controllers SHOULD be named after the following format `vendor\ext\controller\action`. -- Auth-items names may be shortened using an asterisk, eg. `vendor\ext\*` +- If extension outputs messages intended for end user these should be wrapped into `Yii::t()` in order to be translatable. +- Exceptions and other developer-oriented message should not be translated. +- Consider proving `config.php` for `yii message` command to simplify translation. Testing your extension ---------------------- -- Extension SHOULD be testable with *PHPUnit*. +- Consider adding unit tests for PHPUnit.