DEVELOPERS.md

   1 # Distributed Source Control Management
   2
   3 Unlike SVN, git does not used a central repository. This is why git is "distributed" and SVN is
   4 "centralized". Although this makes git an extremely powerful system for collaborators, tracking
   5 changes between various collaborators can quickly become difficult as multiple forks are created.
   6
   7 Please read the following before working with this code:
   8
   9 1. [Dealing with newlines](http://github.com/guides/dealing-with-newlines-in-git)
  10 2. [Submitting changes from your fork](http://github.com/guides/fork-a-project-and-submit-your-modifications)
  11 3. [Using SSH keys with github](http://github.com/guides/how-to-not-have-to-type-your-password-for-every-push)
  12
  13 ## Managing Remote Repositories
  14
  15 First, you will need to tell git about the remote repository:
  16
  17     > git remote add kohana git://github.com/kohana/kohana.git
  18
  19 This tells git about the kohana repository and gives it a name which we can use to refer to it when
  20 fetching changes from the repository.
  21
  22 ## Developing locally
  23
  24 There are 3 branches in the kohana/kohana repository:
  25
  26 * **master** This branch always points to the latest release tag. In essence it points to the last stable edition of the codebase
  27 * **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.
  28 * **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.
  29
  30 To work on a specific release branch you need to check it out then check out the appropriate system branch.
  31 Release branch names follow the same convention in both kohana/kohana and kohana/core.
  32
  33 To work on 3.0.x you'd do the following:
  34
  35         > git clone git://github.com/kohana/kohana.git
  36         # ....
  37
  38         > cd kohana
  39         > git submodule update --init
  40         # ....
  41
  42         > git checkout 3.0.x
  43         # Switched to branch '3.0.x'
  44
  45         > cd system
  46         > git checkout 3.0.x
  47         # Switched to branch 3.0.x
  48
  49 It's important that you follow the last step, because unlike svn, git submodules point at a
  50 specific commit rather than the tip of a branch.  If you cd into the system folder after
  51 a `git submodule update` and run `git status` you'll be told:
  52
  53         # Not currently on any branch.
  54         nothing to commit (working directory clean)
  55
  56 **IMPORTANT:** It is highly recommended that you run the unit tests whilst developing to
  57 ensure that any changes you make do not break the api. *See TESTING.md for more info*
  58
  59 ### Creating new features
  60
  61 New features or API breaking modifications should be developed in separate branches so as to isolate them
  62 until they're stable and **tests have been written for the feature**.
  63
  64 The naming convention for feature branches is:
  65
  66         feature/{issue number}-{short hyphenated description}
  67
  68         // i.e.
  69
  70         feature/4045-rewriting-config-system
  71
  72 When a new feature is complete and tested it can be merged into its respective release branch using
  73 `git pull --no-ff`. The `--no-ff` switch is important as it tells git to always create a commit
  74 detailing what branch you're merging from. This makes it a lot easier to analyse a feature's history.
  75
  76 Here's a quick example:
  77
  78         > git status
  79         # On branch feature/4045-rewriting-everything
  80
  81         > git checkout 3.1.x
  82         # Switched to branch '3.1.x'
  83
  84         > git merge --no-ff feature/4045-rewriting-everything
  85
  86 **If a change you make intentionally breaks the api then please correct the relevant tests before pushing!**
  87
  88 ### Bug fixing
  89
  90 If you're making a bugfix then before you start create a unit test which reproduces the bug,
  91 using the `@ticket` notation in the test to reference the bug's issue number
  92 (i.e. `@ticket 4045` for issue #4045).
  93
  94 If you run the test then the one you've just made should fail.
  95
  96 Once you've written the bugfix, run the tests again before you commit to make sure that the
  97 fix actually works,then commiti both the fix and the test.
  98
  99 There is no need to create separate branches for bugfixes, creating them in the main release
 100 branch is perfectly acceptable.
 101
 102 ## Merging Changes from Remote Repositories
 103
 104 Now that you have a remote repository, you can pull changes in the remote "kohana" repository
 105 into your local repository:
 106
 107     > git pull kohana master
 108
 109 **Note:** Before you pull changes you should make sure that any modifications you've made locally
 110 have been committed.
 111
 112 Sometimes a commit you've made locally will conflict with one made in the "kohana" one.
 113
 114 There are a couple of scenarios where this might happen:
 115
 116 ### The conflict is to do with a few unrelated commits and you want to keep changes made in both commits
 117
 118 You'll need to manually modify the files to resolve the conflict, see the "Resolving a merge"
 119 section [in the git-scm book](http://book.git-scm.com/3_basic_branching_and_merging.html) for more info
 120
 121 ### You've fixed something locally which someone else has already done in the remote repo
 122
 123 The simplest way to fix this is to remove all the changes that you've made locally.
 124
 125 You can do this using
 126
 127     > git reset --hard kohana
 128
 129 ### You've fixed something locally which someone else has already fixed but you also have separate commits you'd like to keep
 130
 131 If this is the case then you'll want to use a tool called rebase.  First of all we need to
 132 get rid of the conflicts created due to the merge:
 133
 134     > git reset --hard HEAD
 135
 136 Then find the hash of the offending local commit and run:
 137
 138     > git rebase -i {offending commit hash}
 139
 140 i.e.
 141
 142         > git rebase -i 57d0b28
 143
 144 A text editor will open with a list of commits, delete the line containing the offending commit
 145 before saving the file & closing your editor.
 146
 147 Git will remove the commit and you can then pull/merge the remote changes.