From 1ab7100e5a67349c22c9db74327b1681a9c9fa60 Mon Sep 17 00:00:00 2001 From: Tobias Munk Date: Thu, 12 Dec 2013 03:11:20 +0100 Subject: [PATCH 1/8] updated extension documentation; added sections dependencies, versioning and authorization --- docs/guide/extensions.md | 38 +++++++++++++++++++++++++++++++------- 1 file changed, 31 insertions(+), 7 deletions(-) diff --git a/docs/guide/extensions.md b/docs/guide/extensions.md index 47ba380..b4ce8c6 100644 --- a/docs/guide/extensions.md +++ b/docs/guide/extensions.md @@ -4,12 +4,15 @@ 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). +- Extension code style SHOULD be similar to [core framework code style](https://github.com/yiisoft/yii2/wiki/Core-framework-code-style). - In case of using getter and setter for defining a property it's preferred to use method in extension code rather than property. -- All classes, methods and properties should be documented using phpdoc. Note that you can use markdown and link to properties and methods +- 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. +- Extension SHOULD provide a valid PSR-0 autoloading configuration in `composer.json` +- Especially for core components (eg. `WebUser`) additional functionality SHOULD be implemented using behaviors or traits instead subclassing. ### Namespace and package names @@ -19,36 +22,57 @@ using the following syntax: e.g. `[[name()]]`, `[[name\space\MyClass::name()]]`. - Extension MAY use a `yii2-` prefix in the composer vendor name (URL). - Extension MAY use a `yii2-` prefix in the repository name (URL). +### Dependencies + +- Additional code, eg. libraries, SHOULD be required in your `composer.json` file. +- Requirements SHOULD NOT include `dev` packages without a `stable` release. +- Use appropriate version constraints, eg. `1.*`, `@stable` for requirements. + +### 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`. + Distribution ------------ - There should be a `readme.md` file clearly describing what extension does in English, its requirements, how to install 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). - TBD: composer.json -- It is recommended to host your extensions at github.com. Working with database --------------------- - If extension creates or modifies database schema always use Yii migrations instead of SQL files or custom scripts. +- Migrations SHOULD be database agnostic. +- You MUST NOT make use of active-record model classes in your migrations. Assets ------ -TBD +- Asset files MUST be registered through Bundles. Events ------ -TBD +- Extension SHOULD make use of the event system, in favor of providing too complex configuration options. i18n ---- -TBD +- 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\*` Testing your extension ---------------------- -TBD \ No newline at end of file +- Extension SHOULD be testable with *Codeception*. \ No newline at end of file From e748455d8f95484408f7816157c677216c01b503 Mon Sep 17 00:00:00 2001 From: Tobias Munk Date: Thu, 12 Dec 2013 03:45:47 +0100 Subject: [PATCH 2/8] reverted events --- docs/guide/extensions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guide/extensions.md b/docs/guide/extensions.md index b4ce8c6..202deb3 100644 --- a/docs/guide/extensions.md +++ b/docs/guide/extensions.md @@ -58,7 +58,7 @@ Assets Events ------ -- Extension SHOULD make use of the event system, in favor of providing too complex configuration options. +TBD i18n ---- From 857feeb6ac0ee8090a8cbd67e93c350c38434cdd Mon Sep 17 00:00:00 2001 From: Tobias Munk Date: Thu, 12 Dec 2013 12:46:15 +0100 Subject: [PATCH 3/8] updated code style, added autoloading and prefix examples --- docs/guide/extensions.md | 31 ++++++++++++++++++++++++++++--- 1 file changed, 28 insertions(+), 3 deletions(-) diff --git a/docs/guide/extensions.md b/docs/guide/extensions.md index 202deb3..e20b4e3 100644 --- a/docs/guide/extensions.md +++ b/docs/guide/extensions.md @@ -10,9 +10,34 @@ Code style 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. -- Extension SHOULD provide a valid PSR-0 autoloading configuration in `composer.json` -- Especially for core components (eg. `WebUser`) additional functionality SHOULD be implemented using behaviors or traits instead subclassing. +- Extension SHOULD NOT use class prefixes (i.e. `TbNavBar`, `EMyWidget`, etc.) +- Extension SHOULD provide a valid PSR-0 autoloading configuration in `composer.json` + + **Example 1: Code in repository root** + + ``` + ./Class.php + ``` + + ``` + "autoload": { + "psr-0": { "vendor\\package\\": "" } + }, + ``` + + **Example 2: Code in repository subfolder `./src`** + + ``` + ./src/vendor/package/Class.php + ``` + + ``` + "autoload": { + "psr-0": { "vendor\\package\\": "./src" } + }, + ``` + + ### Namespace and package names From ce5c3695de84133340b4227dbd249f5a7e915b6d Mon Sep 17 00:00:00 2001 From: Tobias Munk Date: Thu, 12 Dec 2013 12:49:21 +0100 Subject: [PATCH 4/8] updated dependencies and testing --- docs/guide/extensions.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/guide/extensions.md b/docs/guide/extensions.md index e20b4e3..d1fcb00 100644 --- a/docs/guide/extensions.md +++ b/docs/guide/extensions.md @@ -50,7 +50,7 @@ using the following syntax: e.g. `[[name()]]`, `[[name\space\MyClass::name()]]`. ### Dependencies - Additional code, eg. libraries, SHOULD be required in your `composer.json` file. -- Requirements SHOULD NOT include `dev` packages without a `stable` release. +- When extension is released in a stable version, its requirements SHOULD NOT include `dev` packages that do not have a `stable` release. - Use appropriate version constraints, eg. `1.*`, `@stable` for requirements. ### Versioning @@ -100,4 +100,4 @@ Authorization Testing your extension ---------------------- -- Extension SHOULD be testable with *Codeception*. \ No newline at end of file +- Extension SHOULD be testable with *PHPUnit*. \ No newline at end of file From 93cc73858fb138bb972b69adbe7007e42d0b26e7 Mon Sep 17 00:00:00 2001 From: Tobias Munk Date: Thu, 12 Dec 2013 14:21:11 +0100 Subject: [PATCH 5/8] added link to composer docs about autoloading --- docs/guide/extensions.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/guide/extensions.md b/docs/guide/extensions.md index d1fcb00..1f877e6 100644 --- a/docs/guide/extensions.md +++ b/docs/guide/extensions.md @@ -36,6 +36,8 @@ using the following syntax: e.g. `[[name()]]`, `[[name\space\MyClass::name()]]`. "psr-0": { "vendor\\package\\": "./src" } }, ``` + + Details about autoloading configuration can be found in the [composer documentation](http://getcomposer.org/doc/04-schema.md#autoload). From 35594c73bea1ec6973acdf157aeb4767a63da661 Mon Sep 17 00:00:00 2001 From: Tobias Munk Date: Tue, 17 Dec 2013 18:27:38 +0100 Subject: [PATCH 6/8] removed based on samdark's comment from https://github.com/yiisoft/yii2/pull/1485/files#r8293528 --- docs/guide/extensions.md | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/guide/extensions.md b/docs/guide/extensions.md index 1f877e6..c4703f3 100644 --- a/docs/guide/extensions.md +++ b/docs/guide/extensions.md @@ -5,7 +5,6 @@ Code style ---------- - Extension code style SHOULD be similar to [core framework code style](https://github.com/yiisoft/yii2/wiki/Core-framework-code-style). -- In case of using getter and setter for defining a property it's preferred to use method in extension code rather than property. - 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 From ffe4867d668adb9fdf08916064682b3410bc99b3 Mon Sep 17 00:00:00 2001 From: Tobias Munk Date: Tue, 17 Dec 2013 18:28:11 +0100 Subject: [PATCH 7/8] updated autoloading info --- docs/guide/extensions.md | 28 +--------------------------- 1 file changed, 1 insertion(+), 27 deletions(-) diff --git a/docs/guide/extensions.md b/docs/guide/extensions.md index c4703f3..65546b1 100644 --- a/docs/guide/extensions.md +++ b/docs/guide/extensions.md @@ -10,33 +10,7 @@ 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.) -- Extension SHOULD provide a valid PSR-0 autoloading configuration in `composer.json` - - **Example 1: Code in repository root** - - ``` - ./Class.php - ``` - - ``` - "autoload": { - "psr-0": { "vendor\\package\\": "" } - }, - ``` - - **Example 2: Code in repository subfolder `./src`** - - ``` - ./src/vendor/package/Class.php - ``` - - ``` - "autoload": { - "psr-0": { "vendor\\package\\": "./src" } - }, - ``` - - Details about autoloading configuration can be found in the [composer documentation](http://getcomposer.org/doc/04-schema.md#autoload). +- Extension MUST provide a valid autoloading configuration in `composer.json`. Details can be found in the [composer documentation](http://getcomposer.org/doc/04-schema.md#autoload) or see all [official Yii2 extensions](https://github.com/yiisoft/yii2/tree/master/extensions/yii) for example. From 249243a7b0580ce39a3fbe6f7d9c0dd97b983e11 Mon Sep 17 00:00:00 2001 From: Tobias Munk Date: Tue, 17 Dec 2013 19:14:38 +0100 Subject: [PATCH 8/8] updated database, based on @cebe's comment https://github.com/yiisoft/yii2/pull/1485#discussion_r8410809 --- docs/guide/extensions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guide/extensions.md b/docs/guide/extensions.md index 65546b1..4f178ef 100644 --- a/docs/guide/extensions.md +++ b/docs/guide/extensions.md @@ -47,7 +47,7 @@ Working with database --------------------- - If extension creates or modifies database schema always use Yii migrations instead of SQL files or custom scripts. -- Migrations SHOULD be database agnostic. +- Migrations SHOULD be DBMS agnostic. - You MUST NOT make use of active-record model classes in your migrations. Assets