Alexander Makarov
11 years ago
2 changed files with 175 additions and 13 deletions
@ -0,0 +1,175 @@
|
||||
Git workflow for Yii 2 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](http://help.github.com/), [learn git](http://gitref.org/) |
||||
or learn something about [git internal data model](http://nfarina.com/post/9868516270/git-is-simpler). |
||||
|
||||
### 1. [Fork](http://help.github.com/fork-a-repo/) the Yii repository on github and clone your fork to your development |
||||
environment |
||||
|
||||
``` |
||||
git clone git@github.com:YOUR-GITHUB-USERNAME/yii2.git |
||||
``` |
||||
|
||||
If you have trouble setting up GIT with GitHub in Linux, or are getting errors like "Permission Denied (publickey)", |
||||
then you must [setup your GIT installation to work with GitHub](http://help.github.com/linux-set-up-git/) |
||||
|
||||
### 2. Add the main Yii repository as an additional git remote called "upstream" |
||||
|
||||
Change to the directory where you cloned Yii, normally, "yii". Then enter the following command: |
||||
|
||||
``` |
||||
git remote add upstream git://github.com/yiisoft/yii.git |
||||
``` |
||||
|
||||
### 3. Make sure there is an issue created for the thing you are working on. |
||||
|
||||
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. |
||||
|
||||
> For small changes or documentation issues, 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 |
||||
|
||||
``` |
||||
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 |
||||
|
||||
> 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. |
||||
|
||||
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. If you aren't fixing any particular issue, just skip number. |
||||
For example: |
||||
|
||||
``` |
||||
git checkout upstream/master |
||||
git checkout -b 999-name-of-your-branch-goes-here |
||||
``` |
||||
|
||||
### 6. 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 |
||||
|
||||
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: |
||||
|
||||
``` |
||||
Bug #999: a description of the bug fix (Your Name) |
||||
Enh #999: a description of the enhancement (Your Name) |
||||
``` |
||||
|
||||
`#999` is the issue number that the `Bug` or `Enh` is referring to. |
||||
The changelog should be grouped by type (`Bug`,`Enh`) and ordered by issue number. |
||||
|
||||
For very small fixes, e.g. typos and documentation changes, there is no need to update the CHANGELOG. |
||||
|
||||
### 8. Commit your changes |
||||
|
||||
add the files/changes you want to commit to the [staging area](http://gitref.org/basic/#add) 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 999-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](http://help.github.com/send-pull-requests/) 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. To link the pull request to the issue put anywhere in the pull comment `#999` where 999 is the |
||||
issue number. |
||||
|
||||
> Note that each pull-request should fix a single change. |
||||
|
||||
### 12. Someone will review your code |
||||
|
||||
Someone will review your code, and you might be asked to make some changes, if so go to step #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. |
||||
|
||||
### 13. Cleaning it up |
||||
|
||||
After your code was either accepted or declined you can delete branches you've worked with from your local repository |
||||
and `origin`. |
||||
|
||||
``` |
||||
git checkout master |
||||
git branch -D 999-name-of-your-branch-goes-here |
||||
git push origin --delete 999-name-of-your-branch-goes-here |
||||
``` |
||||
|
||||
### Note: |
||||
|
||||
To detect regressions early every merge to the Yii codebase on github will be picked up by |
||||
[Travis CI](http://travis-ci.org) for an automated testrun. As core team doesn't wish to overtax this service, |
||||
[`[ci skip]`](http://about.travis-ci.org/docs/user/how-to-skip-a-build/) will be included to the merge description if |
||||
the pull request: |
||||
|
||||
* affect javascript, css or image files only, |
||||
* updates the documentation, |
||||
* modify fixed strings only (e.g. translation updates) |
||||
|
||||
Doing so will save travis from commencing testruns on changes that are not covered by tests in the first place. |
||||
|
||||
### Command overview (for advanced contributors) |
||||
|
||||
``` |
||||
git clone git@github.com:YOUR-GITHUB-USERNAME/yii.git |
||||
git remote add upstream git://github.com/yiisoft/yii.github |
||||
``` |
||||
|
||||
``` |
||||
git fetch upstream |
||||
git checkout upstream/master |
||||
git checkout -b 999-name-of-your-branch-goes-here |
||||
|
||||
/* do your magic, update changelog if needed */ |
||||
|
||||
git add path/to/my/file.php |
||||
git commit -m "A brief description of this change which fixes #42 goes here" |
||||
git pull upstream master |
||||
git push -u origin 999-name-of-your-branch-goes-here |
||||
``` |
Loading…
Reference in new issue