Thanks for your interest in contributing to Sahana Vesuvius development. Our preferred means of receiving contributions is through pull requests. Make sure that your pull request follows our pull request guidelines before submitting it.

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.

Before accepting a contribution, we ask that you provide us a Contributor License Agreement. If you are making your contribution as part of work for your employer, please follow the guidelines on submitting a Corporate Contributor License Agreement. If you are making your contribution as an individual, you can submit a digital Individual Contributor License Agreement.

For more information, visit here.

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 Vesuvius 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 git@github.com:<mygitusername>/vesuvius
cd vesuvius
git remote add upstream git://github.com/sahana/vesuvius

Graphical Representation of the above code

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.

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.

For these reasons, it is preferable to use rebase rather than merge to include trunk changes into your local repository. Regardless of whether you rebase or merge, neither of these is a “safe” operation – you may make a mistake during the process, or encounter errors or conflicts. So before starting, a simple way to be sure you can go back to your unmodified branch is to make a copy of the branch. The following summary of commands assumes you are working on branch mychanges and want to save your work on branch mychanges_backup. It also assumes you have a master branch that mirrors branch master in trunk, and that you have a remote called upstream that points to the trunk repository. This setup makes it less convenient to use the git pull –rebase command, as that (now) requires that the remote and local branch have the same name. Here we show an alternative that does a pull into your local master branch, then a rebase from your updated master branch into your mychanges branch.

Code reviews help assure that code is correct before it gets accepted into trunk by having other people besides the author examine it, install it, test it, and comment on it. GitHub provides some very convenient features for conducting code reviews.

• The code author can push their changes to GitHub, which makes it easy for the reviewer to pull their changes into their own repository.
• GitHub allows commenting on specific lines in a file or in a diff between revisions. This makes it easy to show exactly what code is being commented on. It is not necessary to squash commits or make a pull request at this point, but the reviewer will need a way to see your changes as a whole.

To prepare for a code review:

• Optionally squash your commits.
• Push your changes to GitHub.

Before submitting code to be included in the trunk repository, several things should be done:

1. Rebase from trunk and deal with any merge conflicts.
2. Squash all commits in your change into one commit. This removes any false steps and re-working, and packages the related work together.
3. Test after rebasing.
4. Push your changes to your own fork of Eden on GitHub.
5. Ask for a code review if appropriate.
6. Once you are ready to submit your work, make a pull request: Click Pull Requests on the right side of the GitHub page for your repo then the New Pull Request button. *Note if you already have a pull request open, then changes you push to the branch that is the source of the pull request will be included in it automatically – you do not need to close the pull request and make a new one.

If you have made changes to one branch & wish to backport them to another branch, then this is done most easily using a Patch: How to create and apply a patch with Git

Tell git your name and email, which it uses to identify you as the author of commits. And tell it your account on GitHub.

git config --global user.name "Your Name"
git config --global user.email your@email.com

Sahana Vesuvius started using Bazaar & LaunchPad but has now switched to Git & GitHub.

For more information regarding the migration process, see this blog post.