- Before you start, please adopt an existing issue (labelled with "ready for adoption") or start a new one to avoid duplicated efforts.
- Please submit a merge request after you finish development.
In order to make it easier we've prepared [special `yii2-dev` Composer package](https://github.com/yiisoft/yii2/blob/master/docs/internals/getting-started.md).
- [Report an issue](docs/internals/report-an-issue.md)
- [Translate documentation or messages](docs/internals/translation-workflow.md)
- [Give us feedback or start a design discussion](http://www.yiiframework.com/forum/index.php/forum/42-design-discussions-for-yii-20/)
- [Contribute to the core code or fix bugs](docs/internals/git-workflow.md)
### 3. Make sure there is an issue created for the thing you are working on if it requires significant effort to fix
### 3. Prepare the testing environment
The following steps are not necessary if you want to work only on translations or documentation.
- run `composer update` to install dependencies (assuming you have [composer installed globally](https://getcomposer.org/doc/00-intro.md#globally)).
- run `php build/build dev/app basic` to clone the basic app and install composer dependencies for the basic app.
This command will install foreign composer packages as normal but will link the yii2 repo to
the currently checked out repo, so you have one instance of all the code installed.
Do the same for the advanced app if needed: `php build/build dev/app advanced`.
This command will also be used to update dependencies, it runs `composer update` internally.
**Now you have a working playground for hacking on Yii 2.**
The following steps are optional.
### Unit tests
You can execute unit tests by running `phpunit` in the repo root directory. If you do not have phpunit installed globally
you can run `php vendor/bin/phpunit` instead.
Some tests require additional databases to be set up and configured. You can create `tests/data/config.local.php` to override
settings that are configured in `tests/data/config.php`.
You may limit the tests to a group of tests you are working on e.g. to run only tests for the validators and redis
`phpunit --group=validators,redis`. You get the list of available groups by running `phpunit --groups`.
### Extensions
To work on extensions you have clone the extension repository. We have created a command that can do this for you:
php build/build dev/ext <extension-name>
where `<extension-name>` is the name of the extension, e.g. `redis`.
If you want to test the extension in one of the application templates, just add them to the `composer.json` of the application as you would
normally do e.g. add `"yiisoft/yii2-redis": "*"` to the `require` section of the basic app.
Running `php build/build dev/app basic` will install the extension and its dependecies and create
a symlink to `extensions/redis` so you are not working in the composer vendor dir but in the yii2 repository directly.
Working on bugs and features
----------------------------
Having prepared your develop environment as explained above you can now start working on the feature or bugfix.
### 1. Make sure there is an issue created for the thing you are working on if it requires significant effort to fix
All new features and bug fixes should have an associated issue to provide a single point of reference for discussion
and documentation. Take a few minutes to look through the existing issue list for one that matches the contribution you
intend to make. If you find one already on the issue list, then please leave a comment on that issue indicating you
intend to work on that item. If you do not find an existing issue matching what you intend to work on, please open a
new issue for your item or create a pull request directly if it is straightforward fix. This will allow the team to review your suggestion, and provide appropriate feedback along
the way.
intend to work on that item. If you do not find an existing issue matching what you intend to work on, please
[open a new issue](report-an-issue.md) or create a pull request directly if it is straightforward fix. This will allow the team to
review your suggestion, and provide appropriate feedback along the way.
> For small changes or documentation issues or straightforward fixes, you don't need to create an issue, a pull request is enough in this case.
### 4. Fetch the latest code from the main Yii branch
### 2. Fetch the latest code from the main Yii branch
```
git fetch upstream
@ -43,7 +95,7 @@ git fetch upstream
You should start at this point for every new contribution to make sure you are working on the latest code.
### 5. Create a new branch for your feature based on the current Yii master branch
### 3. Create a new branch for your feature based on the current Yii master branch
> That's very important since you will not be able to submit more than one pull request from your account if you'll
use master.
@ -57,14 +109,14 @@ git checkout upstream/master
git checkout -b 999-name-of-your-branch-goes-here
```
### 6. Do your magic, write your code
### 4. Do your magic, write your code
Make sure it works :)
Unit tests are always welcome. Tested and well covered code greatly simplifies the task of checking your contributions.
Failing unit tests as issue description are also accepted.
### 7. Update the CHANGELOG
### 5. Update the CHANGELOG
Edit the CHANGELOG file to include your change, you should insert this at the top of the file under the
"Work in progress" heading, the line in the change log should look like one of the following:
@ -79,7 +131,7 @@ The changelog should be grouped by type (`Bug`,`Enh`) and ordered by issue numbe
For very small fixes, e.g. typos and documentation changes, there is no need to update the CHANGELOG.
### 8. Commit your changes
### 6. Commit your changes
add the files/changes you want to commit to the [staging area](http://gitref.org/basic/#add) with
@ -96,7 +148,7 @@ automatically link your commit with the ticket:
git commit -m "A brief description of this change which fixes #42 goes here"
```
### 9. Pull the latest Yii code from upstream into your branch
### 7. Pull the latest Yii code from upstream into your branch
```
git pull upstream master
@ -106,31 +158,32 @@ This ensures you have the latest code in your branch before you open your pull r
you should fix them now and commit the changes again. This ensures that it's easy for the Yii team to merge your changes
with one click.
### 10. Having resolved any conflicts, push your code to github
### 8. Having resolved any conflicts, push your code to github