Developer Workflow

Recommended Git Flow

All Sahana Vesuvius source code is managed by git, and hosted on GitHub under Sahana organizational account. Not only is GitHub used to host the source code, but also to facilitate collaboration via forks and pull requests. Sahana Vesuvius contributors are expected to follow the GitHub flow.

Fork The Sahana Vesuvius Repository

If you've not used GitHub before:

1. Sign-up for an account on GitHub
2. Set up git on you your computer by following these instructions.

• Note: In order to contribute code back to the Eden project, you need to "push" your changes to GitHub, and GitHub requires you to authenticate for that. The instructions describe authenticating using a password. If you don't want to do do that, you can use SSH keys instead. For more information, see links below.
• For Windows users
• For Linux users
• Generating SSH keys

Get your own copy of the Vesuvius repository on both GitHub and your local machine:

1. Fork the Eden repository at: https://github.com/sahana/vesuvius
2. Use git to clone your own new fork down to your PC, as follows:

cd /var/www
git clone [email protected]:<mygitusername>/vesuvius
cd vesuvius
git remote add upstream git://github.com/sahana/vesuvius

Graphical Representation of the above code

https://docs.google.com/drawings/d/1T2k_1fPxCLTqQ-xjZc7MS48Bk8o9rUrSkkvaQmzMGCM/edit

Coding Workflow

Summary of coding workflow using Git

cd /var/www/vesuvius

# Update your local repository with latest code from the trunk repository on GitHub
git pull --rebase upstream

# Write Code

# Quick review of code (no test code left in, etc)
git diff

# Check for any new files which need adding
git status
git add .

# Commit Code (Note, no pushes to GitHub here)
git commit -am "My Changes: Part 1"
.
.
.
git commit -am "My Changes: Part N"

# Pull in changes from trunk
git pull --rebase upstream

# Resolve any conflicts (see below for how)

# Commit fixed code
git add .
git commit -a

# Review commits
git log

# Squash commits
# Use rebase to squash commits to as few as possible to keep revision history clean & make it easier to review the work
# http://gitready.com/advanced/2009/02/10/squashing-commits-with-rebase.html
git rebase -i HEAD~N # Where N = Number of commits to squash

# Push to your branch on GitHub
git push

• Once you have pushed to your branch on GitHub, you will likely want this to be merged with Trunk - this should be done via a Pull Request. This is done at GitHub
• For more details, visit here.

Rebasing from Trunk

As you are working on a change, other changes will likely be added to the trunk repository. You may need some of those changes, or may just want to be sure your work fits in smoothly with them, or you may be preparing to submit your changes as a pull request to trunk. In these cases, you'll want to update the branch you're working on to include new revisions from trunk that are not yet in your local repository. The process for doing this is first "fetching" -- copying from the remote repository -- the new revisions from trunk, then either "rebasing" or "merging" to include them in the branch you want to update. Although rebasing and merging may end up with the same code, the process and "side effects" differ:

*Rebasing lifts your commits off of the common base your branch shared with trunk, then inserts the new trunk revisions, then applies your commits on top of those. Merging leaves your commits where they are, and adds the trunk revisions alongside them. *Rebasing ends with a linear sequence of commits -- each commit has a single child. Merging ends up with a directed acyclic graph of commits -- some commits will have multiple child commits, or multiple parents. If you encounter conflicts while rebasing, you will fix up each of your commits to deal with the conflicts, so when you're done, each of your commits will still be self-contained, free of conflicts, and consistent with the trunk commits that are its ancestors. Conflicts during a merge are handled together at the end of the merge, in a separate "merge commit" that consists of all the new commits that came from trunk, along with any edits you make to deal with merge conflicts. Your commits will still contain their conflicts -- those were fixed externally. *There is also a difference in how your commits will appear in the log, and in particular, what order they will be in once they are accepted into trunk. Rebased commits will be shown after the new trunk commits -- this is the same order in which users of the code will receive the changes if they are updating their deployments. Merged commits are shown at the time they were written, not at the time they became publicly available in trunk.

Resolving Merge Conflicts