Fix internals style (#186)

Author: samdark

000-packages.md

@@ -1,24 +1,25 @@
 # 000 - Packages
 
-Since Yii 3 framework is divided into several packages with the following agreements.
+Yii3 team divided the framework into several packages that conform to the following agreements.
 
-For all packages GitHub repository name exactly matches Packagist package name.
+For all packages, the GitHub repository name exactly matches the Packagist package name.
 
-For a full list of packages and their build statuses see [status page at yiiframework.com](https://www.yiiframework.com/status/3.0).
+For a full list of packages and their building status,
+see [status page at yiiframework.com](https://www.yiiframework.com/status/3.0).
 
-## Yii-specific packages (Yii Framework and Extensions)
+## Yii-specific packages (framework and extensions)
 
 - named `yiisoft/yii-something` or more specific: `yii-type-something` e.g.:
     - modules: `yii-module-users`, `yii-module-pages`
     - themes: `yii-theme-adminlte`, `yii-theme-hyde`
     - widgets: `yii-widget-datepicker`
-    - and so on
+    - ...
 - titled as "Yii Framework ..."
 - may have any dependencies and Yii-specific code
 
-## General purpose packages (Libraries)
+## General purpose packages (libraries)
 
-- can be used outside of Yii Framework
+- you can use these independently of Yii Framework
 - named as `yiisoft/something` without yii-prefix
 - titled as "Yii ..."
 - must not have dependencies on any Yii-specific packages
@@ -30,8 +31,8 @@ The following applies to both Yii-specific packages and general purpose packages
 
 - Package may have `config` directory with Yii-specific defaults.
 - Package may have "config-plugin" in "extra" section of `composer.json`.  
-- Package must not have dependencies in `require` section of `composer.json` that are used in `config` only.
-- Parameters should be namespaced with `vendor/package-name`:
+- Package mustn't have dependencies in `require` section of `composer.json` that are used in `config` only.
+- You should namespace parameters with `vendor/package-name`:
 
 ```php
 return [
@@ -44,19 +45,19 @@ return [
 
 ## Versions
 
-All packages are versioned according to [SemVer](https://semver.org/):
+All packages follow [SemVer](https://semver.org/) versioning:
 
 - `x.*.*` - incompatible API changes.
 - `*.x.*` - add functionality (backwards-compatible).
 - `*.*.x` - bug fixes (backwards-compatible).
 
-First stable version should be 1.0.0.
+The first stable version should be 1.0.0.
 
-Each package version number does not depend on any other package version or "framework version", only on its own public contract. 
+Each package version number doesn't depend on any other package version or framework name/version,
+only on its own public contract.
+The framework as a whole has the "Yii3" name.
 
-So it is completely normal to use together packages with different major versions, as long as they are compatible.
-
-Framework as a whole will keep naming "Yii 3" so it will be considered version 3, independent of version of its packages.
+It's alright to use packages with different major versions together, as long as they're compatible.
 
 ## PHP versions support
 
@@ -67,7 +68,7 @@ The support of PHP versions supported for a package depends on
 - Both packages and application templates MUST have supported versions that receive bug and security fixes.
   These SHOULD correspond to PHP versions receiving security fixes.
 - Packages and application templates MIGHT have supported versions that work with unsupported PHP versions.
-- Bumping minimal PHP version in a package or an application template is considered a minor change.
+- Bumping the minimal PHP version in a package or an application template is a minor change.
 
 ## composer.json
 

001-yii-values.md

@@ -2,48 +2,50 @@
 
 ## Goal
 
-The Yii project aims to build and maintain _practical_ and _helpful_ tools and community.
+The Yii project aims to build and support _practical_ and _helpful_ tools and community.
 
 ## Values
 
 The values we express in our work support the goal. We try to
 
-- Be Practical
-    - [High Performance](#high-performance)
-    - [Sensible Defaults and Flexibility](#sensible-defaults-and-flexibility)
+- Be practical
+    - [High performance](#high-performance)
+    - [Sensible defaults and flexibility](#sensible-defaults-and-flexibility)
     - [Be practice-oriented](#be-practice-oriented)
-- Be Helpful
+- Be helpful
     - [Be simple](#be-simple)
     - [Be explicit](#be-explicit)
     - [Be consistent](#be-consistent)
 
-## Be Practical
+## Be practical
 
-### High Performance
+### High performance
 
-Performance is a necessary condition of practicality. Software should not waste machine or human resources.
+Performance is a necessary condition of practicality. Software shouldn't waste machine resources or human resources.
 
-### Sensible Defaults and Flexibility
+### Sensible defaults and flexibility
 
-We prefer sensible defaults and conventions that users can customize. We seek a balance between flexibility, discipline and simplicity that meets common needs.
+We prefer sensible defaults and conventions that users can customize.
+We seek a balance between flexibility, discipline and simplicity that meets common needs.
 
 ### Be practice-oriented
 
-We prefer practice over theory. For example:
+We prefer practice to theory. For example:
 
 - Solutions for known use cases should avoid excess complexity by providing only needed flexibility.
 - Standard implementations should take practical use into account.
 - Experience is at least as useful as theory in guiding design.
 - Context is critical in determining appropriateness.
 
-## Be Helpful
+## Be helpful
 
-This value guides technical decisions as well as community activity. Consideration of how software features help users should guide development. Community-wise, we value any helpful contribution, be it a
-pull request or an answer in the forum.
+This value guides technical decisions as well as community activity.
+Consideration of how software features help users should guide development.
+Community-wise, we value any helpful contribution, be it a pull request or an answer in the forum.
 
-When the other principles could conflict, we choose a solution that is more helpful to the community.
+When the other principles could conflict, we choose a solution that's more helpful to the community.
 
-### Be Simple
+### Be simple
 
 Solutions should be simple and expressive:
 

002-issue-workflow.md

@@ -6,7 +6,7 @@ The process of handing incoming issues is the following:
 
 ## Roles
 
-We have multiple roles:
+We've many roles:
 
 - Process managers - initially triage issues and manage labels.
 - Decision makers - participate in discussions moving them to resolutions.
@@ -18,10 +18,10 @@ A single person may take one or more roles in the issue resolving process.
 
 ## Labels
 
-We label issues in order to mark multiple things: current status, issue type,
+We label issues to mark many things: current status, issue type,
 component affected. Status labels speak for themselves.
 
 ## Milestones
 
-Issues are not assigned to milestones unless they are critical or there is
-a likely good pull request exist.
+Issues aren't assigned to milestones unless they're critical or there is
+a likely good pull request exists.

003-roadmap.md

@@ -2,23 +2,23 @@
 
 We want Yii 3 to:
 
-- Not limit developer in choosing architecture. Allow anything from "classic" MVC to DDD.
+- Not limit a developer in choosing architecture. Allow anything from "classic" MVC to DDD.
 - Be based on best practices such as SOLID, GRASP etc. and teach them to community.
-- Keep most good things from Yii 2.
-- Be more open to global PHP community and infrastructure.
+- Keep the most good things from Yii 2.
+- Be more open to the global PHP community and infrastructure.
 
 ## PSRs compliance
 
-PSR compliance helps with customizability, ability to use general PHP libraries and implement less wrappers.
+PSR compliance helps with customizability, ability to use general PHP libraries and implement fewer wrappers.
 Here's the list of PSRs we want to implement.
 
 ### PSR-3 Logger
 
-Implemented as a [separate package that is not dependent on a framework](https://github.com/yiisoft/log).
+Implemented as a [separate package that isn't dependent on a framework](https://github.com/yiisoft/log).
 
 - [x] Framework packages should depend on interface only.
 - [x] Split drivers into packages.
-- [x] Clean up code.
+- [x] Clean-up code.
 - [x] [Fix email target](https://github.com/yiisoft/log-target-email).
 
 ### PSR-4 Autoloading
@@ -33,16 +33,16 @@ Implemented as a [separate package that is not dependent on a framework](https:/
 
 ### PSR-11 Container
 
-Implemented as a [separate package that is not dependent on a framework](https://github.com/yiisoft/di).
+Implemented as a [separate package that isn't dependent on a framework](https://github.com/yiisoft/di).
 
-- [x] Framework packages should not use container directly. One should be able to instantiate everything manually.
+- [x] Framework packages shouldn't use container directly. One should be able to instantiate everything manually.
 - [x] Finish refactoring.
-- [x] Remove all framework-specific implementations from the package. Move to framework.
+- [x] Remove all framework-specific implementations from the package. Move to a framework.
 - [x] [Implement autoloader fallback](https://github.com/yiisoft/di/issues/88)
 
 ### PSR-12 Code style
 
-- [x] Make sure code follows it.
+- [x] Make sure the code follows it.
 - [x] Automate fixing style before release.
 
 ### PSR-14 Event dispatcher
@@ -53,8 +53,8 @@ Implemented as a [separate package that is not dependent on a framework](https:/
 
 ### PSR-15 HTTP handlers
 
-- [x] Rewrite HTTP flow to PSR-7 request-reponse + formatting response via emitter.
-- [x] Provide SAPI emitter out of the box.
+- [x] Rewrite HTTP flow to PSR-7 request-response + formatting response via emitter.
+- [x] Offer SAPI emitter out of the box.
 - [x] Make it possible to use alternative emitters such as RoadRunner.
 - [x] Support middleware.
 - [x] Implement filters as middleware:
@@ -65,11 +65,11 @@ Implemented as a [separate package that is not dependent on a framework](https:/
 
 ### PSR-16 Simple cache
 
-Implemented as a [separate package that is not dependent on a framework](https://github.com/yiisoft/cache).
+Implemented as a [separate package that isn't dependent on a framework](https://github.com/yiisoft/cache).
 
 - [x] Framework packages should depend on interfaces only.
 - [x] Split drivers into packages.
-- [x] Clean up code.
+- [x] Clean-up code.
 
 ### PSR-17 HTTP factories
 
@@ -92,7 +92,7 @@ Implemented as a [separate package that is not dependent on a framework](https:/
 
 ## Router
 
-Implemented as a [separate package that is not dependent on a framework](https://github.com/yiisoft/router).
+Implemented as a [separate package that isn't dependent on a framework](https://github.com/yiisoft/router).
 
 - [x] DSL for configuration.
 - [x] Ability to route to any callable.
@@ -101,10 +101,10 @@ Implemented as a [separate package that is not dependent on a framework](https:/
 
 ## Best practices and SOLID compliance of all classes/packages
 
-- [x] Make sure interfaces follow "interface segregation" principle.
-- [x] Do not use public properties.
-- [x] Do not use `init()`.
-- [x] Do not inherit from `BaseObject` or `Component`. Remove these.
+- [x] Make sure interfaces follow the "interface segregation" principle.
+- [x] Don't use public properties.
+- [x] Don't use `init()`.
+- [x] Don't inherit from `BaseObject` or `Component`. Remove these.
 - [x] No globals.
 - [x] No static calls except helpers that are final.
 - [x] Prefer throwing exceptions to fixing input.
@@ -125,12 +125,12 @@ Implemented as a [separate package that is not dependent on a framework](https:/
 ## Documentation
 
 - [ ] Follow best practices.
-- [ ] Don't use "MVC" term.
+- [ ] Don't use the "MVC" term.
 - [ ] Upgrading from Yii 2.
 
 ## RBAC
 
-RBAC is implemented as [framework-independent package](https://github.com/yiisoft/rbac).
+RBAC is implemented as [a framework-independent package](https://github.com/yiisoft/rbac).
 
 - [x] Finish refactoring.
 - [x] Make sure it follows best practices.
@@ -145,17 +145,17 @@ View is implemented as [framework-independent package](https://github.com/yiisof
 - [x] Rethink and implement active form widgets.
 - [x] Implement caching widgets.
 
-## Data abstractions and Grid
+## Data abstractions and grid
 
 - [x] Finish [data abstractions](https://github.com/yiisoft/data).
-- [x] Port sort, make it use data abstractions. Should be part of [yii-dataview](https://github.com/yiisoft/yii-dataview).
-- [x] Port paging, make it use data abstractions. Should be part of [yii-dataview](https://github.com/yiisoft/yii-dataview).
-- [x] Port grid, make it use data abstractions. Should be part of [yii-dataview](https://github.com/yiisoft/yii-dataview).
-- [x] Port list, make it use data abstractions. Should be part of [yii-dataview](https://github.com/yiisoft/yii-dataview).
+- [x] Port sort, use data abstractions. Should be part of [yii-dataview](https://github.com/yiisoft/yii-dataview).
+- [x] Port paging, use data abstractions. Should be part of [yii-dataview](https://github.com/yiisoft/yii-dataview).
+- [x] Port grid, use data abstractions. Should be part of [yii-dataview](https://github.com/yiisoft/yii-dataview).
+- [x] Port list, use data abstractions. Should be part of [yii-dataview](https://github.com/yiisoft/yii-dataview).
 
 ## Validators
 
-- [x] Finish [main package](https://github.com/yiisoft/validator) redesign
+- [x] Finish [the main package](https://github.com/yiisoft/validator) redesign
 - [x] Port necessary validators
 
 ## Debug toolbar
@@ -174,6 +174,7 @@ View is implemented as [framework-independent package](https://github.com/yiisof
 ## Others
 
 - [x] [Decide on namespaces](https://forum.yiiframework.com/t/lowercase-or-camelcase-namespaces/124983/52).
-- [x] [Clean up error handler](https://github.com/yiisoft/yii2/issues/14348). Make sure error handler catches fatals and is using response.
-- [x] Make validators independent from models to allow reusing them in handlers.
+- [x] [Clean up error handler](https://github.com/yiisoft/yii2/issues/14348). Make sure the error handler catches
+  fatals and is using response.
+- [x] Make validators independent of models to allow reusing them in handlers.
 - [x] [Split IdentityInterface](https://github.com/yiisoft/yii2/issues/13825).

005-development-tool.md

@@ -1,7 +1,7 @@
-# 005 - Yii Development Tool
+# 005 - Yii development tool
 
-For Yii 3 the number of packages increased significantly in order to achieve more reusability and independent releases.
-In order to ease development of the framework itself we have created a special tool available from [yiisoft/yii-dev-tool](https://github.com/yiisoft/yii-dev-tool).
+For Yii 3 the number of packages increased significantly to achieve more reusability and independent releases.
+To ease development of the framework itself we've created a special tool available from [yiisoft/yii-dev-tool](https://github.com/yiisoft/yii-dev-tool).
 
 ```
 $ ./yii-dev
@@ -31,17 +31,14 @@ Available commands:
   update           Update packages
 ```
 
-There are multiple commands available. The most important ones are `install` and `update`. What it does is:
+There are many commands available. The most important ones are `install` and `update`. What it does is:
 
 1. Install/update all packages listed in [`packages.php`](https://github.com/yiisoft/yii-dev-tool/blob/master/packages.php)
    or individual package from that list if specified.
-2. For every packages installed check `vendor` directory for packages listed in `packages.php`. If there are any,
-   replace package directory with a symlink to another package source.
+2. For every package installed check `vendor` directory for packages listed in `packages.php`.
+   If there is any, replace package directory with a symlink to another package source.
 
-As a result you will have multiple packages using each other so there is no need to `git push` and `composer install` / `composer update`
+As a result you will have many packages using each other, so there is no need to `git push` and `composer install` / `composer update`
 during development.
 
 A [detailed example](https://github.com/yiisoft/yii-dev-tool#usage-example) of using the tool is available in its README.
-
-> Note: In case you are using PhpStorm you have to add `yiisoft` exclusion pattern in "Settings → Directories → Exclude Files".
-> Else it would go into infinite indexing cycle.

006-git-commit-messages.md

@@ -4,14 +4,14 @@
 ## Subject line
 
 - Use `#123` to reference issue by number
-- Use imperative mood i.e. `Fix`, not `Fixed`
-- Do not add period at the end
+- Use imperative mood that's `Fix`, not `Fixed`
+- Don't add period at the end
 - Use `[skip ci]` if there is no need to run unit tests
 - Start with a capital letter
 - Limit to 50 characters
 
 ## Body
 
-Use message body **if** extra explanation is needed. Explain why, not how.
+Use message body **if** you need an extra explanation. Explain why, not how.
 
 - Limit line length to 72 characters

007-exceptions.md

@@ -2,7 +2,7 @@
 
 - Throw exceptions instead of returning an error code.
 - Exception class name must be suffixed with `Exception`.
-- Use grammatically correct error messages including ending punctuation i.e. most exceptions must end with period.
+- Use grammatically correct error messages including ending punctuation, that's most exceptions must end with a period.
 - `\InvalidArgumentException` must be used directly. There should be no exceptions inherited from it.
 - `\InvalidArgumentException` must never be caught.