adjust internal documentation according to #7812

close #11117

docs/internals/README.md

@@ -0,0 +1,43 @@
+Yii Developer Documentation
+===========================
+
+This directory contains documentation about Yii Framework development and release process.
+
+Contributor Guidelines
+----------------------
+
+- [How to Report an Issue](report-an-issue.md)
+- [Getting started](getting-started.md)
+- [Git workflow for Yii 2 contributors](git-workflow.md) - a step by step guide on how to set up your dev environment and start contributing to Yii.
+- [Yii2 Core Framework Code Style](core-code-style.md)
+- [Yii2 View Code Style](view-code-style.md)
+
+
+Dokumentation
+-------------
+
+- [Translation Status](translation-status.md) - which documents are ready for translation.
+- [Translation teams](translation-teams.md)
+- [Translation workflow](translation-workflow.md)
+
+
+Framework Development
+---------------------
+
+- [Pull request quality assurance](pull-request-qa.md)
+- [Automated Tasks](automation.md), like code style fixes, automatic documentation and file generation.
+- [Design Decisions](design-decisions.md) - a FAQ-like list of statements about commonly debated things.
+
+Versioning and Release
+----------------------
+
+- [Project Organization](project-organization.md)
+- [Yii Versioning](versions.md)
+
+
+Misc
+----
+
+### Exception Hierarchy
+
+![Yii Framework Exception Hierarchy](exception_hierarchy.png)

docs/internals/automation.md

@@ -13,3 +13,8 @@ There are some tasks that are done automatically when working on Yii:
   Run `./build/build php-doc/fix` to fix them.
   Check the changes before you commit them as there may be unwanted changes because the command is not perfect.
   You may use `git add -p` to review the changes.
+
+- Updating the Mime Type Magic file (`framework/helpers/mimeTypes.php`) from the Apache HTTPd repository.
+  Run `./build/build mime-type` to update the file.
+
+All of the above commands are included in the [release process](). They may be run between releases but it is not necessary.

docs/internals/core-code-style.md

@@ -1,4 +1,4 @@
-Yii2 Core framework code style
+Yii2 Core Framework Code Style
 ==============================
 
 The following code style is used for Yii 2.x core and official extensions development. If you want to pull-request code

docs/internals/git-workflow.md

@@ -29,7 +29,7 @@ Change to the directory where you cloned Yii, normally, "yii2". Then enter the f
 git remote add upstream git://github.com/yiisoft/yii2.git
 ```
 
-### 3. Prepare the testing environment
+### 3. Prepare the testing environment <span id="prepare-the-test-environment"></span>
 
 The following steps are not necessary if you want to work only on translations or documentation.
 

docs/internals/project-organization.md

@@ -0,0 +1,36 @@
+Project Organization
+====================
+
+This document describes the organization of the Yii2 development repositories.
+ 
+1. Individual Core extensions and application templates are maintained in
+   separate *independent* GitHub projects under the [yiisoft](https://github.com/yiisoft) Github organization.
+    
+   Extension repository names are prefixed with `yii2-`, e.g. `yii2-gii` for the `gii` extension.
+   The composer package name is equal to the Github repository path, e.g. `yiisoft/yii2-gii`.
+   
+   Application template repository names are prefixed with `yii2-app-`, e.g. `yii2-app-basic` for the `basic` application template.
+   The composer package name is equal to the Github repository path, e.g. `yiisoft/yii2-app-basic`.
+   
+   Each extension/app project will
+ 
+   * maintain its tutorial doc in its "docs" folder. The API doc will be generated on-the-fly when the extension/app is being released.
+   * maintain its own test code in its "tests" folder.
+   * maintain its own message translations and all other relevant meta code.
+   * track issues via the corresponding GitHub project.
+      
+   Extension repositories will be released independently as needed, Application templates will be released together with the framework.
+   See [versioning policy](versions.md) for more details.
+
+2. The `yiisoft/yii2` project is the main repository for developing Yii2 framework.
+   This repository provides the composer package [yiisoft/yii2-dev](https://packagist.org/packages/yiisoft/yii2-dev).
+   It contains the core framework code, framework unit tests, the definitive guide, and a set of build tools for framework development and release.
+   
+   Core framework bugs and feature requests are tracked in the issue tracker of this Github project.
+   
+3. The repository `yiisoft/yii2-framework` is a read-only git subsplit of the `framework` directory of the dev project repository and
+   provides the composer package [yiisoft/yii2](https://packagist.org/packages/yiisoft/yii2) which is the official package to be
+   used when installing the framework.
+
+4. For development the apps and extensions can be included in the dev project structure using the
+   [build dev/app](git-workflow.md#prepare-the-test-environment)-Command.

docs/internals/versions.md

@@ -9,41 +9,78 @@ Within the core developer team, we have emphasized several times that it is impo
 But this is an ideal plan. The ferver article has given out a real world example that this is hard to achieve in practice,
 regardless you are using semver or not.
 
-In summary, our versioning policy is as follows:
+In summary, our versioning policy for Yii 2 is as follows:
 
-## Patch Releases `2.x.Y`
+## Version numbers
 
-Patch releases, which should be 100% BC-compatible. Ideally, we hope they contain bug fixes only so that it reduces
+Version numbers are in the format of `2.x.y.z`, where the `z` can be skipped for releases for which `z` is `0`.
-the chance of breaking BC. Practically, since 2.0.x is released more frequently, we are also adding minor features
+
+A possible Yii version 3 is not covered here as we'd expect it to be like 2.0 over 1.0. We expect that this only happens every 3 to 5 years,
+depending on external technology advancement (such as PHP upgraded from 5.0 to 5.4).
+
+### `2.X.0`: major releases
+
+BC-breaking releases, which contain major features and changes that may break BC. Upgrading from earlier versions may
+not be trivial, but a complete upgrade guide will be available.
+
+* Mainly contain new features and bug fixes
+* Contain minor features and bug fixes merged from patch releases.
+* May contain BC-breaking changes which are recorded in a `UPGRADE-2.X.md` file.
+* Release cycle is around 12 months or more.
+* Require pre-releases: `2.X.0-alpha`, `2.X.0-beta`, `2.X.0-rc`.
+* Requires major news releases and marketing effort.
+
+
+### `2.x.Y`: minor releases
+
+Patch releases, which should be 100% BC-compatible. Ideally, we hope they contain only changes that do not affect backwards compatibilty
+however it is not always possible to keep 100% BC-compatible, so upgrade notes are recorded in `UPGRADE.md`.
+Practically, since 2.0.x is released more frequently, we are also adding minor features
 to it so that users can enjoy them earlier.
 
-* Maintained on a branch named `2.x`
 * Mainly contain bug fixes and minor feature enhancements
-* No major features.
+* No major features or changes.
-* Must be 100% backward compatible to ensure worry-free upgrade. Only exception is security issues that may require breaking BC.
+* Should be 100% backward compatible to ensure worry-free upgrade. Only a few exceptions are allowed which are documented in `UPGRADE.md`.
 * Release cycle is around 1 to 2 months.
 * No pre-releases (alpha, beta, RC) needed.
 * Should be merged back to master branch constantly (at least once every week manually).
+* With news announcements. Project site will be updated.
 
 
-## Minor Releases `2.X.0`
+### `2.x.y.Z`: patch releases
 
-BC-breaking releases, which contains major features and changes that may break BC. Upgrading from earlier versions may
+Patch releases, which should be 100% BC-compatible, containing bug fixes only.
-not be trivial, but a complete upgrade guide or even script will be available.
+No news announcement or project site update (unless it contains major/security issue fixes).
+The release process will be made mostly automatic.
 
-* Developed on master branch
+* containing bug fixes only, no features included.
-* Mainly contain new features and bug fixes
+* Must be 100% backward compatible to ensure worry-free upgrade. Only exception is security issues that may require breaking BC.
-* Contain minor features and bug fixes merged from patch releases
+* Release cycle is around 1 to 2 weeks.
-* May contain BC-breaking changes which are recorded in `UPGRADE-2.X.md` file
+* No pre-releases (alpha, beta, RC) needed.
-* Release cycle is around 6 to 8 months
+* Should be merged back to master branch on release.
-* Require pre-releases: `2.X.0-alpha`, `2.X.0-beta`, `2.X.0-rc`
+
-* Requires major news releases and marketing effort.
+
+## Branching policy
+
+* `master` branch is the development branch for the current stable major release, currently `2.0.x` versions.
+* Each new major release will be developed on a branch named after the version number, e.g. `2.1`.
+* Once a new major release `2.n` is ready, create a maintenance branch named `2.(n-1).x` off `master`.
+  E.g. a `2.0` branch is created if version `2.1.0` is released as stable and will now be developed on `master`
+  (cmp. [composer branch naming schema](https://getcomposer.org/doc/02-libraries.md#branches)).
+* Create tags `2.x.y.z` and `2.x.y` branch to mark patch releases. For `2.x.y.0` releases, the `0` will be skipped.
+* Changes on `2.n.x` maintenance branches will be merged back to `master` constantly.
+
+The following image shows an illustration of the branches on changing commit history over time:
+
+![Branching policy](versions-branches.png)
 
 
-## Major Releases `X.0.0`
+## Releases
 
-It's like 2.0 over 1.0. We expect this only happens every 3 to 5 years, depending on external technology advancement
+Both Yii2  Framework and official extension projects follow the above versioning and branching policies.
-(such as PHP upgraded from 5.0 to 5.4).
+Framework and official extension projects are released independently of each other, i.e. version number mismatch between framework and extension is expected.
+The Application Templates are always released together with the framework.
 
-> Note: Official extensions are following the same versioning policy but could be released independently from
+The release cycles described above only apply to the core framework.
-the framework i.e. version number mismatch between framework and extension is expected.
+Extensions are released on demand.
+It is likely that an extension has no new releases for a very long time because it does not receive any bug fixes or enhancements.

docs/internals/view-code-style.md

@@ -1,4 +1,4 @@
-Yii2 view code style
+Yii2 View Code Style
 ====================
 
 The following code style is used for Yii 2.x core and official extensions view files. We aren't forcing you to use this code style for your application. Feel free to choose what suits you better.