Reflections on Configuration Management

murakamicatHave you ever sat down at 3am thinking, “I’m just gonna fix this one bug then I’m going to go to sleep.”

You fix the bug.

You’re riding the high, having fixed a persistent bug that’s been bothering you for a week. Then you decide, why not, I’ll just code a little more. Nothing’s planned out but you decide to dive in anyway. You’re on a roll.

Until…

Three hours later your program won’t compile and you have no idea why.

You don’t have any configuration management set up. And you have no idea how to reverse your changes.

At best you can pull up an old zip file of the code from 1 month ago.

You’ve effectively ruined your code.

Now you’re tired. Now you’re angry. And worst of all you have to start over.

Enter Configuration Management

Configuration management is an elegant life-saving productivity monster.

Thoughts on Git

My biggest beef with git is that the terminology they use to describe the functions the program does seem like they could be better written. “Checkout” means “switch current branch.” It’s almost as big of a misnomer as the * character used in C to denote a dereferenced pointer.

Mental Mapping of Git verbs

  • commit – save all changes and add a label
  • branch – make a copy that doesn’t affect the original
  • checkout – switch to branch/commit
  • cherry-pick – choose the good copies and add it to the project (best git command ever)
  • checkout – switch to this version of the project
  • reset – act like this version never existed
  • revert -act like this version never existed and add in everyone else’s changes
  • rebase – cleanly merge the copy with the original file (Honestly, I still don’t really understand the big difference between rebase and merge other than the commit history looks cleaner. Comparing rebase to a clever helped but the exact differences between the rebase and merge is still unclear).
  • merge -copy the original file with the changes in the copy.

Areas of Improvement

This interactive git tutorial highlights my weaknesses in the following areas of git:

  • reset
  • revert
  • rebase
  • rebase -i

Comparing Configuration Management solutions

Compared to RCS, CVS, Subversion, and Mercurial, Git has a decentralized approach to configuration management. Users can copy the entire codebase to their computer. Once their changes are made, they can either keep working on their own copy of the project or they can submit their changes back to the original copy of the project.

Git facilitates the three prime directives of open source software:

  • The README.md file explains the usefulness of the project.
  • The entire codebase is included as a downloadable compressed file (so it can be used installed and used by the user).
  • The entire codebase is made available to the user so they can see how everything inter-operates and update the code themselves.

Thoughts on Github

I created a sample repo on my new GitHub profile page: HelloRepo I am impressed that GitHub has the ability to programmatically create a compelling webpage to showcase the development of open source projects for developers. Here’s a link to the page that was automatically generated by GitHub for my repo: http://davidkneely.github.io/HelloRepo

GitHub has an interactive git tutorial that shows users how to use git from the command line with a simulated command line in the browser. It reminded me of the programming interface on Codecademy. I have one comment to add on the fantastic tutorial. On the interactive git tutorial, specifically on the rebase tutorial, keep in mind that the pick buttons that are highlighted pink mean they are “already selected.” I got stuck for a good 15 minutes because of this misapprehension of the interactive interface.

GitHub app for Mac

I download the GitHub app. The GitHub app is the easiest way to interact with Github. I used the first version back in 2011 and it was awful. I am glad to see that it’s gotten much better and doesn’t crash. New users who want to quickly interact with their repositories on GitHub should use the GitHub app if they are visual learners.

This slideshow requires JavaScript.

Lingering Questions

How do you undo your last git command? I found an answer on StackOverflow on how to undo the last commit but I want to know now if it is possible to undo any git command, not just a commit. If you know how to do this, please email me.

Ok, I think I got it, reset and revert allow you to go back in commits but the commits stay there in the git hierarchy. I am interested in a way to remove previous commits from the git hierarchy. I will keep researching.

Open Source Software Licenses

indexI have to confess something. It might be controversial. Here goes. I don’t want to open source my projects. Before you start thinking I’m a Luddite let me explain where I’m coming from.

I’ve been writing, producing, and selling my music for the past 15 years. I haven’t made a ton of money (to be honest, I’ve barely made any) but I like having complete control over my creative output. 

When I think of open source I think of throwing the code up on the web and losing all control of it. I don’t want to “open the kimono.” I want to hide the magic. I want to keep my software unseen. There are two distinct audiences experiencing my output: users and developers. I want to delight the former and, if there’s time, include the latter.

I am on the cusp pf releasing a new application that I have been coding non-stop for the past 3 months. I’ve had the idea for a year and only just made some serious progress on the program. If I were to release the code that I’ve been working on, I am concerned that someone who has not worked on this code as long and hard as I have will compile it and get it to the marketplace before I do.

I still have a week of debugging before I can submit it to the app store for approval. What if I introduce other contributors to my code and they change it into an application that I do not like? What kind of control do I have over my code once it’s been released on the internet?

If I’m being honest, the only real motivation in posting my code to github is to show that I can indeed code. Don’t misunderstand me, I see the benefits of getting more eyes on my code to extend the features and squash the bugs at a faster pace than I can manage by myself. I suppose I’m hesitant to be judged by other programmers.

The open source initiative lists the following popular licenses:

Why open source your software?

  • More developers review your code
  • Bugs are identified faster
  • Bugs are fixed quicker
  • Opportunities for new features are discovered
  • Feedback from the developer community guides development
  • New features can be added faster
  • You don’t need to hire developers
  • You don’t need to hire beta-testers
  • You don’t need to hire debuggers

Misconceptions of Open Sourcing Software

When I first started thinking about open sourcing my software I was worried about it being trashed. During my review of the libgdx framework I learned that they use the Apache 2.0 license. The license allows them to share their code but it prevents contributors from deviating their code from its intended purpose.

Now that I understand that certain privileges of the original creator can be guarded I am a little more willing to consider releasing my source code to the public. I also understand that no one person can truly accomplish something great.

If you want to accomplish something in the world, idealism is not enough – you need to choose a method that works to achieve the goal.

– Richard Stallman

Why use an Open Source Software License?

  • Protect your intellectual property
  • Solicit programming feedback from the programming community
  • Explicitly state the rules in extending your code

Licensing my projects

I am considering a restrictive license on code that I do not want someone to make a clone of my service. I want to retain some to all of the rights for this piece of code and the services that I will monetize with it. I would use the Apache 2.0 open source software license.

Licenses I’d like to fork

On the other side of the table I have a very different view. If I find a project on github that I am very interested in, I hope to see that it has an MIT License. You can do anything with it. It is the least restrictive.

I would appreciate any feedback that someone wants to give me regarding how to control my code and make sure that someone else doesn’t take from me. I know that once I publish my code to the wider world, all of it will be exposed and I can never take it back.

I want a license that protects my work from being exploited by being repacked, re-branded, or re-purposed.

Well-formed questions are more likely to get answers

Eric_S_Raymond_portraitWhen I was prototyping my game Mathogen. I had so many questions and no one to answer them. Objective C was relatively new and there weren’t many resources online.

I posted my questions to the Cocos2d discussion forum and got a different set of responses. I noticed that based on the narrowness of my questions, I would get different responses. If I didn’t take time to narrow down my questions, fully search for the answer online, and phrase it in an understandable way.

After seeing that I didn’t get answers, or got some really nasty feedback, I was ready to work on forming my questions in a better way.

Eric Raymond, author of The Cathedral and the Bazaar, offers the following tips on How to ask questions the smart way:

  • Choose your forum carefully
  • Stack Overflow
  • Web and IRC forums
  • As a second step, use project mailing lists
  • Use meaningful, specific subject headers
  • Make it easy to reply
  • Write in clear, grammatical, correctly-spelled language
  • Send questions in accessible, standard formats
  • Be precise and informative about your problem
  • Volume is not precision
  • Don’t rush to claim that you have found a bug
  • Grovelling is not a substitute for doing your homework
  • Describe the problem’s symptoms, not your guesses
  • Describe your problem’s symptoms in chronological order
  • Describe the goal, not the step
  • Don’t ask people to reply by private e-mail
  • Be explicit about your question
  • When asking about code
  • Don’t post homework questions
  • Prune pointless queries
  • Don’t flag your question as “Urgent”, even if it is for you
  • Courtesy never hurts, and sometimes helps
  • Follow up with a brief note on the solution

Questions on StackOverflow

In this post I am planning to highlight the effectiveness of Raymond’s suggestions by selecting two questions posted to StackOverflow. I will be featuring the outcomes that occur based on the quality of the way the question was asked. Hopefully I will find that the following is true:

  1. Positive outcomes occur when users follow the guidelines.
  2. Negative outcomes occur when users don’t follow the guidelines.

I am going to show how the chosen questions fulfill (or not) the precepts for smart questions, I will also include how the responses reflect the smartness (or lack thereof), and the insights I gained as a result of this experience.

The “smart way” to ask questions

Here is an example of a good question: Retrieve referral application from URL scheme launch via NSAppleEventDescriptor

The OP follows these precepts established by Raymond:

  • Choose your forum carefully
  • Use meaningful, specific subject headers
  • Make it easy to reply
  • Write in clear, grammatical, correctly-spelled language
  • Send questions in accessible, standard formats
  • Be precise and informative about your problem
  • Describe the problem’s symptoms
  • Describe your problem’s symptoms in chronological order
  • Describe the goal, not the step
  • Don’t ask people to reply by private e-mail
  • Be explicit about your question
  • Prune pointless queries
  • Don’t flag your question as “Urgent”, even if it is for you.
  • Courtesy never hurts, and sometimes helps
  • Follow up with a brief note on the solution

The author of this question poses the question so well that he ends up answering his own question. I believe that he framed his question so well (perhaps reframed is a better word) that he was able to see the question more clearly than he had before. He doesn’t explicitly state how he got to the answer but I believe he used a technique used by Richard Feynman to reframe a problem.

Shane Parish at the Farnam Street blog explains:

The Feynman Technique

Step 1. Choose the concept you want to understand.
Take a blank piece of paper and write that concept at the top of the page.

Step 2. Pretend you’re teaching the idea to someone else.
Write out an explanation of the topic, as if you were trying to teach it to a new student. When you explain the idea this way you get a better idea of what you understand and where you might have some gaps.

Step 3. If you get stuck, go back to the book.
Whenever you get stuck, go back to the source material and re-learn that part of the material until you get it enough that you can explain it on paper.

Step 4. Simplify your language.
The goal is to use your words, not the words of the source material. If your explanation is wordy or confusing, that’s an indication that you might not understand the idea as well as you thought – try to simplify the language or create an analogy to better understand it.

The “not smart way” to ask questions

Is it possible to execute Objective-C programs in Windows? is an example of a question that does not follow Raymond’s guide to asking questions.

  • Question violates the principles established by Raymond.
  • Answers provided by the community should demonstrate that asking a question in a “not smart” way does not lead to both effective and efficient help.

The OP does not follow these precepts established by Raymond:

  • Be precise and informative about your problem
  • Describe the problem’s symptoms
  • Describe your problem’s symptoms in chronological order
  • Describe the goal, not the step
  • Be explicit about your question
  • Prune pointless queries

As a result the OP gets the following responses:

Out of all the 6 answers he gets on StackOverflow the one that illustrates that he did not search for a possible answer before posting is here:

Yes you can compile Objective-C on Windows. But for iPhone development this question was already asked.

And there are several similar questions about iPhone development here on Stackoverflow, just search for it.

Because the OP did not do the proper research to find out if his question had been answered before he added unneeded stress to the people that were reviewing his question.

Insights gained as a result of this experience

I learned that a well-phrased question leads to answers. Even if they come from the OP.

Open Source Software Review: libgdx

 libgdx logo white bgIn the first of what I hope will be a series of posts on Open Source Software development, I am reviewing libgdx. The goal of this post is to review libgdx to see if it satisfies the three prime directives of open source software.

If it does satisfy the three prime directives of open source software there is a greater chance that the project will be shared, continue to be supported, and a vibrant community will remain active in maintaining it.

Libgdx is “a game-development application framework written in the Java programming language with some C and C++ components for performance dependent code. It allows for the development of desktop and mobile games by using the same code base. It is cross-platform, supporting Windows, Linux, Mac OS X, Android, iOS, and web browsers with WebGL support.

libGDX allows the developer to write, test, and debug their application on their own desktop PC and use the same code on Android. It abstracts away the differences between a common Windows/Linux application and an Android application. The usual development cycle consists of staying on the desktop PC as much as possible while periodically verifying that the project still works on Android. Its main goal is to provide total compatibility between desktop and mobile devices, the main difference being speed and processing power.

libGDX uses some third-party libraries to provide its functionality, these include Lightweight Java Game Library, OpenGL, FreeType, mpg123, Vorbis, SoundTouch Audio Processing Library, Box2D, OpenAL, and Kiss FFT.

– Wikipedia

Let me explain something

I’ve been making video games for the iPhone for 6 years. When I started I did not want to learn OpenGL to create animations in my games. It took too much programming to do a simple animation. I needed help. I wanted to create a game quickly. I needed a game framework or an engine.

Frameworks are code libraries that add functionality to existing code. Engines impose too many restrictions to make them useful for “riffing” on new games. I needed a framework. I needed something fast. Enter Cocos2d.

Cocos2d has fantastic documentation and a thriving online community that answered my questions quickly. Cocos2d was so good Zynga, makers of the fantastically popular game Farmville, bought the company and the framework. Thankfully they kept the code opensource.

The only problem with Cocos2d is that it only builds to the iOS platform. There is no support for porting your game to Android, Desktop, Linux, or HTML. When I ported Mathogen to run in the browser, I had to convert each function in Objective-C to a corresponding function in ActionScript 3.0. This took too much time. This was the opposite of “riffing.”

Enter libgdx.

Making it easy to understand libgdx

Thankfully the steps described in the README.md on the libgdx github project page tells developers exactly what they need to do to get started using libgdx.

  1. Set up the IDE to run libgdx.
  2. Create a new project.
  3. Link to the wiki that explains how the application framework works, how to contribute, and the contributor licensing agreement.

Reviewing libgdx

I will be reviewing libgdx according to the three principles of open source software by attempting to install, run, and contribute to the framework.

Three prime directives of open source software:

1. The system successfully accomplishes a useful task.

Libgdx allows the developer to write their code in Java. Libgdx takes advantage of the Java Virtual Machine and its ability to run on multiple platforms. When I write a game in Java with libgdx I will never have to rewrite it for different platforms.

Libgdx allows developers to write once and deliver everywhere. I am excited to have found this new framework. It may take a little time to learn the new animation methods but the cross-platform compatibility of the resulting code will make learning the new framework all worth it.

2. An external user can successfully install and use the system.

I downloaded the zip file from the libgdx github page. I will be using Eclipse to create games with libdx. I followed the guide for Setting up your Development Environment (Eclipse, IntelliJ, and NetBeans) that was linked for the project’s main github page.

According to the guide, the first thing I needed to do was ensure that I had Java 7. I was able to update this on my mac by navigating to ‘System Preferences’ -> “Java.” The installer took care of updating Java on my computer. First step down, five more to go.

I already had Eclipse 4.4 Luna installed on my mac so I could skip the step about installing Eclipse on my mac.

Next, the guide says to install the Android Development Tools for Eclipse. I believe the wording on this page could be much clearer. As a developer who is relatively new to using the Eclipse IDE, the wording on this step, “Use this update site:” could and should be updated to make the step more understandable.

I would suggest they update the instructions to something more understandable like RoboVM has on their page for installing the RoboVM Eclipse plugin. This step would be clearer if they updated the instructions to read:

Install the Android SDK for Eclipse plugin from the following update site under Help → Install New Software in Eclipse:

https://dl-ssl.google.com/android/eclipse/

I wasted 2 hours fiddling with the Android SDK installer only to find out that I could install the Android SDK from within Eclipse:

Screen Shot 2015-01-23 at 8.05.28 PM

Next I installed “Eclipse Integration Gradle” and the RoboVM plugin with the supplied links with no problems.

Before I move on to creating a new project, I wanted to comment on how this guide can be updated to prevent other developers from getting confused.

Now that all the tools can be installed within Eclipse 4.4 Luna, I believe the maintainers of the Setting up your Development Environment (Eclipse, IntelliJ, and NetBeans) page should update the section on “Setting up Eclipse” to make the instructions clearer. Users need to know that they don’t need to navigate outside of Eclipse to get the code they need to make libgdx compile and work.

Finally I was ready to create a project. Exporting the libgdx project to all supported platforms took about 5 minutes. I followed the instructions, opened the existing project in Eclipse and ran it as a Java Application.

Screen Shot 2015-01-23 at 8.49.03 PM

3. An external developer can successfully understand and enhance the system.

The included wiki explains how the application framework works, how to contribute, and the contributor licensing agreement.

Screenshots showing my progress

This slideshow requires JavaScript.

Final Review:

libgdx fulfills all three of the prime directives of open source software. My suggestion to the maintainers of the guide for setting up libgdx in eclipse would be to update the installation guide to show that all the tools necessary for creating games with libgdx can be installed from within Eclipse.

Other than that, I am very happy to have found this game development framework. I can’t wait to start coding once and deploying to multiple platforms.

Resources:

Hello World

shutterstock_220650781Interests in software engineering

I am interested in the impact of technology on the psychology of its users. I have a reminder on my phone that goes off at 8:30pm nightly to “Turn off all screens.” That way I get rid of the blue light that keeps everyone in the modern world awake. Their minds buzz buzz buzzing to the tune of youtube loading screens and mac spinning pin-wheels.

I am also interested in Jane McGonigal’s Gamificaiton of the world. I want to build games that contribute to the edification of the modern user. I want to leave users with something interesting in their lives. I want to enrich them with short bursts of challenges. I believe in games and their power to persuade users to live better lives. I want to advance the progress of calm technology.

Skills I hope to develop

As I get better at Software Engineering, I hope to be able to create MVP’s more quickly. So I can test my ideas out with beta-testers and get their feedback more quickly. I want to implement analytics in a fast way to get the feedback that will allow me to find out if this idea is a winner or a dud. Then if it’s good, I want to polish it and add features and make it better.

If it’s a dud, I want to move on quickly and start something new. I have a ton of new ideas in my head. I want to get them out to the public faster so I can build up a strong presence online and be seen and looked to as a mentor for future programmers.

Experiences I hope to have

I hope to develop new experiences to learn how to deal with people in the modern world. I read a lot and I hope to get more book recommendations as I move along and figure out new things. I’ve been wanting to take ICS 613 for a long time.

There are gaps in my knowledge. I feel that I am weak in Information Security. I want to squash them and have nothing to hold me back from contributing to a thoughtful discussion of software development, the impacts of technology, and the potholes we need to avoid in creating the future. I want to meet more people who are interested in software and find out how I can help them get their dreams shining on the machine.