Added a bit more info inc. stuff about --no-ff

This commit is contained in:
BRMatt 2010-07-29 19:43:12 +01:00
parent 710b2a0140
commit 9a15d3cd0d

View file

@ -16,7 +16,8 @@ First, you will need to tell git about the remote repository:
> git remote add kohana git://github.com/kohana/kohana.git
This tells git about the kohana repository and gives it a name which we can use to refer to it when fetching changes from the repository.
This tells git about the kohana repository and gives it a name which we can use to refer to it when
fetching changes from the repository.
## Developing locally
@ -26,43 +27,87 @@ There are 3 branches in the kohana/kohana repository:
* **3.0.x** This is a release branch for development of the 3.0.x series, i.e. 3.0, 3.0.3, 3.0.8 etc.
* **3.1.x** This is a release branch for development of the 3.1.x series, i.e. 3.1, 3.1.4, 3.1.14 etc.
To work on a specific release branch you need to check it out then check out the appropriate system branch (the system repo uses 3.0 and 3.1 instead of 3.0.x and 3.1.x).
To work on a specific release branch you need to check it out then check out the appropriate system branch.
Release branch names follow the same convention in both kohana/kohana and kohana/core.
i.e. to work on 3.0.x you'd do the following
To work on 3.0.x you'd do the following:
> git clone git://github.com/kohana/kohana.git
# ....
> cd kohana
> git submodule update --init
# ....
> git checkout 3.0.x
Switched to branch '3.0.x'
# Switched to branch '3.0.x'
> cd system
> git checkout 3.0
Switched to branch 3.0
> git checkout 3.0.x
# Switched to branch 3.0.x
**Note:** The last step is necessary due to the way that git submodules work.
It's important that you follow the last step, because unlike svn, git submodules point at a
specific commit rather than the tip of a branch. If you cd into the system folder after
a `git submodule update` and run `git status` you'll be told:
It is highly recommended that you run the unit tests while developing to ensure that any changes you make don't break the api. *See TESTING.md for more info*
# Not currently on any branch.
nothing to commit (working directory clean)
**IMPORTANT:** It is highly recommended that you run the unit tests whilst developing to
ensure that any changes you make do not break the api. *See TESTING.md for more info*
### Creating new features
New features or API breaking modifications should be developed in separate branches so as to isolate them until they're both stable and **tests have been written for the feature**.
When a new feature is complete and tested it can be merged into its respective release branch.
New features or API breaking modifications should be developed in separate branches so as to isolate them
until they're stable and **tests have been written for the feature**.
If a change you make intentionally breaks the api then please correct the relevant tests.
The naming convention for feature branches is:
feature/{issue number}-{short hyphenated description}
// i.e.
feature/4045-rewriting-config-system
When a new feature is complete and tested it can be merged into its respective release branch using
`git pull --no-ff`. The `--no-ff` switch is important as it tells git to always create a commit
detailing what branch you're merging from. This makes it a lot easier to analyse a feature's history.
Here's a quick example:
> git status
# On branch feature/4045-rewriting-everything
> git checkout 3.1.x
# Switched to branch '3.1.x'
> git merge --no-ff feature/4045-rewriting-everything
**If a change you make intentionally breaks the api then please correct the relevant tests before pushing!**
### Bug fixing
If you're making a bugfix then before you start create a unit test which reproduces the bug, using the @ticket notation to reference the bug's ticket number. When you run the tests then this test should fail.
If you're making a bugfix then before you start create a unit test which reproduces the bug,
using the `@ticket` notation in the test to reference the bug's issue number
(i.e. `@ticket 4045` for issue #4045).
Once you've written the bugfix run the tests again before you commit to make sure that the fix actually works, then commit the fix and the test.
If you run the test then the one you've just made should fail.
There is no need to create separate branches for bugfixes, creating them in the main release branch is perfectly acceptable.
Once you've written the bugfix, run the tests again before you commit to make sure that the
fix actually works,then commiti both the fix and the test.
There is no need to create separate branches for bugfixes, creating them in the main release
branch is perfectly acceptable.
## Merging Changes from Remote Repositories
Now that you have a remote repository, you can pull changes in the remote "kohana" repository into your local repository:
Now that you have a remote repository, you can pull changes in the remote "kohana" repository
into your local repository:
> git pull kohana master
**Note:** Before you pull changes you should make sure that any modifications you've made locally have been committed
**Note:** Before you pull changes you should make sure that any modifications you've made locally
have been committed.
Sometimes a commit you've made locally will conflict with one made in the "kohana" one.
@ -70,7 +115,8 @@ There are a couple of scenarios where this might happen:
### The conflict is to do with a few unrelated commits and you want to keep changes made in both commits
You'll need to manually modify the files to resolve the conflict, see the "Resolving a merge" section [in the git-scm book](http://book.git-scm.com/3_basic_branching_and_merging.html) for more info
You'll need to manually modify the files to resolve the conflict, see the "Resolving a merge"
section [in the git-scm book](http://book.git-scm.com/3_basic_branching_and_merging.html) for more info
### You've fixed something locally which someone else has already done in the remote repo
@ -82,18 +128,20 @@ You can do this using
### You've fixed something locally which someone else has already fixed but you also have separate commits you'd like to keep
If this is the case then you'll want to use a tool called rebase. First of all we need to get rid of the conflicts created due to the merge:
If this is the case then you'll want to use a tool called rebase. First of all we need to
get rid of the conflicts created due to the merge:
> git reset --hard HEAD
Then we find the hash of the offending local commit and run:
Then find the hash of the offending local commit and run:
> git rebase -i {commit hash}
> git rebase -i {offending commit hash}
i.e.
> git rebase -i 57d0b28
A text editor will open with a list of commits, delete the line containing the offending commit and then save & close your editor.
A text editor will open with a list of commits, delete the line containing the offending commit
before saving the file & closing your editor.
Git will remove the commit and you can then pull/merge the remote changes.