[[development-github]]
=== How we use git and github

[float]
==== Forking

We follow the https://help.github.com/articles/fork-a-repo/[GitHub
forking model] for collaborating on {kib} code. This model assumes that
you have a remote called `upstream` which points to the official {kib}
repo, which we'll refer to in later code snippets.

[float]
==== Branching

* All work on the next major release goes into master.
* Past major release branches are named `{majorVersion}.x`. They contain
work that will go into the next minor release. For example, if the next
minor release is `5.2.0`, work for it should go into the `5.x` branch.
* Past minor release branches are named `{majorVersion}.{minorVersion}`.
They contain work that will go into the next patch release. For example,
if the next patch release is `5.3.1`, work for it should go into the
`5.3` branch.
* All work is done on feature branches and merged into one of these
branches.
* Where appropriate, we'll backport changes into older release branches.

[float]
==== Commits and Merging

* Feel free to make as many commits as you want, while working on a
branch.
* When submitting a PR for review, please perform an interactive rebase
to present a logical history that's easy for the reviewers to follow.
* Please use your commit messages to include helpful information on your
changes, e.g. changes to APIs, UX changes, bugs fixed, and an
explanation of _why_ you made the changes that you did.
* Resolve merge conflicts by rebasing the target branch over your
feature branch, and force-pushing (see below for instructions).
* When merging, we'll squash your commits into a single commit.

[float]
===== Rebasing and fixing merge conflicts

Rebasing can be tricky, and fixing merge conflicts can be even trickier
because it involves force pushing. This is all compounded by the fact
that attempting to push a rebased branch remotely will be rejected by
git, and you'll be prompted to do a `pull`, which is not at all what you
should do (this will really mess up your branch's history).

Here's how you should rebase master onto your branch, and how to fix
merge conflicts when they arise.

First, make sure master is up-to-date.

["source","shell"]
-----------
git checkout master
git fetch upstream
git rebase upstream/master
-----------

Then, check out your branch and rebase master on top of it, which will
apply all of the new commits on master to your branch, and then apply
all of your branch's new commits after that.

["source","shell"]
-----------
git checkout name-of-your-branch
git rebase master
-----------

You want to make sure there are no merge conflicts. If there are merge
conflicts, git will pause the rebase and allow you to fix the conflicts
before continuing.

You can use `git status` to see which files contain conflicts. They'll
be the ones that aren't staged for commit. Open those files, and look
for where git has marked the conflicts. Resolve the conflicts so that
the changes you want to make to the code have been incorporated in a way
that doesn't destroy work that's been done in master. Refer to master's
commit history on GitHub if you need to gain a better understanding of how code is conflicting and how best to resolve it.

Once you've resolved all of the merge conflicts, use `git add -A` to stage them to be committed, and then use
 `git rebase --continue` to tell git to continue the rebase.

When the rebase has completed, you will need to force push your branch because the history is now completely different than what's on the remote. This is potentially dangerous because it will completely overwrite what you have on the remote, so you need to be sure that you haven't lost any work when resolving merge conflicts. (If there weren't any merge conflicts, then you can force push without having to worry about this.)

["source","shell"]
-----------
git push origin name-of-your-branch --force
-----------

This will overwrite the remote branch with what you have locally. You're done!

**Note that you should not run git pull**, for example in response to a push rejection like this:

["source","shell"]
-----------
! [rejected] name-of-your-branch -> name-of-your-branch (non-fast-forward)
error: failed to push some refs to 'https://github.com/YourGitHubHandle/kibana.git'
hint: Updates were rejected because the tip of your current branch is behind
hint: its remote counterpart. Integrate the remote changes (e.g.
hint: 'git pull ...') before pushing again.
hint: See the 'Note about fast-forwards' in 'git push --help' for details.
-----------

Assuming you've successfully rebased and you're happy with the code, you should force push instead.

[float]
==== Creating a pull request

See <<development-pull-request>> for the next steps on getting your code changes merged into {kib}.