Updated Typical Git Workflow (markdown)

bunnei 2014-06-16 11:30:29 -07:00
parent a642c1e0b3
commit b3f323d92b

@ -1,6 +1,6 @@
This is a guide to a typical Git workflow with Citra. It covers forking from the main repository, creating a branch, keeping your branch up to date with the main repository, resolving conflicts, and merging back into the main repository. It's not meant to be a hard-and-fast set of rules. However, if you following something along these lines, you'll be less likely to piss people off.
This is a guide to a typical Git workflow with Citra. It covers forking from the main repository, creating a branch, keeping your branch up to date with the main repository, resolving conflicts, and merging back into the main repository. It's not meant to be a hard-and-fast set of rules. However, if you follow something along these lines, you'll be less likely to piss people off.
It's appreciated if every single commit in a branch on its own compiles on all supported platforms and doesn't cause any regressions if the commits after it were left unmerged. We understand that with early development, sometimes it's easier to commit early-and-often, and sometimes you may unintentionally break things (and then later fix them in your branch). If this is part of your workflow, we expect appropriate use of git rebase to squash broken commits and resolve merge conflicts. If you don't know how git rebase works, please read [this article](http://git-scm.com/book/en/Git-Branching-Rebasing) before developing for Citra.
It's appreciated if every single commit in a branch on its own compiles on all supported platforms (Windows, Linux) and doesn't cause any regressions if the commits after it were left unmerged. We understand that with early development, sometimes it's easier to commit early-and-often, and sometimes you may unintentionally break things (and then later fix them in your branch). If this is part of your workflow, we expect appropriate use of Git rebase to squash broken commits and resolve merge conflicts. If you don't know how Git rebase works, please read [this article](http://git-scm.com/book/en/Git-Branching-Rebasing) before developing for Citra.
**Terminology**
* `upstream`: Main project repository (https://github.com/citra-emu/citra)
@ -12,32 +12,32 @@ It's appreciated if every single commit in a branch on its own compiles on all s
* `git clone https://github.com/your-username/citra.git`
* Set your `upstream` to the main project repository
* `git remote add upstream https://github.com/citra-emu/citra.git`
* Set your git identity configuration
* Set your Git identity configuration
* `git config --global user.name "your-username"`
* `git config --global user.email your-email@example.com`
**Create a new branch**
* Create your branch from the latest master (Note: please format-branch-names-like-this)
* Create your branch from the latest `upstream/master` (Note: please format-branch-names-like-this)
* `git fetch upstream && git checkout -b new-branch-name upstream/master`
* Push your new branch to origin (required later for a pull request)
* Push your new branch to `origin` (required later for a pull request)
* `git push origin new-branch-name`
**Scenario A: You did some work in your branch... Then, someone committed something to `upstream/master` that you want!**
* Make sure you're on your branch
* `git checkout new-branch-name`
* Rebase upstream/master onto it. With the rebase, move all of your changes to the top, and put all of the new master changes immediately after where you branched from. The goal should be that the branch now appears as though you just created it, and then committed all of your new stuff.
* Rebase `upstream/master` onto it. With the rebase, move all of your changes to the top, and put all of the new master changes immediately after where you branched from. The goal should be that the branch now appears as though you just created it from `upstream/master`, and then committed all of your new stuff.
* `git rebase -i upstream/master`
* Resolve any conflicts, then update `origin/new-branch-name` if you'd like
* `git push origin/new-branch-name --force`
**Scenario B: You did some more work in your branch... Then, someone committed something to `upstream/master` that will cause conflicts when trying to get the branch merged back to upstream/master!**
* Repeat the previous step (interactive rebase `upstream/master` to your branch)
* Resolve any conflicts, then update `origin/new-branch-name` if you'd like
* `git push origin/new-branch-name --force`
* From your branch, rebase `upstream/master`
* `git checkout new-branch-name`
* `git rebase -i upstream/master`
**Your branch is getting near completion, now you're ready for a pull request!**
* Repeat the previous step (interactive rebase `upstream/master` to your branch)
* Resolve any conflicts, then update origin/new-branch-name
* From your branch, rebase `upstream/master`
* `git checkout new-branch-name`
* `git rebase -i upstream/master`
* Update `origin/new-branch-name`
* `git push origin/new-branch-name --force`
* Create the pull request on GitHub to merge `origin/new-branch-name` into `upstream/master`
@ -48,9 +48,10 @@ It's appreciated if every single commit in a branch on its own compiles on all s
* From your branch, interactive rebase to squash all of the new commits (as a result of the pull request feedback) into the commits that they were addressing
* `git checkout new-branch-name`
* `git rebase -i HEAD~n`
* Repeat the previous step (interactive rebase `upstream/master` to your branch)
* Resolve any conflicts, then update origin/new-branch-name
* Rebase `upstream/master` onto your branch to ensure that you have any changes made since your pull request was created
* `git rebase -i upstream/master`
* Update `origin/new-branch-name`
* `git push origin/new-branch-name --force`
* Merge your branch in
* Always merge using the >merge< button in the GitHub pull request
* If GitHub says the branch cannot be merged automatically, you've likely done something incorrectly. If things don't work for you, don't hesitate asking us @ #citra on [freenode](http://webchat.freenode.net/). Mastering Git is not as easy as it might sound, but we'll happily help you get started.
* If GitHub says the branch cannot be merged automatically, you've likely done something incorrectly (e.g. you did not fully rebase changes from `upstream/master` into your branch). If things don't work for you, don't hesitate to ask us for help @ #citra on [freenode](http://webchat.freenode.net/). Mastering Git is not as easy as it might sound, but we'll happily help you get started.