My Experience authoring an open source project on github

If you are an active reader of the blog here, you know that I have participated in an open source project on Github. It was way back in late 2009 that I found an Augmented Reality project there. At the time this was the up and up and AR was just starting to take off on the iPhone. However there was one same problem; the author who begun the project, started developing and then abandoned the code.

Github has a great feature (and bad, that I'll discuss here) to fork a project. So the fun began, I forked the project, cleaned up a ton of code, made the project more of a tool kit and finally got the code working the way I thought it should. All was good. However, the toolkit was far from done. I had big dreams of really making this in into the toolkit thousands of developers would use. I even created it as a static library that could be linked easily into other developers projects.

Right about at this time, as human as we all are, I was going thru a life changing event (a divorce). Needless to say I was not able to work on the project as much as I would have liked (none at all actually). During this time, a few people had forked the project and began making their own changes. That's the beauty of github. If you don't like what you see, you can fork it and begin making your own changes. Hopefully the changes made are good enough the project that it's forked from will pull this code into their branch. It's a win win for everyone.

Since I no longer had the time to make all the changes on my own, I was able to merge the code that others had made, which in turn made the toolkit even better! This is the the beauty and the beast of Open Source.

Let's go over what I've learned.

The Good

While I was not able to work on the code, others had stepped up. A couple found some memory leaks and fixed them. That was awesome.

Another developer decided that maybe using a static library was not the best idea, since many people found it confusing. So he moved it out of the library and back into the main project. Great! The toolkit still had life.

Github can merge other people's code back into a branch as long as the changes are not too drastic. At this point pretty much all the changes other's had made could be merged with no effort on my end. So why not include the changes? We had my fork of the project going still strong and in many ways I was still in control. (Even when I was not really working on it.) However, I still had the final say that would be merged into my code base. All was good! Or least I thought it was...

The Bad

At this point, the project was stale. I was not checking on the updates, nor even responding to the emails from people who needed help or had suggestions to make it beter. (Sorry guys). There were still forks of the project going on. However it was not from my project, but from others whom had forked my toolkit. By the time I gotten back into having some free time to review the changes again, the project was a complete mess. We had way too many forked versions and some really bad versions began to popup.

To make matters worse, I had developed the toolkit for the iPhone 3 and now iOS4 was out with major changes to the framework. The project was in a deep pile of crap as I'd like to say.

The Ugly

This is where it really gets bad. One of the forks was created from someone who had the best intentions but I seriously judge the changes they were making. I don't think they really knew what they were doing.

Since I was not maintaining my project, this fork now became the fork that people were using because it seemed to be the most active. (I would have done the same) With this version, many bugs were introduced and people were making changes to the code base that made life very difficult to merge back to mine.

I began getting emails from people asking if I could fix my version of the project (code did break with iOS 4) because the other forked projects were so unstable. I became to feel their pain. It's time to get back into the game again...

A New Hope

Yesterday I finally got some free time and went thru all my issues and began to fix the problems that others had found. I fixed the code so that it would run in xCode 4.2 and run on the iPhone 4. I also reviewed some changes that were made by other forks that I thought were good and added them to the toolkit. Someone even created the app Icon, so I grab that and added it too. Thank you by the way!

Now I have the project updated and I hope people can grab this version and begin using the AR toolkit again. I'm so excited about the project again that I plan on making some new code updates to make the toolkit even better!

As you can see, this seems to be the typical problem that happens with an open source project. If there's no one core owner to keep the dream alive, or the wrong people take over, a project can go sideways pretty quickly. I'm glad to be back, I'm grateful for the people who were able to contribute the changes to what I believe to be a good learning tool in the world of Augmented Reality!

Thanks to all the people who kept it going!

5 Reasons why to switch to Git

I'm going to predict that 2010 is the year where Git becomes the defacto version control for most open source projects. I also think Git will see a wide spread use from corporations but not as fast because of the slow adoption of anything new. If you've not heard of Git, I strongly suggest to check it out. I was skeptical myself. I had just moved over to Subversion a few years ago from CVS and that from Visual Source Safe. The last thing I wanted to do was learn another version control and SVN seemed to do the job. That was until over the winter break I was looking for a project on GitHub and needed to use Git to download the source code. I instantly fell in love with it. All the things I loved about SVN it seemed to do better and all the problems of SVN seem to have been solved! Reason's why to start using Git

#1 Local Repository features

The one advantage Git has over other repositories is how much you can actually do on the local version. Besides doing a fetch, push or a pull, most commands are done locally. The ability to do a diff locally without hitting the server can save a ton of time.

One feature I like is creating local branches that I can do all my work on and not have the fear of messing up the remote repository with my changes because I committed the changes. Now I can work locally, make as many commits as I need to and if I have to rollback I can do so with no worries. Once I have the version that is what I feel is good for everyone on the team to use, I can simply commit to the remote repository.

#2 The staging area

The staging area is a great idea. Sometimes you have code that you're not quiet sure you want to commit but you want to store it in a place while you continue to work on the file. If the changes made in working directory have gone 180 on you still have the code in the staging area. However, If satisfied with the new code, simply add the code to the staging area again. Then use the commit command and the code is moved from staging to the local repository.

The main advantage of using the staging area is that when committing to the repository only the files ready to be committed are actually added. This avoids accidentally sending files in the working directory that may not be ready. Git does not force the developer to have to use the staging feature. Directly going from the working directory to the local repository can be done by adding the -a option when issuing the commit command. However, remember that using the -a argument of the commit command, sends all the modified files that were added previously to the local repository. This has been a hard habit to break for myself since I'm so used to the way SVN handles commits, that I was using the commit command with the -a option. Now what I know of the advantages of staging, I can avoid these problems I've had in the past.

#3 Local Branching is super easy

Local branching allows for the developer to create as many branches without having to have them stored on the the remote repository! Keep one(1) branch for production, one (1) for development where to do all work in, and then other branches for experimental work.

The beauty is that switching between branches is as quick as typing the branch name. Simply type git checkout <Your Branch Name> and the working directory has switched over to the selected branch. It's very easy to then merge changes from each branch. Again this is all done locally. These branches can stay local or any branch can be added to the remote repository.

#4 Cloning a remote Repository gives you the entire repository!

When cloning from remote repository, a complete copy is added to the local repository, not the current version like how Subversion handles it. This alone has many advantages. If working offline because the internet connection is down, or on a train or plane, the entire repository is still available for all the features normally found only when making calls back to the remote repository. The ability to continue to make commits when offline is a huge deal! Commit the changes later when back online!

#5 Github.com rocks

There is no better place to host open source or host your private repositories than Github! Github has a great set of features that are simply amazing. Open source projects are free but to host a private repository will cost a few bucks a month. The prices are cheap and offer so many features that's its a no brainer to use them to host your projects!

Summary

I love SVN but when something better comes along that you can't simply ignore it because your comfortable with something else. I'll still have to use Subversion for some of my older projects, but from now on, all new projects will be using Git and Github.com. Sorry Subversion but it's time we parted our ways! :)

Progress made to the Augmented Reality Toolkit. Now a static library!

Today we're please to announce that we've updated the source code on Github.  The latest set of changes made this week fixes  the orientation issue that's been driving me nuts.

A Static Library - Finally!

The project now has the core of the toolkit put into a static library.  Why is this important? In the future when this project has matured, it will allow anyone to add the library to their projects.

We've still have a long way to go. One of the changes we want to have is the ability for any type of view to be added to augmented Reality layer.

Orientation works in both landscape and portrait modes

Woot! We finally got this one piece of code figured out.  It really came down to some simple math.  When the orientation of the phone changes, we need to adjust the azimuth.  We also fixed a stupid mistake where we were checking the same orientation direction instead of checking the left AND right.

The final a-ha moment came in the determining the angle of the phone to know where to draw the y position of a view.

   1:  switch (currentOrientation) {

   2:    case UIDeviceOrientationLandscapeLeft:

   3:       viewAngle = atan2(acceleration.x, acceleration.z);

   4:       break;

   5:   

   6:    case UIDeviceOrientationLandscapeRight:

   7:       viewAngle = atan2(-acceleration.x, acceleration.z);

   8:       break;

   9:   

  10:    case UIDeviceOrientationPortrait:

  11:       viewAngle = atan2(acceleration.y, acceleration.z);

  12:       break;

  13:   

  14:    case UIDeviceOrientationPortraitUpsideDown:

  15:       viewAngle = atan2(-acceleration.y, acceleration.z);

  16:       break;

  17:   

  18:    default:

  19:       break;

  20:  }

As you can see, determining the angle we need to use the y acceleration in portrait mode and the x acceleration in landscape mode.  However, there was one more thing we had to do to make sure the functionality behaved the same way, regardless of the orientation.  We needed to adjust the  x value as negative when the iPhone is in Landscape Right and the y value when the iPhone is upside down. (Not sure why one would do it upside down but we added the functionality anyways!)

Scaling issue resolved!

We finally go the scaling of the views working now too! The funny thing all we had to do was uncomment out the code we had commented out before and it started working.  The problem was solved by another bug we fixed a while back but forgot to uncomment the block code that was scaling the views down to nothing.

What's next?

Now that we have the bare minimum working now by simplifying the code and getting it to work for all orientations and adding it to a static library, we can now get to the fun part.  Making it into a real toolkit.  

I don't recommend forking the project just yet because I still see a ton of refactoring that will go on from the project we forked from to get it to an acceptable toolkit.  My big projects are slowing down a bit right now so I feel I can spend a little more on this project than I had the first couple of weeks of the year.

Stay tuned. The best is yet to come!

Augmented Reality Toolkit for the iPhone on GitHub

A couple of weeks ago I got very interested in doing an Augmented Reality Application for the iPhone and one of business partners had a great idea for a game.  Instead of starting from scratch I decided to see if there was any existing open source projects I could use as base.

I started searching on GitHub and found a very good start of a toolkit.  I downloaded the original code and really liked where it was going.  However there were several things I felt I could do to make the code a bit less complicated and say many ways to improve it!

I've forked the original project and have begun to make the many changes I think could make it into a better toolkit.  I want to thank the original developers for getting me started and doing some of the heavy lifting.

I plan on blogging about the changes I've made and what I plan on adding to the toolkit. 

This should allow me to create the application I'm interested in making but also provide everyone who is interested a great toolkit to make their own projects as well.

It currently has a long way to go but now that I have the code in a manner that I want, I can really start adding the code to make this great!

You can check out the project on GitHub.com