Git is an extremely powerful distributed version control system that helps dRonin developers coordinate their work. While there's a bit of a learning curve to begin using Git, it's well worth it.
The individual Development Setup documentation pages (available for [Mac](🔗), [Windows](🔗), and [Linux](🔗)) document installing git and associated development tools. This page instead covers best practices for how to maintain your git repository.
Concept: forks
Every developer (and many users) has their own fork (copy) of the dRonin code repository with its own history. In this fork, changes can be made until they are "ready", when they can be submitted to the main dRonin fork as a pull request. When dRonin accepts this pull request, the history associated with those changes is appended to the dRonin revision control history.
It may also be helpful to run through the [tryGit tutorial](🔗) to become familiar with the git command line tools.
## Obtaining your own fork of the GitHub repository
[Create an account on GitHub](🔗).
Go to the [dRonin GitHub page](🔗).
Click the fork button:
Github Project Page: Fork
You will be taken to your fork's page. At the top, there will be an URL for your fork, in the format `https://github.com/yourusername/dRonin.git` – note this URL.
If you already have cloned from the main project... (not your fork)
Then you already have a clone, and you need to adjust your "origin" remote to point to your fork.
Instead of the following two steps, do this:
## Clone your fork locally
Follow the instructions for the development setup linked above, but when you clone the repository, provide your fork's URL:
## Add a remote for the main (upstream) dRonin project
After you create and clone your own fork, it is helpful to be able to access the primary project repository as well. To do this, execute the following commands:
## Getting the latest next
Your local fork just contains a snapshot of the origin (your fork) and upstream repositories. Later, to update it, just run these commands:
The first command (fetch) downloads all changes that have happened since last fetch; it does not change your working copy at all. `git checkout upstream/next` replaces your working copy with the current code from `next`, dRonin's development branch.
You should usually clean the build environment after updating or changing branches:
## Retrieving and testing other pull requests
It is also helpful to be able to retrieve and test other peoples' pull requests. There is a neat trick to make retrieving PRs easier from github. First, from your dronin repository edit `.git/config`. In the `[remote "upstream"]` section, add a new line that says:
After this, you can run a series of commands like:
to get source code of next with PR's 1000 and 1100 applied for testing.
## Set your user information
Git needs to know who you are so it can properly attribute your changes-- it won't let you commit until it's configured. So go ahead and tell it:
## Beginning a new feature branch
If you've spotted a bug, want to adjust some text in the project to be clearer, or are looking to add a new feature: Thank you! Here's how it works.
First, get the current development code, and clean your build environment:
Next, name your branch and begin your work:
This takes a virtual copy of the current branch (which should be current `next`), names it `myNiceBranch`, and checks it out into your `dRonin` directory.
You can now edit the source code files and make test builds. For each logical work item within the branch, you can add the files you want to commit (whether they're new or just have changes) and then commit them:
You'll be asked to type in a commit message. The first line is expected to be a short subject line that indicates the subsystem of the code and is 50 characters or less; subsequent lines can describe the changes in greater detail:
After this commit, you can continue working and producing additional change sets on this branch.
When the work is all done, you can run `git push` to send the contents of `myNiceBranch` to your fork on GitHub, and then visit your GitHub page to open a pull request for our review.
Advanced topics, not yet covered
Sometimes it's necessary to rebase, in order to get a clean revision history or to pick up changes from upstream.
For now, a brief tutorial on rebasing is here: http://rypress.com/tutorials/git/rebasing