Tag Archive: GitHub

GitHub Fails and Lessons Learned

I messed up my Xcode plugin yesterday. GitHub failed me, or rather, I failed GitHub. Then I fixed it and implemented better practices.

This blog post is an open, transparent attempt to share my mistakes and solutions.

For non-GitHub users, GitHub is sort of like Google Docs for software. It allows multiple software developers around the world to work together on software (relatively) seamlessly. So, if a software developer in Dubai makes a change, and another software developer in France makes a different change, those two changes can be merged into a single version of the software without significant hassle.

One Branch to Rule Them All

My first mistake was that I had only one GitHub branch: master. Initially, this worked well for me, because I used one laptop for development and pushed changes frequently from my local machine’s master branch to GitHub’s remote master branch.

Yesterday, I decided to push changes from a second machine, a test iMac with OS X Yosemite and Xcode 6 GM installed (for stability of the plugin, my laptop is still running Mavericks and Xcode 5/Xcode 6 beta. This turned out to be a good idea, at least until quirks are worked out).

Using the test iMac, I added the UUID (unique identification code) for Xcode 6 GM to my plugin. I did some limited testing (MAJOR MISTAKE) to verify functionality, pushed the code to GitHub’s master branch from the iMac, published a few more minor commits, and then pulled the new master version onto my laptop to make sure it also worked there.

Spoiler Alert!

The plugin did not work on my laptop. Previously functional commands produced no output. One command to create a for loop actually executed the Undo function instead! (If you’re not a software developer, just know that this is a bad kind of bug.) Most of these commands had worked fine on the test iMac.

Baffled, I decided to test every single command on the iMac (maybe I should have done this the first time, hmm?). I quickly discovered that with only one exception (of course, the one I’d tested before) my conditional-statement methods crashed Xcode. Some of the other methods that had produced no output on the laptop worked perfectly on the iMac. And entering slightly non-matching commands, which should produce no action, also crashed Xcode.

Clearly, my program now had crossed wires — and this crossed-wires version was the master branch on GitHub and the working version on my iMac and my laptop.

It was time to revert.

Don’t Cross the Streams

I researched how to revert GitHub commits. I wanted to roll back to a canonical, stable version that had worked with Xcode 5, and then go forward from there in a more measured way.

It turned out there were many ways to do this, many of which seemed complicated. The simplest way, doing a hard reset, was utterly bad practice (see: rewriting history) and I didn’t want to go there.

I found a Stack OverFlow answer that solved my dilemma. A poster there recommended doing this:

git revert –no-commit #######..HEAD (where ####### is the ID of the commit)
git commit -m “Commit message explaining what I just did”

This approach would revert all of the commits at once and re-create the state that had existed after the target commit. But it would not rewrite history by entirely removing old commits. Perfect.

Executing the Plan

First, in case something went wrong, I created a new branch with the old commit that I considered to be stable:

git checkout -b xcodestable #######
git push origin xcodestable

Then, reassured that I had a stable version stored on a separate branch, I switched back to the master branch and rolled it back to the old commit using the “git revert –no-commit” solution from Stack OverFlow:

git checkout master
git revert –no-commit #######..HEAD
git commit -m “Commit message explaining what I just did”
git push -u origin master

This seemed to work beautifully. But when I tried to run the plugin on my laptop, I encountered the same problems as before.

Into the Logs

Stymied in all other ways, I dealt with the situation I had in front of me and started logging messages to the console. I stepped through each process to see where things were going wrong.

To my surprise, the main problem appeared to be that many commands, after detecting the correct start point, were jumping into a method that adds items to an array. That method started with the word “Put “.

I had added case insensitivity to the plugin recently. That meant any text containing “put ” also would trigger the add-items-to-array method. For example, if the word “input” appeared anywhere in the code or comments, that would be a trigger. Whoops. I wasn’t sure why the case-insensitivity feature had worked perfectly when I first implemented and tested it, but it was breaking now.

I cleaned that up by making the command start point more specific (“Put item “) and built the program again. This time everything functioned. I tested every piece of functionality and then pushed it to the master branch:

git add –all
git commit -m “Functioning version”
git push -u origin master

Since everything was working, and the prior “stable” snapshot actually had not functioned correctly, I created a new stable branch from the functioning master branch:

git checkout -b xcode5stable2
git push origin xcode5stable2

Then I deleted the old, non-stable-after-all snapshot branch:

git push origin –delete xcode5stable
git branch -d xcode5stable

On to New Frontiers

At this point, the master branch functioned on my laptop and I had taken a snapshot (branch) of this stable state.

I still wanted to update the plugin for Yosemite and Xcode 6 GM functionality.

Unlike the last time, I decided not to do that on master. I created a new branch for testing new functionality, with the goal of merging it into the master branch once it verifiably worked on Mavericks and Yosemite:

git checkout -b newyosemite

Using the laptop, I opened the plist file as source code and added the Xcode 6 GM UUID. Then I built, re-tested every piece of functionality on the Mavericks laptop, and then pushed to the newyosemite branch.

git add –all
git commit -m “Now compatible with…”
git push -u origin newyosemite

Next Steps

The next step is to test this seemingly functional version on the test iMac with Yosemite. I’ll do that this weekend. I’m not sure if it will work, but I believe I found and fixed the major bug behind the wacky, unpredictable functionality. I also think I figured out what is causing another bug and have several ideas on how to make the code more robust.

My major takeaway is that no matter how small a project, better Git/GitHub practices are worthwhile. Specifically:

  • Preserve stable versions before major changes in a separate branch;
  • Make new changes in a separate branch before merging those changes into master; and, possibly most importantly:
  • Test ALL pieces of functionality before pushing or merging anything to branch master. Don’t just do spot tests.