Thursday, September 1, 2011

Version Control in Magic Spell Development

Version control refers to the process of managing changes to a piece of work, such as a computer program. One of the primary benefits of a version control system is that is maintains previous versions of the work. This is important for both: backing up the work against unexpected loss and allowing the developer to access previous versions of the work. For example, a developer might want to revert some part of the work back to a previous state (e.g., reverting a function to before a bug was introduced).

The wizard Marcus kept his apprentices very busy. In his opinion, work was the best way for them to learn. Plus, it was quite convenient to have someone help with the less glamorous work. It was not as though Marcus actually wanted to do any of that work himself; he had more important things to do, such as developing new spells.

Developing new spells was Marcus's favorite task. There was a deep challenge to creating a new spell. First, you had to determine what you wanted the spell to do. Second, you had to determine the overall flow of the spell. Third, you had to isolate and develop the subcomponents of the spell. How would you initiate the transmogrification? How would you know when to stop? He likened the process to writing a symphony or to creating a complex computer program. It could take him months to create the perfect spell.

And that is why Marcus was a firm believer in the importance of version control.

At the end of every day, he would have his apprentice copy down all of his notes onto a fresh roll of parchment. This meant all notes -- a perfect copy of the current state of Marcus's notebook. The apprentice would label the parchment with that day's date and file it in a special drawer. Thus, if Marcus ever needed access to an old version of his work, he could simply retrieve the correct parchment.

One day, his apprentice Shelly started to complain bitterly. "Why do I have to keep copying down your notes? You have everything in your notebook already. And you are just going to change things again tomorrow. Like this paragraph on mixing the potion. Yesterday, I copied down almost exactly the same thing. Except today you crossed out 'Stir 3 times clockwise' and replaced it with 'Stir 4 times counter-clockwise'. Why did I bother copying it down yesterday? Why not just wait until you are finished?"

"Two reasons." Marcus began calmly. He enjoyed explaining the logic behind good spell development almost as much as he enjoyed spell development itself. "First, for safety. Do you remember that time last month, when I accidentally set the room on fire? It was while I was working on the spell to cure dry skin. My lab notebook completely burned up."

"But, sir." protested Shelly. "That was an exceptional case. How often do you accidentally set your notebook on fire? Is it really worth that much effort? Couldn't you just make a copy of the final product? That way you would never loose a spell that is finished. You could only loose parts of unfinished work."

Even as she spoke, Shelly considered her own question. In the one year that she had been Marcus's apprentice, he had managed to accidentally set five different notebooks on fire. Maybe he did have a point about backing up his work. Or perhaps a better solution would be for him to avoid working on spells involving fire. She quickly decided not to raise either of these points.

"I would have still lost days of valuable work!" exclaimed Marcus. "A complex spell might take months to develop. It is simply not worth the risk."

"Then why not just use a magic mirroring spell on your notebook. Surely, you do not need a whole new copy each night. You could just have a single, identical copy in some safe location -- like New Pompeii." argued Shelly.

Marcus smiled. "I do that too. I mirror all my notebooks to a castle out in the country. But there is another reason to copy my notes: developing the a spell is not always a straight line process. Sometimes, I make mistakes and need to go back to what I was doing before."

Shelly looked confused.

"Remember when you copied down the spell for silencing marching bands?" Marcus asked.

Shelly nodded. Of all the spells that she had seen Marcus develop, that was one of her favorites. She had tried it at half-time during her brother's high-school bocce game. In the middle of a song, all of the instruments had gone completely silent. All of the band members were completely confused. Of course, Shelly still felt a little guilty that she had not bothered to learn the reverse spell.

"During the middle of developing that spell, I changed a block at the end." continued Marcus. "I removed all of the instructions for using the wand and started over. I threw out two weeks worth of work."

Shelly remembered clearly. She had muttered a lot of nasty things under her breadth when she had seen the paragraphs crossed out.

"But then what happened?" asked Marcus.

Shelly thought back. "You put them back in a few days later."

"Yes!" agreed Marcus. "It turns out that I had not factored the wind into the spell yet. So I was just able to modify the wording. The original wand instructions were fine."

"I don't understand." sighed Shelly.

"Version control allows you to go back and recover previous versions. If I change my mind and alter an instruction, then I cross it out in my notebook. It is gone from my notebook and the mirrored copies. But I might need to be able to go back and look at the old version. There might be something there that I need later."

"Why not just keep everything in the current notebook?" asked Shelly. "You could add comments saying 'Don't do this' or 'Ignore this' so that you know which instructions are old. That way you would never need to throw anything out."

"That would be too messy. How would I ever read a spell?" argued Marcus. "Version control is cleaner. I can make whatever changes I want, and I know that I can always go back to a previous version if I need it."

"But…" started Shelly, but she had run out of arguments. She could clearly remember many instances when he made major changes to a spell, and then had backtracked the next day and reverted them. During the development of the Spell of Singing Rocks, he had gone back and forth three times on a single approach. Each time he changed his mind, she had been able to retrieve an old scroll so that he did not need to start from scratch.

"But… my hand hurts from copying the same instructions over and over." Shelly finally admitted.

Marcus tried to look sympathetic. "I know that it can be a tiresome task. That is why I have apprentices do it for me."

His statement did not make Shelly feel any better.


Check out other valuable lessons learned by apprentices, such as the Value of Good Comments or the Importance of Unit Testing.

Or read about Marcus's castle in the country in Pointers and Walk-In Closests.

No comments:

Post a Comment

Note: Only a member of this blog may post a comment.