From ec7546efa8ae1201a854c61b71fb322fd6d291b8 Mon Sep 17 00:00:00 2001 From: Alexander Makarov Date: Tue, 10 Dec 2013 23:14:22 +0100 Subject: [PATCH] Copied and adjusted 1.1 git workflow document --- docs/internals/git-workflow.md | 175 +++++++++++++++++++++++++++++++++++++++++ docs/internals/git.md | 13 --- 2 files changed, 175 insertions(+), 13 deletions(-) create mode 100644 docs/internals/git-workflow.md delete mode 100644 docs/internals/git.md diff --git a/docs/internals/git-workflow.md b/docs/internals/git-workflow.md new file mode 100644 index 0000000..3386df6 --- /dev/null +++ b/docs/internals/git-workflow.md @@ -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 +``` diff --git a/docs/internals/git.md b/docs/internals/git.md deleted file mode 100644 index 0d660aa..0000000 --- a/docs/internals/git.md +++ /dev/null @@ -1,13 +0,0 @@ -Git branches and tags -===================== - -Tags ----- - -Each release should be tagged with v2.X.X and message "Yii 2.X.X release". - -Branches --------- - -What should be in master branch? -Do we need another branches? \ No newline at end of file