git-workflow.md 6.89 KB
Newer Older
1 2 3 4 5
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
6
and github, you might want to first check out [github help](http://help.github.com/), [try git](https://try.github.com)
7 8 9 10 11 12 13 14 15 16 17 18 19 20
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"

Alexander Makarov committed
21
Change to the directory where you cloned Yii, normally, "yii2". Then enter the following command:
22 23

```
Alexander Makarov committed
24
git remote add upstream git://github.com/yiisoft/yii2.git
25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159
```

### 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)

```
160 161
git clone git@github.com:YOUR-GITHUB-USERNAME/yii2.git
git remote add upstream git://github.com/yiisoft/yii2.git
162 163 164 165 166 167 168 169 170 171 172 173 174 175
```

```
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
```