User:Callahanp/git-workflow

From FlightGear wiki
Jump to: navigation, search

The workflow depends on the creation of so called forks of the flightgear and simgear projects and possibly others. These forks should reside on Sourceforge for Flightgear and Simgear, and possibly other repository systems for things like Open Scene Graph and Plib. You, the developer create these forks as a registered user on Sourceforge or other repository system.

The forks are your way of communicating your changes to the core developers. You'll need to remember two "aliases" commonly used in git operations: origin, meaning your forks, and upstream, meaning the official repositories. Origin and Upstream are historical terms and you may be confused if you try to use these terms as if they retain their english language meaning while using git. Just try to think of them as "aliases" for the locations of your forks (origin) and the official repositories (upstream). Each component will have an origin and an upstream.


The following is from an e-mail message from F Rougon.

Proposed workflow:

0) After having cloned (using the SF web interface) the repositories you intend to contribute to, set denyNonFastforwards=false on the SF server for all your forks (details in my previous message), or accept to delete a branch on your personal fork before repushing it when you need to force-update it.

1) Clone these forks to your hard drive and prepare changes locally on a specific branch. We assume from now on that the branch in question is checked out.

2) Run 'git branch --set-upstream-to=upstream/next', where 'upstream' is the name of the upstream remote (official FG repo, not your personal fork). This only needs to be done once per branch, and Git reminds you for certain operations like 'git pull --rebase' in case you forgot it.

3) Push the branch to your personal fork ('git push origin $branch', where 'origin' is the remote name for your personal fork at SourceForge).

4) File a merge request where you designate the branch and tell SF that the changes should be merged to 'next' (normally). Receive comments on your changes. From now on, we assume you need to change something in your commits before they can be considered good for merging.

5) Update your branch locally ('git commit --amend', 'git rebase -i $afterThisCommit'...).

6) Run 'git pull --rebase' in case the official repo's 'next' branch had commits since your changes (this is where step 2 matters: it tells Git where to get upstream changes from). It can't harm, even there were no new commits upstream. If there was a conflict, resolve it and repeat this step.

7) Force-push your branch to your personal fork using 'git push origin +$branch', where 'origin' is the remote name for your personal fork (if you didn't do the denyNonFastforwards=false setup of step 0, run 'git push origin --delete $branch' followed by 'git push origin $branch').

8) Click on the “Refresh commits” button of the SF page containing your merge request.

9) Add a comment there to notify people about the fact that you've refreshed the commits.

Beware of the Git remote names: in the above workflow, 'origin' is the remote where your SF fork lives (as set up by default as part of steps 0 and 1). This will be the case if you cloned your SF fork to your computer. But if you obtained the repo using d&c or 'git clone' from the official FG repos, the 'origin' remote will by default point to the corresponding official FG repo. Remotes can be easily renamed using 'git remote rename <old> <new>' inside a given repository.