Git workflow for Yii contributors

So you want to contribute to Yii? Great! But to increase the chances of your changes being accepted quickly, please follow the following steps (the first 2 steps only need to be done the first time you contribute). If you are new to git and github, you might want to first check out github help, learn git or learn something about git internal data model.

1. Fork the Yii repository on github and clone your fork to your development environment

git clone git@github.com:YOUR-GITHUB-USERNAME/yii.git

2. Add the main Yii repository as an additional git remote called "upstream"

git remote add upstream git://github.com/yiisoft/yii.git

3. If you don't already have an open issue for the thing you're working on, create one.

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. This will allow the team to review your suggestion, and provide appropriate feedback along the way.

4. Fetch the latest code from the main Yii branch

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

Each separate bug fix or change should go in its own branch. Branch names should be descriptive and start with the number of the issue that your code relates to. For example:

git checkout upstream/master
git checkout -b 001-name-of-your-branch-goes-here

6. Do your magic, write your code

Make sure it works :)

7. 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:

Enh #001: a description of your change goes here (Your Name)

If your change is a bug fix, rather than an enhancement, use "Bug #001" instead of "Enh #001"

8. Commit your changes

add the files/changes you want to commit to the staging area with

git add path/to/my/file.php

You can use the -p option to select the changes you want to have in your commit.

Commit your changes with a descriptive commit message. Make sure to mention the ticket number with #XXX so github will 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

git pull upstream master

This ensures you have the latest code in your branch before you open your pull request. If there are any merge conflicts, 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

git push -u origin 001-name-of-your-branch-goes-here

The -u parameter ensures that your branch will now automatically push and pull from the github branch. That means if you type git push the next time it will know where to push to.

11. Open a pull request against upstream.

Go to your repository on github and click "Pull Request", choose your branch on the right and enter some more details in the comment box.

12. Someone will review your code

Someone will review your code, and you might be asked to make some changes, if so goto 6 (you don't need to open another pull request if your current one is still open). If your code is accepted it will be merged into the main branch and become part of the next Yii release. If not, don't be disheartened, different people need different features and Yii can't be everything to everyone, your code will still be available on github as a reference for people who need it