A detailed example of how to contribute to Yii 3.0

[rugabarbo (Pavel Ivanov)]

Hi, friends!

I noticed that many developers want to help - that’s great! But they don’t understand how to set up a working environment to contribute. And this becomes a serious problem on the way to contribution.

I am developing yii-dev-tool for the framework. And I noticed that we do not have a detailed description of how to use it. That is why I decided to write a detailed example of contributing to the framework. Here I will now duplicate this instruction so that you can quote it and ask questions.

So, let’s begin…

Objective

Suppose we want to work on three interdependent packages:

• yiisoft/yii-demo
• yiisoft/view
• yiisoft/i18n

Package yii-demo depends on package view, and package view depends on package i18n.

Suppose we want to add new features to package i18n, and then use them in package view. After that, we will need to run the tests in package yii-demo and make sure that everything works correctly.

Step 1: create forks

Go to the page of each repository and click the “Fork” button:

• yiisoft/yii-demo
• yiisoft/view
• yiisoft/i18n

Suppose my nickname on Github is “samdark”. Then I will get three forks:

• samdark/yii-demo
• samdark/view
• samdark/i18n

For your nickname you will get other fork names.

Step 2: install yii-dev-tool

Now install yii-dev-tool:

git clone https://github.com/yiisoft/yii-dev-tool
cd yii-dev-tool
composer install

Step 3: configure yii-dev-tool to use forks

In order for yii-dev-tool to use our forks, they must be configured. Create your configuration:

cd yii-dev-tool
cp packages.local.php.example packages.local.php

Specify the forks in config packages.local.php:

$packages = [
    'yii-demo' => 'samdark/yii-demo',
    'view' => 'samdark/view',
    'i18n' => 'samdark/i18n',
];

Step 4: install packages

Now install the packages:

cd yii-dev-tool
./yii-dev install yii-demo,view,i18n

This command clones the fork repositories from GitHub to the local directory yii-dev-tool/dev/, sets upstream for them and executes composer install in each package. Then symlinks will be created:

• yii-dev-tool/dev/yii-demo/vendor/yiisoft/view -> yii-dev-tool/dev/view
• yii-dev-tool/dev/view/vendor/yiisoft/i18n -> yii-dev-tool/dev/i18n

Due to these symlinks, changes in packages will immediately affect the operation of packages that depend on them. It is very convenient for development.

Step 5: create a git branch for work

Create a new feature-x branch in the repositories:

cd yii-dev-tool
./yii-dev git/checkout-branch feature-x yii-demo,view,i18n

Step 6: writing the code

Now make the necessary changes to the code of package i18n in folder yii-dev-tool/dev/i18n. Next, make changes to the code of package view in folder yii-dev-tool/dev/view. And, finally, change package yii-demo in folder yii-dev-tool/dev/yii-demo.

Step 7: run the tests

Make sure the tests pass. For instance, package yii-demo tests can be run with the following command:

cd yii-dev-tool/dev/yii-demo
./vendor/bin/phpunit

Step 8: commit and push the changes to the fork repositories

Commit the changes:

cd yii-dev-tool
./yii-dev git/commit "Add feature X" yii-demo,view,i18n

Push the new code to remote repositories:

cd yii-dev-tool
./yii-dev git/push yii-demo,view,i18n

Step 9: create pull requests

Go to the pages of the original repositories and create a PR in each:

• yiisoft/yii-demo
• yiisoft/view
• yiisoft/i18n

Final notes

That’s all. We developed new functionality and submitted it for review Of course, the steps will be slightly different for different tasks and configurations.

Remember that yii-dev-tool contains many other commands for working with repositories:

• ./yii-dev exec – executes the specified console command in each package
• ./yii-dev git/checkout-branch – creates, if not exists, and checkout a git branch
• ./yii-dev git/commit – add and commit changes into each package repository
• ./yii-dev git/pull – pull changes from package repositories
• ./yii-dev git/push – push changes into package repositories
• ./yii-dev git/status – show git status of packages
• ./yii-dev install – install packages
• ./yii-dev lint – check packages according to PSR12 standa
• ./yii-dev replicate/files – copy files specified in config/replicate/files.php into each package
• ./yii-dev replicate/composer-config – merge config/replicate/composer.json into composer.json of each package
• ./yii-dev update – update packages

If you encounter any problems, create an issue – and we’ll try to help you.

---

If you have suggestions for improving this workflow example, let’s discuss Thanks for reading!

[rugabarbo (Pavel Ivanov)]

See also yii-dev-tool updates:

Yii-dev-tool enhancements

Hi all I develop yii-dev-tool package for Yii3 contributors. I recently wrote about how to use this tool to develop the framework. Today I’ll write about the improvements that have been made since then. [03] Vagrant Added ready-to-use Vagrant configuration. See related documentation. Now in a few minutes you can get a working environment for developing the framework. Just install, write code and commit it from the pre-configured virtual machine. The stack is: Ubuntu 18.04 PH…

[soodssr]

Hi
I feel like that it might not be required to use dev-tool when working on a single package but still wanted to know view point from others.
Is it suitable/required to use this tool when contributing for a single package?

[samdark (Alexander Makarov)]

No, it’s not required. It is just a tool.

[JobranRodriguez]

hola buenos días, lleva tiempo el desarrollo de yii3 demasiado diría yo, creo que muchos estamos esperando esta actualización, y espero que tengan muchos ejemplos prácticos para facilitar los usos de las diferentes clases, propiedades y métodos del nuevo yii3, animo finalicen pronto hagan de yii3 algo grande que todos quieran usar saludos… =)

[johndoeII (Jhondoeii)]

Yo puedo ayudar con la traducción de la documentación en inglés, francés y/o español.

Saludos!