Version Control

** Using Mercurial Cheat Sheet ** We need a system that will allow the team to work on projects and tasks independently from each other without micromanaging and allowing build-testing and rollbacks to avoid bugs, allow updates of versions and merging, viewing of all versions of code.

=Eclipse=

Eclipse can be handy for version control, as it has built-in version control functionality, and works (on Windows at least) with some fuss to compile Arduino code. See the Eclipse page if you have free time and would like to try to set it up on your computer.

=Mercurial=

Why Mercurial is better than Subversion (according to Mercurial): http://hginit.com/

Mercurial section of the Mozilla project: https://developer.mozilla.org/en/Mercurial

Some scary warnings about using Mercurial

Portable Mercurial
These are the links to install on your Z: drive:

http://mercurial.selenic.com/downloads/ Inno installers dont require admin priviledges, the x86 version is for 32 bit operating systems, x64 for 64 bit.

http://sourceforge.net/projects/kdiff3/files/kdiff3/0.9.95/ KDiff3, for merging, you'll want this later; get the *.exe with the large number of downloads (for Windows).

Install these to Z:\Mercurial and Z:\KDiff3

TortoiseHg requires admin priviledges, but can perhaps be run off a flash drive, (also http://stackoverflow.com/questions/1904419/running-mercurial-on-a-flash-drive Command-line mercurial can run off a flash drive.)

First Run Guide (command line)
If you're using Eclipse or TortoiseHg or some front-end, the steps are the same, you just dont have to use these command-line commands.

Install Mercurial (hg) and KDiff3. If you have any trouble with these instructions (programs not found) on windows try the following in a command prompt (change to your install locations). path = $PATH$;Z:\Mercurial;Z:\KDiff3

First pull or clone the qmast repository. hg clone https://qmast.googlecode.com/hg/ qmast (OR) hg pull When you pull the repository, you may be asked to update to get a working copy. This is achieved by typing: hg update Now your repository will be ready to work on. Then make changes to a file, in the qmast folder mercurial just created. Save the file. Note: if you add a file to this directory there's this extra step: hg add (this updates the repository to include any new files in the folder that aren't already tracked) Check what the difference between the old and new repository is; (hg status will list files that have changed with a code-character in front, ? and ! characters are bad news and require updating the repo ) hg status hg diff If it looks good, commit it with a useful informative, short comment. (see the googleCode issue updating from commits page for some cool things you can do with your commit logs) hg commit -u YourGoogleUsername -m "First commit! :) (test)" This worked? Great! Skip to the next paragraph. If not, stay here. If you're working off your Z:\ drive and get the error "Abort: none: the system cannot find the file specified" try copying and pasting the notepad.exe (found in C:\WINDOWS\system32 ) file to the repository (or possibly, anywhere on your Z:\ drive).

Make other changes, save the world with your awesome coding skills, committing when you want to save a "screenshot" of your code. Now to share it with everyone: First check the list of commits you're about to share: hg outgoing Looks good? Share! This updates the code on the repo with YOUR version! hg push https://YourGoogleUsername:YourGoogleCODEpassword@qmast.googlecode.com/hg/ If there is an error about merging, there's very little code needed to fix it. Type: hg merge You should now get a message about uncommitted merges. Commit your file as indicated above using the commit command. If there are multiple heads, you will have to repeat this process until you no longer get any errors about merging. Below is an in depth discussion for merging with KDiff.
 * Your Google CODE password is NOT the same as your gmail password. It is autogenerated and can be found under your Settings tab****

External Diff/Merge Setup
External software that allows comparisons for diff-ing and merging is critical once you get into merging different people's changes together.

I installed KDiff3 from the .exe on windows here, no problems with admin privileges on my Z:/ drive.

Then, (this makes KDiff3 accessible everywhere into that command prompt is closed) run -> cmd -> :\> path = $PATH$;Z:\KDiff3

External merge configuration just comes down to editing the ~/.hgrc file to have the proper settings.

Mercurial book, section about merging theory

Trouble-shooting kdiff3 and mercurial setup

How to install and setup mercurials .hgrc (and it's location on Windows, Unix); good instructions, not sure about some of the hgrc diff flags

Directions to setup an external merge program in mercurial, no examples, some tips

Sample ~/.hgrc file

Mine looks like this on linux, seems to work for pushing at least: [ui] username = C Blair merge = kdiff3 [extensions] hgext.extdiff = [extdiff] cmd.kdiff3 = [merge-tools] kdiff3.args = $base $local $other -o $output [defaults] commit = -v

For Windows, I edited Z:\Mercurial\Mercurial.ini : (removed the lines which were commented out; this works to push and merge; the [merge-tools] section could probably just be cut down to the kdiff3 stuff) [ui] editor = notepad username = C Blair merge = kdiff3 [extensions] hgext.extdiff = [extdiff] cmd.kdiff3 = [merge-tools] kdiff3.args=--auto --L1 base --L2 local --L3 other $base $local $other -o $output kdiff3.regkey=Software\KDiff3 kdiff3.regappend=\kdiff3.exe kdiff3.fixeol=True kdiff3.gui=True kdiff3.diffargs=--L1 '$plabel1' --L2 '$clabel' $parent $child gvimdiff.args=--nofork -d -g -O $local $other $base gvimdiff.regkey=Software\Vim\GVim gvimdiff.regname=path gvimdiff.priority=-9 vimdiff.args=$local $other $base vimdiff.priority=-10 merge.checkconflicts=True merge.priority=-100 gpyfm.gui=True meld.gui=True meld.args=--label='local' $local --label='base' $base --label='other' $other meld.diffargs=-a --label='$plabel1' $parent --label='$clabel' $child tkdiff.args=$local $other -a $base -o $output tkdiff.gui=True tkdiff.priority=-8 tkdiff.diffargs=-L '$plabel1' $parent -L '$clabel' $child xxdiff.args=--show-merged-pane --exit-with-merge-status --title1 local --title2 base --title3 other --merged-filename $output --merge $local $base $other xxdiff.gui=True xxdiff.priority=-8 xxdiff.diffargs=--title1 '$plabel1' $parent --title2 '$clabel' $child diffmerge.regkey=Software\SourceGear\SourceGear DiffMerge\ diffmerge.regname=Location diffmerge.priority=-7 diffmerge.args=-nosplash -merge -title1=local -title2=merged -title3=other $local $base $other -result=$output diffmerge.checkchanged=True diffmerge.gui=True diffmerge.diffargs=--nosplash --title1='$plabel1' --title2='$clabel' $parent $child p4merge.args=$base $local $other $output p4merge.regkey=Software\Perforce\Environment p4merge.regname=P4INSTROOT p4merge.regappend=\p4merge.exe p4merge.gui=True p4merge.priority=-8 p4merge.diffargs=$parent $child tortoisemerge.args=/base:$base /mine:$local /theirs:$other /merged:$output tortoisemerge.regkey=Software\TortoiseSVN tortoisemerge.checkchanged=True tortoisemerge.gui=True tortoisemerge.priority=-8 tortoisemerge.diffargs=/base:$parent /mine:$child /basename:'$plabel1' /minename:'$clabel' ecmerge.args=$base $local $other --mode=merge3 --title0=base --title1=local --title2=other --to=$output ecmerge.regkey=Software\Elli\xc3\xa9 Computing\Merge ecmerge.gui=True ecmerge.diffargs=$parent $child --mode=diff2 --title1='$plabel1' --title2='$clabel' filemerge.executable=/Developer/Applications/Utilities/FileMerge.app/Contents/MacOS/FileMerge filemerge.args=-left $other -right $local -ancestor $base -merge $output filemerge.gui=True ; Windows version of Beyond Compare beyondcompare3.args=$local $other $base $output /ro /lefttitle=local /centertitle=base /righttitle=other /automerge /reviewconflicts /solo beyondcompare3.regkey=Software\Scooter Software\Beyond Compare 3 beyondcompare3.regname=ExePath beyondcompare3.gui=True beyondcompare3.priority=-2 beyondcompare3.diffargs=/lro /lefttitle='$plabel1' /righttitle='$clabel' /solo /expandall $parent $child ; Linux version of Beyond Compare bcompare.args=$local $other $base -mergeoutput=$output -ro -lefttitle=parent1 -centertitle=base -righttitle=parent2 -outputtitle=merged -automerge -reviewconflicts -solo bcompare.premerge=False bcompare.gui=True bcompare.priority=-1 bcompare.diffargs=-lro -lefttitle='$plabel1' -righttitle='$clabel' -solo -expandall $parent $child winmerge.args=/e /x /wl /ub /dl other /dr local $other $local $output winmerge.regkey=Software\Thingamahoochie\WinMerge winmerge.regname=Executable winmerge.checkchanged=True winmerge.gui=True winmerge.priority=-10 winmerge.diffargs=/r /e /x /ub /wl /dl '$plabel1' /dr '$clabel' $parent $child araxis.regkey=SOFTWARE\Classes\TypeLib\{46799e0a-7bd1-4330-911c-9660bb964ea2}\7.0\HELPDIR araxis.regappend=\ConsoleCompare.exe araxis.priority=-2 araxis.args=/3 /a2 /wait /merge /title1:"Other" /title2:"Base" /title3:"Local :"$local $other $base $local $output araxis.premerge=False araxis.checkconflict=True araxis.binary=True araxis.gui=True araxis.diffargs=/2 /wait /title1:"$plabel1" /title2:"$clabel" $parent $child diffuse.priority=-3 diffuse.args=$local $base $other diffuse.gui=True diffuse.diffargs=$parent $child UltraCompare.regkey=Software\Microsoft\Windows\CurrentVersion\App Paths\UC.exe UltraCompare.args = $base $local $other -title1 base -title3 other UltraCompare.priority = -2 UltraCompare.gui = True UltraCompare.binary = True UltraCompare.checkconflicts = True UltraCompare.checkchanged = True UltraCompare.diffargs=$child $parent -title1 $clabel -title2 $plabel1 [web] cacerts=U:\Mercurial\cacert.pem [defaults] commit = -v
 * 1) Some default global settings for common merge tools

I also went to Windows -> Preferences -> Team -> Mercurial and ticked "Use external merge tool" option in Eclipse, and installed kdiff3 to my Z drive.

Using command-line hg, I created a merge conflict (pulled from one computer, made a change on another computer and pushed, then changed the same line in the file on the first computer) and tried to push, as above. Was warned, so did

hg pull

Was warned that I should merge, so

hg merge

KDiff3 opened, as per my settings. I copied the proper fix into the Output box, and then clicked "Merge" (the diamond-arrow picture). It didn't seem to be doing anything though. Tried saving, clicking merge - I feel like each time I did this it was actually just merging the output as an input? Once I exited, hg detected that KDiff3 had closed and prompted me to commit. Tada!

Update: KDiff3 will not let you Save until all conflicting merges are dealt with. Once you've saved, you can close KDiff3 and your changes will be recorded, and you'll return to hg. The "Merge" button has nothing to do with this; just wrong-click on any "?" lines in the output box, select which version (A or B) you want (or edit the Merge Conflict line by hand) to fix merge conflicts. There is a button that will go to the next Merge Conflict, useful for when you're not sure why you can't save.

=Hosting Services= There are many hosting services around the internet. We looked at GoogleCode and Launchpad, presently we're using GoogleCode.

Google Code
This is what we wound up going with.

https://code.google.com/p/qmast/ Our project

http://blogs.intland.com/main/entry/39 Good tutorial on using google code from eclipse

http://code.google.com/p/googlecode-mylyn-connector/ Eclipse task list to google code issue list connector

Launchpad
Bazaar-driven project code repository and feature request form

Plugin for bazaar/eclipse integration necessary to save a step using launchpad and eclipse and not really working (could just test in eclipse and then bzr the files)

Version control software tracks changes. Launchpad also tracks bugs and allows descriptions of future features (which I've setup as our major tasks, though I'm sure there are other ways to do it).

Good directions for creating local branches on launchpad with bazaar

QMAST on launchpad This is our project. Bazaar on my computer seems very tempermental with when it will allow me to push - it worked well directly after booting, and pushed once.

bzr push --use-existing lp:qmast