Made extensions guide more human-friendly and more specific

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).
+- Use [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
+- 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()]]`.
+  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
+- Extension classes should not be prefixed. No `TbNavBar`, `EMyWidget`, etc.
-  translated only if they're displayed to end users.
-- Extension SHOULD NOT use class prefixes (i.e. `TbNavBar`, `EMyWidget`, etc.)
-
 
 ### Namespace
 
-- Extension MUST NOT use `yiisoft` in the namespaces used in the package.
+- Do not use `yiisoft` in the namespaces.
-- Extension MUST NOT have a root-namespace named `\yii`, `\yii2` or `\yiisoft`.
+- Do not use `\yii`, `\yii2` or `\yiisoft` as root namespace.
-- Extension SHOULD use namespaces in this format `vendor-name\type` (all lowercase).
+- 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
+- Extension should be registered at [Packagist](https://packagist.org) in order to be installable via Composer.
-  to losing stats and inability to install package by the old name.
+  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`.
-
 
 ### Composer package name
 
@@ -53,14 +48,15 @@ In the above:
 
 ### Versioning
 
-- Extension SHOULD follow the rules of [semantic versioning](http://semver.org).
+- 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`.
+- 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.
+- Use the type `yii2-extension` in `composer.json` file if your extension is Yii-specific.
-- Extension MUST NOT use `yii` or `yii2` in their composer vendor name.
+- Do not use `yii` or `yii2` as composer vendor name.
-- Extension MUST NOT use `yiisoft` in the composer package name or the 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.
+- Migrations should be appliable to as many data storages as possible.
-- You MUST NOT make use of active-record model classes in your migrations.
+- 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.
+- If extension outputs messages intended for end user these should be wrapped into `Yii::t()` in order to be translatable.
-- Extension MAY provide a configuration for creating message catalogues.
+- Exceptions and other developer-oriented message should not be translated.
-
+- Consider proving `config.php` for `yii message` command to simplify translation.
-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\*`
 
 Testing your extension
 ----------------------
 
-- Extension SHOULD be testable with *PHPUnit*.
+- Consider adding unit tests for PHPUnit.