Maintaining core extensions separately

[qiangxue]

In order to enable faster version releases and make core extensions more scalable, we are thinking to maintain each core extension and application template separately in individual github projects. Below is a preliminary plan. Before we execute it, we would like to have it reviewed by everyone to make sure we do not omit anything important. Thank you!

Tasks

• [x] stop automatic subsplit
• [x] delete /extensions and /apps from yii2 repo
• [x] move/adjust unit tests and documentation specific for each extension to the corresponding extension repo
• [x] adjust yii2-dev to keep BC (solved by dev command)
• [x] adjust build scripts to support major/minor releases
• [ ] adjust apidoc tool for generating api/guide docs for extensions
• [x] enhance build scripts to support automatic patch releases
• [x] adjust travis configs. Each extension or app will need its own travis setup
• adjust internal docs
  • [x] update https://github.com/yiisoft/yii2/blob/master/docs/internals/versions.md
  • [x] adjust git workflow for extensions https://github.com/yiisoft/yii2/blob/master/docs/internals/git-workflow.md
  • [x] adjust getting started https://github.com/yiisoft/yii2/blob/master/docs/internals/getting-started.md

    Project Organization

    1. Maintain individual core extensions and application templates in separate independent GitHub projects. Each extension/app project will
  • keep using its current project name to ensure BC. For example, the yii2-gii extension will be maintained in yiisoft/yii2-gii project.
  • 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.
  • be released independently as needed. See versioning policy below.
    2. Continue using "yii2" as the main project to maintain the core framework. "yii2" should contain the following stuff
  • the core framework code
  • the definitive guide. Extension-specific guide should be put in the corresponding extension projects. API doc should be generated on-the-fly when releasing the core framework.
  • the test code for the core framework only
  • build tools and internal docs
    3. Continue doing automatic subsplit from "yii2" to "yii2-framework" to ensure BC.
    4. Track the core framework issues in the "yii2" project. Extension issues should be reported to the corresponding extension projects.

       Release and Versioning Policy

    5. Version numbers are in the format of 2.x.y.z.
  • 2.x: major releases, containing major features. May be BC-breaking. Release cycle is around 6 months. With news announcements. Project site will be updated.
  • 2.x.y: minor releases, containing minor features and bug fixes. Must be BC with prior 2.x.* releases. Release cycle is around 1 to 2 months. With news announcements. Project site will be updated.
  • 2.x.y.z: patch releases, containing bug fixes only. Must be BC with prior 2.x.*.* releases. Release cycle is around 1 to 2 weeks. No news announcement or project site update (unless it contains major/security issue fixes). The release process will be made mostly automatic.
    2. Branching policy
  • master branch is the dev branch for the current major release. Once a new minor release is ready, create a maintenance branch named 2.x.y off master.
  • Create tags 2.x.y.z on 2.x.y branch to mark patch releases (including 2.x.y.0 release).
  • Changes on 2.x.y will be merged back to master constantly.
  • For the next major release, create a dev branch named 2.t-dev. Once the next major release is ready, it will be merged to master, and then create a 2.t.0 branch off master (the old 2.t-dev branch will be deleted to avoid confusion).
    3. yii2 and core extension/application projects are released independently of each other.
  • Both yii2 and core extension projects follow the above versioning and branching policies.
  • The release cycles described above only apply to the core framework.
  • Extensions and application templates 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.
  • Extensions and application templates may have version numbers that are different from that of the core framework. For example, yii2-gii may have the latest version number as 2.0.5 while yii2 is already at 2.1.3, even though currently they are all synchronized at 2.0.3.

[schmunk42]

@samdark :smile:

I'd also strongly recommend to replace all unbound version constraints, eg. with 1.*, 2.*, i.e. here

    "swiftmailer/swiftmailer": "*",
    "fzaninotto/faker": "*",
    "cebe/indent": "*"

[samdark]

It seems all tests and docs are fine now...

[pana1990]

@samdark i think tool-api-doc.md, tutorial-mailing.md, tests tutorials should be move to extension repository appropriate

What do you think about it?

[samdark]

Mailing was already moved. Some parts of it left as is because overall mailing is not an extension, only swiftmailer adapter is.

[samdark]

Will check tool-api-doc.md.

[SDKiller]

There is one drawback after moving tests and docs to corresponding extensions' repos - unlike framework docs and tests, extensions' ones are downloaded by composer. And update runs each time docs and tests are changed (as for the docs - it happens frequently enough). It also takes additional disk space (for some extensions - more than extension code itself), docs also are dowloaded with existing translations - imagine some time there will be 20-30 languages.

[janisto]

All packages should have .gitattributes file. When you download stable packages, all extra files are excluded, but they are included for dev.

Example: https://github.com/janisto/yii2-timepicker/blob/master/.gitattributes

[samdark]

Good idea. @janisto want to work on a pull request?

[janisto]

I can do a pull request during the weekend. A bit too busy today.

[klimov-paul]

Status of GIT attributes setup:

• [x] basic app
• [x] advanced app
• [x] authclient
• [x] bootstrap
• [x] elasticsearch
• [x] faker
• [x] gii
• [x] imagine
• [x] mongodb
• [x] redis
• [x] smarty
• [x] sphinx
• [x] swiftmailer
• [x] twig
• [x] jui
• [x] codeception
• [x] debug

[janisto]

👍🍻🍺

[klimov-paul]

What about 'README.md', 'LICENCE.md', 'CHANGELOG.md', should these files be kept?

[janisto]

I would keep those.

[samdark]

Yes, these should be kept.

[samdark]

https://github.com/yiisoft/yii2/commit/46cd63fd284de21466699b97fe0684009ed401af

[samdark]

Done with the rest of GIT attributes.

[amnah]

I installed yii2-app-basic using composer create-project, but it excluded the .gitignore file (I assume because of the newly added .gitattributes file)

Is that supposed to happen? I found it weird when I noticed that my vendor dir got committed.

[samdark]

Right. .gitignore should not be in .gitattributes... At least for apps.

[samdark]

Fixed.

[pana1990]

i think that Translation status should should take into due consideration status docs from extensions.

what do you think about it?

[samdark]

What do you mean?

[pana1990]

here : https://github.com/yiisoft/yii2/blob/master/docs/internals/translation-status.md

It should have the status docs from extensions.

sorry for my english.

[samdark]

Yes. Should be updated...

[dynasource]

is it possible to further minimize yii's composer.json, ie. by making composer libraries such as cebe/markdown as suggestion instead of a requirement?

[samdark]

@dynasource only by throwing out Markdown and HtmlPurifier helpers, MaskedInput etc.

[RusAlex]

My 2 cents here. Yes it would be great to have packages not only as separate repositories, but in future as separate components which can be used without core.

At moment, when your project based on Yii 1.x , and when it's big enough, you wont have time to re-write whole project at once. And this situation makes me more careful in selecting packages I will use.

One main ides now is to start replacing app parts which are depends on Yii 1.x with stand alone components where it could. And leave Yii only several global responsibilities: Handle request, render result.

I see this the only way possible in projects with big code base grow and being rewriten seamlesly not in a "full rewrite" way.

And I hope Yii will get rid of this problem in future.

Thanks

[creocoder]

@RusAlex

My 2 cents here. Yes it would be great to have packages not only as separate repositories, but in future as separate components which can be used without core.

As I understand it completely contradicts the philosophy of Yii. This framework of tightly coupled components with lots of conscious violation of many OOP principles (like SOLID) for practice reasons. If short independent components from Yii will not be interested to anyone who build systems with independent components. Yii is interesting as full stack framework and only as full stack.

And I hope Yii will get rid of this problem in future.

I bet that this never will happen.

[RusAlex]

Anyway I could use it as I wrote for Handling Request and Response. Then I will be free in selecting other App components. Yii allows it.

[creocoder]

@RusAlex

Anyway I could use it as I wrote for Handling Request and Response.

I could do so to, but never will do that. Just check http://stackphp.com/ . If you want free set of components you usually want microframework. Like Silex. Yii is full stack. Its different. And you know, choosing Yii for handling Request and Response only is really not smart option because there is much more better tools for that. Every tool have it niche.

[RusAlex]

While there are good built in features to make simple and nice CRUDs fast it will make sense =)

Agree Yii is a tool and it must be used wisely as any other.

[vbsessa]

+1 Actually, i'm really looking forward the changes proposed in the wiki, titled "ideas for 2.1". They seem nice and ambicious.

[samdark]

@cebe anything left for this one?

[cebe]

@samdark automation of releases. I'd like to keep this open until done.

[cebe]

also docs are not 100% fine. E.g. guide for extension is not rendered anywhere.

[cebe]

closing this now. extension docs generation will be part of the new website.

[cebe]

docs about project structure, versioning etc are now in https://github.com/yiisoft/yii2/blob/master/docs/internals/README.md