The blog has moved to: http://jkamenik.github.com.
The full details of why are here: http://randomsoftwareinklings.blogspot.com/2012/11/the-long-away.html
Saturday, December 29, 2012
Monday, November 12, 2012
The long away
The Reason
First, let me apologize to my 3 readers that I have been away for so long. There are a lot of reasons why I have been gone, but mainly it boils down to how much I hate the blogger interface for dealing with code.Sure, blogger is a simple platform and does exactly what it says. Sure, it integrates with google plus, twitter, etc... Sure, it was easy to configure, setup and deploy. Sure, it has a lot of features.
But, it sucks for code! And I mean Sucks! For code there are a few very specific hot button items that are must haves:
- Monospaced font and significant whitespace (<pre> in HTML)
- Line numbers
- Syntax highlighting
Not that much to ask, but those features are ONLY ever going to be needed by a programmer. So I can see why they don't get that much attention.
Both the old and the new blogger interface have a way of dealing with this, but it is time consuming and annoying:
- Use gist.github.com as a dumping place for all your code samples
- Create a separate file in the gist for each sample (makes it easier later)
- Make sure the file name has the right extension so that syntax highlighting happens
- Copy the embed codes for each gist
- When editing the blog only use HTML mode!
- The gist code is a javascript so it will only render in preview
- Switching between HMTL and compose sometimes rearranges non-visible items, which means when your page renders your code could be anywhere
- If I am going to write raw HTML I might as well use Markdown, which sucks less and converts to HTML
- Hope that nobody views your blog with JS disabled!
The Solution
After playing with many blogging solution and giving up on Wordpress entirely (Sorry I just cannot get what I want without a LOT of php hacking), I have decided to give a Octopress a serious shot. I use github all the time and even host a few things using github pages.
In case you don't know, Github pages can render Jekyll sites. And Jekyll is a blog aware static site generator, which can read markdown. And Markdown is a much more human friendly markup language then HTML, but compiles into HTML; also, Github uses it everywhere in their site (as do a lot of other places).
So things started to fall into place with Jekyll. I just needed to install a syntax highlighting gem, and design the site. In the process, I stumbled across Octopress, which is a wrapper around a Jekyll site, works with github, has syntax highlighting, provides a clean theme, and has a programmer friendly workflow.
So Octopress is the blog engine for me. And it will reside at http://jkamenik.github.com. I will slowly be transferring all my entries from here, but I doubt I will retire this site entirely.
Friday, March 9, 2012
Factory Girl Automatic Tests
Introduction
Early in a project I started to use factory girl without fully understanding it. After many months of creating steps like "Given /^(\d+) blog exists$/" and "Given /^the following blogs exist:$/" I started to come up with generic functions that would build those steps.
Stupid me for not checking that factory girl already does something like that. All you have to do is include factory girl's step_definitions.rb file:
Once you start using FactoryGirl correctly there are a world of new features that can make your steps both cleaner and more concise. Here are some tips I have found via trial and error.
Tip 1: Do not reinvent the wheel
Factory girl will create steps for all factories that you have register.
Tip 2: Use association, Do not add more steps then are needed
Factory girl association are automatically created before the factory is created and they are automatically linked. It only supports the belongs_to behavior, so keep that in mind.
Using the "Given the following XXX exist" step you can define attributes, on the the association, in the table. If we leave the association out then a default is created. If we define an attribute then it will be found or created using that attribute.
Lets say you have a product and it can belog to a category. You do not need to create a category.
Tip 3: Attaching files via CarrierWave
Since cucumber is a text file it doesn't make much sense for you to define full files in steps. It also doesn't really make sense to embed full file paths in the tests. Instead, you can use a Transient attribute and some code so that in cucumber you define a file name and in the factory it converts to an actual file.
Tip 4: Fixing a circular dependency between two models
Lets say you have a Store model and User model. And a User can both work at and own a Store. If you put associations in both the User and the Store model then each will try to create the other, infinitely. We can reuse the transient method as before to break the circle.
The trick is to avoid defining an association in both factories, but instead use a transient attribute in one factory to simulate the behavior of an association. Also, since transient attributes are not likely to have the same level of sophistication as the associations you should use the association to define the more complex of the two models.
Tip 5: Fixing a circular dependency between the same model
Let say you have a Category model, and that model can belong to another Category (a tree) then you cannot use an association or you get the same infinite recursion issue as before. Here we can use a transient attribute along with an after_create hook to simulate the behavior we want.
Early in a project I started to use factory girl without fully understanding it. After many months of creating steps like "Given /^(\d+) blog exists$/" and "Given /^the following blogs exist:$/" I started to come up with generic functions that would build those steps.
Stupid me for not checking that factory girl already does something like that. All you have to do is include factory girl's step_definitions.rb file:
Once you start using FactoryGirl correctly there are a world of new features that can make your steps both cleaner and more concise. Here are some tips I have found via trial and error.
Tip 1: Do not reinvent the wheel
Factory girl will create steps for all factories that you have register.
Tip 2: Use association, Do not add more steps then are needed
Factory girl association are automatically created before the factory is created and they are automatically linked. It only supports the belongs_to behavior, so keep that in mind.
Using the "Given the following XXX exist" step you can define attributes, on the the association, in the table. If we leave the association out then a default is created. If we define an attribute then it will be found or created using that attribute.
Lets say you have a product and it can belog to a category. You do not need to create a category.
Tip 3: Attaching files via CarrierWave
Since cucumber is a text file it doesn't make much sense for you to define full files in steps. It also doesn't really make sense to embed full file paths in the tests. Instead, you can use a Transient attribute and some code so that in cucumber you define a file name and in the factory it converts to an actual file.
Tip 4: Fixing a circular dependency between two models
Lets say you have a Store model and User model. And a User can both work at and own a Store. If you put associations in both the User and the Store model then each will try to create the other, infinitely. We can reuse the transient method as before to break the circle.
The trick is to avoid defining an association in both factories, but instead use a transient attribute in one factory to simulate the behavior of an association. Also, since transient attributes are not likely to have the same level of sophistication as the associations you should use the association to define the more complex of the two models.
Tip 5: Fixing a circular dependency between the same model
Let say you have a Category model, and that model can belong to another Category (a tree) then you cannot use an association or you get the same infinite recursion issue as before. Here we can use a transient attribute along with an after_create hook to simulate the behavior we want.
Wednesday, November 30, 2011
CI server using Firefox
If you are like me, you always setup a CI to ensure things that you already finished are not broken by things you are currently doing. And if you are like me, you use capybara, selenium-webdriver, and firefox to actually test the results in a browser. The rub comes when the CI server (running headless) needs to run firefox, which needs a screen.
Virtual Frame Buffer (xvfb) is a great package. All it does is provide an X11 interface in memory instead of requiring a screen. Below I detail what I do on Ubuntu, but it should work the same on any Linux distro.
Installing Firefox
Testing Firefox
Once firefox is installed it can be tested on a X11-forwarded ssh connection. X11-forwarding has to be enabled on the server and client and can be tested by checking DISPLAY.
Installing Xvfb
Testing Firefox again
The easiest way to test is to use image magick to take a screen shot of the VFB and save it to an image that can be opened in Firefox. If the image opens and it looks like a firefox browser is running on the google page then you did it correctly.
Create a xvfb startup script
On ubuntu no start script is provided, but a simple one put in /etc/init.d/xvfb is enough.
Getting the CI server to use the VFB
At this point getting a CI server to use Xvfb will depend on how it is started. If you use the Xvfb startup script then the display is :1. All you have to do is export DISPLAY=:1 before the CI server starts.
Virtual Frame Buffer (xvfb) is a great package. All it does is provide an X11 interface in memory instead of requiring a screen. Below I detail what I do on Ubuntu, but it should work the same on any Linux distro.
Installing Firefox
Testing Firefox
Once firefox is installed it can be tested on a X11-forwarded ssh connection. X11-forwarding has to be enabled on the server and client and can be tested by checking DISPLAY.
Installing Xvfb
Testing Firefox again
The easiest way to test is to use image magick to take a screen shot of the VFB and save it to an image that can be opened in Firefox. If the image opens and it looks like a firefox browser is running on the google page then you did it correctly.
Create a xvfb startup script
On ubuntu no start script is provided, but a simple one put in /etc/init.d/xvfb is enough.
Getting the CI server to use the VFB
At this point getting a CI server to use Xvfb will depend on how it is started. If you use the Xvfb startup script then the display is :1. All you have to do is export DISPLAY=:1 before the CI server starts.
Monday, November 21, 2011
Ruby module instance and class methods
A very common idiom especially when code starts to become complicated is to put functions in modules and mix in that behavior to several classes. And a common expansion is to have a single "include" add both instance and class methods.
Here is how to do it:
"include" is used to add a module's instance methods as instance methods to the including class, but it doesn't traverse sub modules. "extend" is used to add a module's instance methods as class methods to a class.
When a module is "included" it can register a callback which is passed the class that is doing the including. And calling "extend" on the base and passing a submodule will cause it to put those methods at the class level. This causes a chain reaction of loading both instance and class methods using a single "include".
Pro Tip: It is possible to cause the same behavior using "extend" by using the "extended" callback; however, this is not common and "include 'x'" reads better then "extend 'y'".
When a module is "included" it can register a callback which is passed the class that is doing the including. And calling "extend" on the base and passing a submodule will cause it to put those methods at the class level. This causes a chain reaction of loading both instance and class methods using a single "include".
Pro Tip: It is possible to cause the same behavior using "extend" by using the "extended" callback; however, this is not common and "include 'x'" reads better then "extend 'y'".
Tuesday, August 16, 2011
The 3N Rule for deployment
As a programmer I am lazy, but in a productive way. It is not that I don't do anything. It is that I only do things a set number of times. I have a simple rule, which I call the "3N rule", which states "I will doing something once, script it the second time, and use the script from then on". Therefore, if I have 3 to N devices to manage then I have a script that takes minimal input and replicates the change on all devices.
I also have a 3N rule for programming, but that is a matter for another time.
By using a script I eliminate a lot of the human error and also increase my productivity because computers are, now days, faster at responding to stimuli then I am. But computers are "swift idiots" so for this to work the environment has got to be controlled. I recommend doing the following:
I also have a 3N rule for programming, but that is a matter for another time.
By using a script I eliminate a lot of the human error and also increase my productivity because computers are, now days, faster at responding to stimuli then I am. But computers are "swift idiots" so for this to work the environment has got to be controlled. I recommend doing the following:
- Use VMs
- Run headless, enable SSH
- Use ClusterSSH or csshX for learning what to script
- Use Capistrano or Fabric for automating change
By using a VM and running headless you remove the temptation to sit at a physical terminal. It also eliminates the fear associated with screwing something up as it is trivial to snapshot a machine and restore its state.
By using SSH and ClusterSSH you enable yourself to start thinking about the cluster as a whole, and more importantly start acting on the cluster as a whole. If some of the servers get out of sync then it makes management more difficult, so by using ClusterSSH you eliminate that problem.
By using Capistrano, or its like, then you eliminate the human error entirely. This is just good policy. Also, a benefit of a deployment script is that it is self documenting (assuming you know how to read).
Sunday, June 26, 2011
ExtJS 3 Views and Controllers
In a previous post I wrote about my impressions of Ext4. The overall impression were that the ideas were sound, but the implementation was still buggy. So instead of waiting (which is not possible in a business sense) I have back-ported the ideas to Ext3. I have not yet figured out how to get stores and models working well, but I have gotten views and controllers works very well.
Layout
Views basically work as is, because that is how ExtJS was designed. Any subclass of a UI widget will work as a view. However, to make the concept of a view work well they should only be instantiated once and have their modification logic in a controller. For this reason I recommend using the following directory layout:
app.js
This should just a Ext.onRead function that instantiates the Viewport.js class. It should also setup any globals that will be used throughout the app and should be included last.
lib/
Since views should only be instantiated once this is the place to put reusable code. Items here will not usually have an xtype because they will be extended by view items.
Controller.js
This is the base class for all controllers. It has the helper to bind to views and look them up afterwards. A small override to Ext.ComponentMgr is required to make everything work.
Content.js
This needs to be a simple card layout so that you can add new items to it.
ContentController.js
This class binds to a something that would change the content panel, like a TreePanel, and then using Ext.ComponentMgr creates a card, adds it to the content, and shows it.
Layout
Views basically work as is, because that is how ExtJS was designed. Any subclass of a UI widget will work as a view. However, to make the concept of a view work well they should only be instantiated once and have their modification logic in a controller. For this reason I recommend using the following directory layout:
- app.js
- ext/
- app/
- controllers/
- Controller.js
- ContentController.js
- lib/
- view/
- layout/
- Content.js
- Viewport.js
- OtherView.js
app.js
This should just a Ext.onRead function that instantiates the Viewport.js class. It should also setup any globals that will be used throughout the app and should be included last.
lib/
Since views should only be instantiated once this is the place to put reusable code. Items here will not usually have an xtype because they will be extended by view items.
Controller.js
This is the base class for all controllers. It has the helper to bind to views and look them up afterwards. A small override to Ext.ComponentMgr is required to make everything work.
Content.js
This needs to be a simple card layout so that you can add new items to it.
ContentController.js
This class binds to a something that would change the content panel, like a TreePanel, and then using Ext.ComponentMgr creates a card, adds it to the content, and shows it.
Saturday, June 18, 2011
Minimum Rcov
Uncle Bob, has stated that all code should be 100% covered, but 100% is an asymptote. Therefore he expects something less then 100%. This might be true in the Java, or C version of Rcov, but not for Ruby Rcov. Also, I personally think that 100% is a bit low.
All 100% coverage means is that at least one test touches every line. And in truly simple code that is usually enough. But I work on systems, not simple code. Rarely do I write single use code. In most cases I write code that does one thing well, but is used by a lot of different part of the system.
Errors are very rarely in core modules, but rather in the runtime combination of core modules. This is covered by integration testing which is not usually pulled into rcov. I think this is a mistake.
The following is how I think about a minimum level of Rcov:
All 100% coverage means is that at least one test touches every line. And in truly simple code that is usually enough. But I work on systems, not simple code. Rarely do I write single use code. In most cases I write code that does one thing well, but is used by a lot of different part of the system.
Errors are very rarely in core modules, but rather in the runtime combination of core modules. This is covered by integration testing which is not usually pulled into rcov. I think this is a mistake.
The following is how I think about a minimum level of Rcov:
- Exclude libraries from rcov metrics. That is unless you decide to include their unit testing within your own. Either way this will give you a more accurate reading of coverage. Seeing rcov at 90%, but thinking it is 100% because rcov can't see libraries isn't a valid assumption, IMHO.
- Include integration testing in rcov. Rcov has an option to aggregate several runs into a final number. You should include both unit and integration testing in the final number.
- Expect greater then 100% coverage. Actually, including edge cases, positive, and negative testing the number will be closer to 1000% percent covered. You read that right, every line of code should be covered by at least 10 tests.
- Include the rcov threshold test in CI. You should, before committing, always run all unit tests, integration tests, and rcov threshold. At first set the threshold low (about 80%) and move it to 100% ASAP. And by including threshold test in CI then the code can't go out the door without the correct amount of coverage.
- Review tests first and last. If your teams doesn't already do code reviews, it should. If it does then start with the tests and then review the code. This lets you ensure the obvious edge cases are covered without being swayed by the code. After reviewing the code re-review the tests to ensure there are no new edge cases need to be covered.
Monday, June 6, 2011
Ext4 Impressions
I have been using Ext for years, starting with 2.0. In most cases this is paired with Ruby on Rails on the server and has generally been nice. There were some growing pains in understanding that Ext is not like jQuery. It isn't meant to enhance the page it is meant to control it. Once it is understood that ExtJS is an event driven UI layer much like MFC (Microsoft) then things are rather easy to grasp.
In fact, Ext (pre 4) is almost just like MFC in that it is primarily a collection of UI widgets that you can put together in any way you wish. This is great for very small UIs that do not have a lot of interconnected parts, but once the number of interconnected item reaches more then a few (say 5 or 6) then it is nearly impossible to map all the emergent properties mentally. Enter MVC.
MVC is a design patter created over 30 years ago, whose sole purpose is the separation of concerns. Business logic (model) is separated from UI (view) and they communicate via a defined set of actions (controller). Anyone familiar with UI programming should be familiar with this pattern. It is used in almost all major UI libraries except ExtJS, until now.
Ext4 aims to fix this flaw by retooling the framework to be MVC. It is almost successful. There is a major problem in separating models from collections (which is understandable given Javascript's nature) but there are more elegant solutions then the one Ext4 uses (see SproutCore and Backbone). There are far too many annoyances at the model level for me to detail here, but as an example the LocalStore and MemoryStore are broken as of this writing and cannot update or remove models since they do not fire events. This problem can be seen is a number of their own grid demos.
I also tried to use the compatibility mode to convert an older Ext3 app to Ext4. I was successful in removing all of the errors and most of the warning, but could not get the page to render. Each component thought it was rendered, but no DOM was presented to the browser. Lots of digging later and it turns out you can't mix MVC Ext4 objects with non-MVC Ext3 like objects. Not sure why, and without errors it is hard to tell what went wrong.
Finally I started from scratch and created extjs4-frame so that I could dig in without having to worry about Ext3 compatibility screwing things up. Thing did not go much better. I watched the videos and then dove right in. As expected what was shown on the videos (obviously dumbed down) worked as expected, but as I started to add complexity things would break in mysterious ways. Turning to the documentation was only marginally helpful, since it appears that it has not been full updated. Also, some of the documentation does not match the JDoc comments in the source (probably human error in generating the docs). This is an annoyance to be sure, but not a show stopper since I know how to read Javascript (as anyone that would be using ExtJS should). However, documentation error (especially when generated from embedded comments) are indicative of a lack of attention to detail and since they do not provide their unit tests I can only guess that their storage engines are not well tested either.
Pros
In fact, Ext (pre 4) is almost just like MFC in that it is primarily a collection of UI widgets that you can put together in any way you wish. This is great for very small UIs that do not have a lot of interconnected parts, but once the number of interconnected item reaches more then a few (say 5 or 6) then it is nearly impossible to map all the emergent properties mentally. Enter MVC.
MVC is a design patter created over 30 years ago, whose sole purpose is the separation of concerns. Business logic (model) is separated from UI (view) and they communicate via a defined set of actions (controller). Anyone familiar with UI programming should be familiar with this pattern. It is used in almost all major UI libraries except ExtJS, until now.
Ext4 aims to fix this flaw by retooling the framework to be MVC. It is almost successful. There is a major problem in separating models from collections (which is understandable given Javascript's nature) but there are more elegant solutions then the one Ext4 uses (see SproutCore and Backbone). There are far too many annoyances at the model level for me to detail here, but as an example the LocalStore and MemoryStore are broken as of this writing and cannot update or remove models since they do not fire events. This problem can be seen is a number of their own grid demos.
I also tried to use the compatibility mode to convert an older Ext3 app to Ext4. I was successful in removing all of the errors and most of the warning, but could not get the page to render. Each component thought it was rendered, but no DOM was presented to the browser. Lots of digging later and it turns out you can't mix MVC Ext4 objects with non-MVC Ext3 like objects. Not sure why, and without errors it is hard to tell what went wrong.
Finally I started from scratch and created extjs4-frame so that I could dig in without having to worry about Ext3 compatibility screwing things up. Thing did not go much better. I watched the videos and then dove right in. As expected what was shown on the videos (obviously dumbed down) worked as expected, but as I started to add complexity things would break in mysterious ways. Turning to the documentation was only marginally helpful, since it appears that it has not been full updated. Also, some of the documentation does not match the JDoc comments in the source (probably human error in generating the docs). This is an annoyance to be sure, but not a show stopper since I know how to read Javascript (as anyone that would be using ExtJS should). However, documentation error (especially when generated from embedded comments) are indicative of a lack of attention to detail and since they do not provide their unit tests I can only guess that their storage engines are not well tested either.
Pros
- Documentation videos are a nice touch
- Simplified code due to the MVC nature
- Sensible file structure (forced)
- Auto-loader (turn off in production, but great for development)
- Better stack and error handling (as compared with Ext 2/3)
- Trees use real models (meaning the server can respond with any hierarchical objects)
- Non-flash based charts
- Smaller size (as compared to Ext 2/3)
- Difficult to understand (even for those with MVC and ExtJS experience)
- No backwards compatibility (the compatibility mode is a joke)
- 4.0.X versions are not guaranteed compatible (there are still a lot of internal changes going on)
- Documentation does not always match source comments and is not always correct (save some time and just start with the code)
- Inconsistant Model/Container behavior
- No generator scripts provided for aiding design patterns
- No unit testing framework provided
- No JS compiler/minifier provided (one that can read the requires directive is almost a must now that they exist)
Overall
Wait for 4.1 to see if things stabilize. Or switch to SproutCore.
Wednesday, May 11, 2011
Cucumber with using Rspec should_receive
I recently came across a case where I wanted to use a should_receive test in cucumber. The basic idea is that I was attempting to prevent Apache library code from calling out to the system, while simultaneously testing that the correct function was actually called. In Rspec (which backs cucumber in my setup) it is simply:
At the end of the test if restart has not been called then the entire test fails. Because of the way that cucumber works with rspec 1.3 (rails 2.x, which is required by the project) registering a should_receive has no effect (seems this is fixed in the cucumber/rspec versions for rails 3). Even if it were to work it would mean putting a Then before the When or putting a test in a Given. To me that just seems wrong.
What I had to do to simulate a should_receive but still maintain the flow of the scenario was break it up so that I stub the function and when that function is called I set a flag. Later I test that the flag is set.
The step that sets the flag is Apache can restart and the one that tests is Apache should restart. Here are the step definitions:
At the end of the test if restart has not been called then the entire test fails. Because of the way that cucumber works with rspec 1.3 (rails 2.x, which is required by the project) registering a should_receive has no effect (seems this is fixed in the cucumber/rspec versions for rails 3). Even if it were to work it would mean putting a Then before the When or putting a test in a Given. To me that just seems wrong.
What I had to do to simulate a should_receive but still maintain the flow of the scenario was break it up so that I stub the function and when that function is called I set a flag. Later I test that the flag is set.
The step that sets the flag is Apache can restart and the one that tests is Apache should restart. Here are the step definitions:
Wednesday, April 13, 2011
Heroku
At first it was not clear to me that Heroku was free for very small apps, but it is. There are also a few restrictions that Heroku has:
Setup a heroku ENV
Pushing to Heroku
- The project has to use Git
- The project has to be a Rails App (or have a config.ru)
- The project has to be in the repository root (good practice)
- The project has to list all the dependent gems (good practice)
If you meet all these requirements it is as simple as installing the heroku gem, creating a new app, and pushing the to heroku.
Setup a heroku ENV
$ mkdir heroku
$ cd heroku
$ rvm use 1.9.2@heroku --create
$ gem install heroku
Pushing to Heroku
$ git clone git@github.com:jkamenik/Laser-Landmarks-Prototype.git
$ cd Laser-Landmarks-Prototype
$ heroku add laser-landmarks
$ git push heroku master
Monday, February 28, 2011
Continuous Integration with CIJoe
CIJoe lacks a great many things that I usually expect in a CI server. But it is now unclear if they are really all that needed, or just added by CI marketing. Here is now I usually get CIJoe working with the least Effort.
The abridged version:
1. Install RVM
Docs on installing RVM are here. I use this to isolate my version of Ruby and Gems from other CIJoe servers that I will setup on the same machine. This reduces the headaches later
1.1. Install Ruby
With RVM installing new versions of ruby is easy with RVM. For example I use ruby 1.8.7-p330 on one of my projects so I run rvm install 1.8.7-p330.
1.2. Create a Gemset
For every CI Server I run I use a different gem set. Yes it uses more disk space but it saves so many headaches if two repos need different versions of different gems it is worth it. You can run it with the "rvm use" command. Lets say my project is called "FOO" I would run rvm use 1.8.7-p330@foo --create to switch to ruby 1.8.7-p330 using gemset foo and create the gemset if it doesn't already exist.
1.3. Install Bundler
Bundler is a manager for RubyGems that aids in getting the correct version of the correct gems installed. I install it so that before every make I run "bundle install" to make sure that the CI server has all the gems it needs for the test to pass. And if it fails because of a gem problem then it means the correct gems were not noted in the GemFile and therefore it will break in production.
2. Install CIJoe
CIJoe is a gem and it should be installed in the same gemset that the repo will be run out of. So if the code to test is Foo then run rvm use 1.8.7-p330@foo --create; gem install cijoe.
2.1. Clone your repo
git clone git://github.com/XXX/foo.git or something like that
2.2. Run CIJoe
I run it with nohup and & so it is in the background and always running. I also give it a known port so that I blow a hole in the firewall for it (see below for why).
nohup cijoe -p 4000 foo &
3. Configure your repo
This is both a strength and weakness of CIJoe: all the configuration for what to run and how is stored in the Git repo. The strength is that it is stored with the repo, the weakness is that .git/config and .git/hooks are not pushed to remote repos so if you need to start over you will need to recreate that config from scratch.
3.1. Add the runner command
CIJoe only allows running of a single command but it executes it in "sh" so you can use "&&" to chain them. However, to make things easier on myself I always create a rake task called "ci" and execute that. Also, to make sure that all the gems are correctly installed I run bundler first.
Note: When chaining commands via && make sure you redirect stderr to stdout since CIJoe only reads stdout, otherwise you will get nothing in the output file. The last command will already have stderr redirected so do not do it twice.
git config --add cijoe.runner "bundle install 2>&1 && rake ci"
3.2. Adding Notification
CIJoe just executes .git/hook/build-failed on a failure and .git/hook/build-worked on a success. The examples show how to setup these up.
4. Auto build
Any HTTP PUSH to CIJoe will cause a build to be kicked off. This is useful for auto-kicking a build when a new commit is pushed.
4.1. Blow a hole in the Firewall
This is so that github can get into your build server, since I assume you have your build server behind a firewall. Your config will depend on Firewall/Router.
4.2. Configure Github
Just add a Post-Receive hook via the github admin screen.
The abridged version:
# rvm
$ bash < <( curl http://rvm.beginrescueend.com/releases/rvm-install-head )
$ rvm install 1.8.7-p330
$ rvm use 1.8.7-p330@foo --create
$ gem install bundler
$ gem install cijoe
$ git clone git://github.com/XXX/foo.git
$ nohup cijoe -p 4000 foo &
$ git config --add cijoe.runner "bundle install 2>&1 && rake ci"
$ bash < <( curl http://rvm.beginrescueend.com/releases/rvm-install-head )
$ rvm install 1.8.7-p330
$ rvm use 1.8.7-p330@foo --create
$ gem install bundler
$ gem install cijoe
$ git clone git://github.com/XXX/foo.git
$ nohup cijoe -p 4000 foo &
$ git config --add cijoe.runner "bundle install 2>&1 && rake ci"
1. Install RVM
Docs on installing RVM are here. I use this to isolate my version of Ruby and Gems from other CIJoe servers that I will setup on the same machine. This reduces the headaches later
1.1. Install Ruby
With RVM installing new versions of ruby is easy with RVM. For example I use ruby 1.8.7-p330 on one of my projects so I run rvm install 1.8.7-p330.
1.2. Create a Gemset
For every CI Server I run I use a different gem set. Yes it uses more disk space but it saves so many headaches if two repos need different versions of different gems it is worth it. You can run it with the "rvm use" command. Lets say my project is called "FOO" I would run rvm use 1.8.7-p330@foo --create to switch to ruby 1.8.7-p330 using gemset foo and create the gemset if it doesn't already exist.
1.3. Install Bundler
Bundler is a manager for RubyGems that aids in getting the correct version of the correct gems installed. I install it so that before every make I run "bundle install" to make sure that the CI server has all the gems it needs for the test to pass. And if it fails because of a gem problem then it means the correct gems were not noted in the GemFile and therefore it will break in production.
2. Install CIJoe
CIJoe is a gem and it should be installed in the same gemset that the repo will be run out of. So if the code to test is Foo then run rvm use 1.8.7-p330@foo --create; gem install cijoe.
2.1. Clone your repo
git clone git://github.com/XXX/foo.git or something like that
2.2. Run CIJoe
I run it with nohup and & so it is in the background and always running. I also give it a known port so that I blow a hole in the firewall for it (see below for why).
nohup cijoe -p 4000 foo &
3. Configure your repo
This is both a strength and weakness of CIJoe: all the configuration for what to run and how is stored in the Git repo. The strength is that it is stored with the repo, the weakness is that .git/config and .git/hooks are not pushed to remote repos so if you need to start over you will need to recreate that config from scratch.
3.1. Add the runner command
CIJoe only allows running of a single command but it executes it in "sh" so you can use "&&" to chain them. However, to make things easier on myself I always create a rake task called "ci" and execute that. Also, to make sure that all the gems are correctly installed I run bundler first.
Note: When chaining commands via && make sure you redirect stderr to stdout since CIJoe only reads stdout, otherwise you will get nothing in the output file. The last command will already have stderr redirected so do not do it twice.
git config --add cijoe.runner "bundle install 2>&1 && rake ci"
3.2. Adding Notification
CIJoe just executes .git/hook/build-failed on a failure and .git/hook/build-worked on a success. The examples show how to setup these up.
4. Auto build
Any HTTP PUSH to CIJoe will cause a build to be kicked off. This is useful for auto-kicking a build when a new commit is pushed.
4.1. Blow a hole in the Firewall
This is so that github can get into your build server, since I assume you have your build server behind a firewall. Your config will depend on Firewall/Router.
4.2. Configure Github
Just add a Post-Receive hook via the github admin screen.
Friday, February 25, 2011
BDD and TDD
Apparently I have been doing TDD wrong for years (who knew?). There are plenty of resources out there to help, but here are the ones I found useful in the order of most to least useful.
- BDD - TDD done well? Basically explained away my misconceptions about BDD. I thought it a replacement to TDD (unit testing) and it is not.
- Roman Numeral Kata in Ruby. I had thought the point of testing was to test working code and never really bridged to understand how good code comes from bad code that is tested. The video shows by adding tests that define the "correct" code 1 at a time and coding only to the current tests that elegant solutions are likely.
- TDD Problem. It is nice to read articles and watch movies, but until you have actually attempted to solve a real life TDD problem things are not going to make sense. This site is full of problems.
- Gherkin. This is the language used by Cucumber to define BDD.
- How I Learned To Love Testing. Demo of by testing up a test env things are easier.
- How to adopt TDD and ensure adherence? The question posed is strikingly similar to oppositions that I have heard in the past; mostly stemming from misconceptions about testing. The selected answer is well formed, and is the main reason to read the question.
- Ruby Koans. Helps people learn ruby by presenting tests that all fail and requiring the user to code until they pass. The tests are very basic, but it is a good foray into TDD
- Cucumber Tutorials and Related Blog Posts. Just a list of other resources.
Wednesday, February 9, 2011
Sinatra Proxy
Anyone that has developed for the web has come accross the Same Origin Policy problem. Basically it says that for an AJAX call to be valid it must come from the same host as the page, using the same port, subdomain, and protocol. I find there are many cases where I need to gather information from remote hosts, which leaves me two choices: proxy the request through my server, or use an iframe.
In general since it is JSON/XML data I am interested in then an iframe will not work so I have to create a proxy. Below is what I do using Sinatra.
Required Gems
/remote/*
The * tells sinatra to blindly take everything up to the "?" and put it in params[:splat]. I then split out the first item for the server name and port. You could also split out username/password if you want, but I rarely use HTTP Basic Auth so I never do.
I delete the key 'splat' and anything I do not want to forward so that they are not URL encoded to the remote.
urlencode
A simple function that re-encodes params that were placed in the params hash. Sinatra does a good job of taking params that look like color[]=red&color[]=blue and turning them into {"color" => ["red","blue"]}. Therefore I check the value's class for Array and if so I add the "[]" to the param name.
Proxy
The proxy code is a call to Net::HTTP returning the response body. I could also have returned the headers, but in this case I do not care.
In Action
In general since it is JSON/XML data I am interested in then an iframe will not work so I have to create a proxy. Below is what I do using Sinatra.
Required Gems
- Sinatra
- Net::HTTP
- CGI
- URI
Directory Structure
This is just the default that I use for all sinatra apps because it makes things easier. Sinatra will automatically serve files in the public directory if a file by that name exists
- index.html - static file that includes all other files
- public - place where other static files will go
- javascript
- stylesheets
- images
- server.rb - the sinatra app
Server.rb
/remote/*
The * tells sinatra to blindly take everything up to the "?" and put it in params[:splat]. I then split out the first item for the server name and port. You could also split out username/password if you want, but I rarely use HTTP Basic Auth so I never do.
I delete the key 'splat' and anything I do not want to forward so that they are not URL encoded to the remote.
urlencode
A simple function that re-encodes params that were placed in the params hash. Sinatra does a good job of taking params that look like color[]=red&color[]=blue and turning them into {"color" => ["red","blue"]}. Therefore I check the value's class for Array and if so I add the "[]" to the param name.
Proxy
The proxy code is a call to Net::HTTP returning the response body. I could also have returned the headers, but in this case I do not care.
In Action
| /remote/medic/this | -> | /medic:80/this |
| /remote/medic:4567/this | -> | /medic:4567/this |
| /remote/medic:4567/this?_dc=1 | -> | /medic:4567/this |
| /remote/medic/this?foo=bar | -> | /medic:80/this?foo=bar |
| /remote/medic/this?foo[]=bar&foo[]=baz | -> | /medic:80/this?foo[]=bar&foo[]=baz |
Friday, January 28, 2011
RVM
It looks like I am the last hold out for the use of RVM. What prompted my move? Well Macs come with ruby 1.8.7, but I always use ruby 1.9 in my projects. I replaced the standard system ruby with my own 1.9 version. The problem came when starting a new job since they used ruby 1.8.7 (a patch level greater then supplied my Apple), and JRuby.
I spend a few hours just trying to get JRuby to play nice with the 1.9 version that I had installed. Things where not going well. The problems were almost entirely related to path-ing, but I am ruby programer not a system administrator. I was almost ready to give up when I remembered a lightning talk given at the B'more on Rails group on RVM.
In case you, like me, have been hiding under a rock for the last few years RVM is a Ruby Version Manager. In a nutshell it lets you install any or all versions of ruby in their own sandbox (you would be insane to install "all", but you can!). It solves all the problems associated with having different ruby versions installed and allows you to easily switch ruby versions with rvm use XXX where XXX is the version of ruby of you want.
More then just being able to switch ruby versions; you are able to create arbitrary sandboxes for gems called GemSets. This is most useful for me in trying to figure out what gems are used in what projects. In most of my projects now I have a .rvmrc files containing the version of ruby and the GemSet to use for that project: echo "rvm use XXX@YYY --create" > .rvmrc, where XXX is the ruby version and YYY is the GemSet to use. --create just creates a GemSet if it doesn't exist.
Your results may vary, but for me all I had to do was:
I spend a few hours just trying to get JRuby to play nice with the 1.9 version that I had installed. Things where not going well. The problems were almost entirely related to path-ing, but I am ruby programer not a system administrator. I was almost ready to give up when I remembered a lightning talk given at the B'more on Rails group on RVM.
In case you, like me, have been hiding under a rock for the last few years RVM is a Ruby Version Manager. In a nutshell it lets you install any or all versions of ruby in their own sandbox (you would be insane to install "all", but you can!). It solves all the problems associated with having different ruby versions installed and allows you to easily switch ruby versions with rvm use XXX where XXX is the version of ruby of you want.
More then just being able to switch ruby versions; you are able to create arbitrary sandboxes for gems called GemSets. This is most useful for me in trying to figure out what gems are used in what projects. In most of my projects now I have a .rvmrc files containing the version of ruby and the GemSet to use for that project: echo "rvm use XXX@YYY --create" > .rvmrc, where XXX is the ruby version and YYY is the GemSet to use. --create just creates a GemSet if it doesn't exist.
Your results may vary, but for me all I had to do was:
- Follow the quick install: bash < <( curl http://rvm.beginrescueend.com/releases/rvm-install-head )
- List the rubies I could install: rvm list known
- Install a few rubies: rvm install XXX
- Switch to a ruby and test it: rvm use XXX
- Setup and a .rvmrc file: echo "rvm use XXX@YYY --create" > .rvmrc
I have not yet played around enough to see if I could use a GemSet to create a Bundler package. It seems that they are made to play nice with each other, so I foresee no reason it will not be as straight forward as this.
Monday, January 10, 2011
Problems with Agile Implementation
I really like agile programming. It keeps me close to the action, and makes me have to think about my next moves. It also keeps me informed as to what is going on around me. But in my many years of using agile I realize that, though the process itself is very nice, its implementations can tend not to be.
Problem don't arise from agile itself, but who and how it was implemented. If the implementer's goals do not match the Agile Manifesto there is little chance of success. I have used scrum many times and the most common problems I see are:
These are all excuses I have heard. Each time given by a person in chicken role (managers) because they are ignoring changes in the field (military term). Every choice has a set of outcomes: some good, some bad. The attempt with agile is not to mitigate bad outcomes, but to allow those outcomes to contribute to the overall direction.
Problem don't arise from agile itself, but who and how it was implemented. If the implementer's goals do not match the Agile Manifesto there is little chance of success. I have used scrum many times and the most common problems I see are:
- Agile as Micromanagement
- Agile as a Whip
- Agile as an Excuse
Agile as Micromanagement
It looks like:
- Having to break task down into hourly segments of work
- Having to break task that logically have to be done by a single person
- Having to account for ALL time taken, even time not related to code like attending meetings
Agile tenet misused:
- Individuals and interactions over process and tools
- Working software over comprehensive documentation
This happens when a manager (chicken role) is the Scrum Master or when the Product Owner has say over implementation specifics. It is a confusion of roles, which in turn leads to a confusion of goals, which in turn leads to over documentation.
Agile as a Whip
It looks like:
- Filtering a burn-down on an individual basis
- Placing more in the sprint then can be done (but still requiring it all to be done)
- Associating points with people (publicly)
- Associating number of tasks done with effort
- Associating points with hours
- Basically anything where measured output is more important then people
Agile tenet misused:
- Individuals and interactions over process and tools
Anytime you associate numbers with people you have created a crab mentality. Their focus will stop being on software, but on making their numbers better. Those that are better at number games will succeed, those that are better at software will fail.
Anytime you put your people under undo pressure then simple mistakes are made. This is going to later erode confidence in the team. It is going to happen like this: "you missed a comma in a Javascript file which causes it not to work in IE. That was such a simple mistake to have tested for that I am not sure you are testing any of your code." The problem was caused by 4 hours of sleep in 72 hours of coding at the end of an over-extended sprint. The programmer was nearly delirious. It is shocking it was the only mistake, not that it was a simple mistake!
Unfortunately I have seen this situation start innocent enough, with comments like "we don't want to over work the staff" or "we want to make sure they always have something to do" or "we want them working on the correct things". If the "we" in question is management (chicken role) then there is probably already micromanagement going on, and Agile is being used as whip to solve the problems created by the bad implementation.
Agile as an Excuse.
It looks like:
- "You said it would take XXX. It took YYY. You need to make up the difference out of your own time"
- "We cannot slip these date, and you have already pared back the release N sprints ago. You need to put in extra effort"
- "Agile is about being agile. Even though we are mid sprint we are radically changing direction, but we are not canceling the sprint or doing sprint planning. We are just swapping out some tasks for others."
- "You picked the language. It is now your problem to bring this project to conclusion and under budget."
Agile tenet misused:
- Individuals and interactions over process and tools
- Responding to change over following a plan
These are all excuses I have heard. Each time given by a person in chicken role (managers) because they are ignoring changes in the field (military term). Every choice has a set of outcomes: some good, some bad. The attempt with agile is not to mitigate bad outcomes, but to allow those outcomes to contribute to the overall direction.
Sometimes the bad outcome will be that something took to long, or that one language/tool was not the correct choice given the problem set. If for every problem that happens the developer has to take their own time, or face embarrassment, to solve the problem then they will stop making choices. Not just choices that might have bad outcomes, but choices altogether. At which point someone in a chicken role will start making more choices then they should.
Wednesday, December 15, 2010
JS Unit Testing using YUI
Ok, Selenium was a partial success that you can read about here, but it really was harder then I wanted it to be and it required a lot of setup for only a little bit of testing. I noticed that a project that I use a lot ExtJS uses a modified version of YUI Test. So I converted my Selenium test example to YUI Test.
My initial impression was confusion because you have to download the entire YUI 2 suite just get to get the test tools. Also, when you download the entire suite they are many different copies of the same file in various stages of minification. But following the documentation I boiled down exactly what I needed and threw away the rest. I put all the code for my test here so you can follow along.
You will need the following files from the YUI archive:
Now that we have a YAHOO.tool.TestRunner we need to add a test that can be run. Instanciate a new YAHOO.tool.TestCase and add it to the TestRunner. All a TestCase needs is a name and a bunch of functions that start with "test". Everything else is automatic. Below is a simplified version of the full file.
Conclusion
Though Selenium is more automated that comes at the cost of being more complicated then testing should be. If I were a team of programmers then sure setting up and maintaining Selenium Remote controls would be a small part of the overall effort, but since I am not a team of programmers I think it is overkill.
What I really need is an easy to run, easy to write, repeatable, unit testing framework in JS. I do the leg work on pointing my various browsers at the html and reviewing the results. When things get big enough that I need to setup a continuous integration server, or I have a QA department, then I will give Selenium another go. For now YUI test is the way to go.
My initial impression was confusion because you have to download the entire YUI 2 suite just get to get the test tools. Also, when you download the entire suite they are many different copies of the same file in various stages of minification. But following the documentation I boiled down exactly what I needed and threw away the rest. I put all the code for my test here so you can follow along.
You will need the following files from the YUI archive:
- build/logger/assets/logger.css
- build/logger/logger.js
- build/yuiloader-dom-event/yuiloader-dom-event.js
- build/yuitest/assets/testlogger.css
- build/yuitest/yuitest.js
Create an HTML file that includes the css and js files:
The HTML will also need to instantiate the test logger and run the test runner global. I bound the test run to a button so I could control when it ran:
Now that we have a YAHOO.tool.TestRunner we need to add a test that can be run. Instanciate a new YAHOO.tool.TestCase and add it to the TestRunner. All a TestCase needs is a name and a bunch of functions that start with "test". Everything else is automatic. Below is a simplified version of the full file.
Conclusion
Though Selenium is more automated that comes at the cost of being more complicated then testing should be. If I were a team of programmers then sure setting up and maintaining Selenium Remote controls would be a small part of the overall effort, but since I am not a team of programmers I think it is overkill.
What I really need is an easy to run, easy to write, repeatable, unit testing framework in JS. I do the leg work on pointing my various browsers at the html and reviewing the results. When things get big enough that I need to setup a continuous integration server, or I have a QA department, then I will give Selenium another go. For now YUI test is the way to go.
Sunday, December 12, 2010
Dealing with Email overload
This isn't strictly software related, but a lot of us have to deal with the horror that is email. Email is not a good solution to any problem, but it is ubiquitous so it is used for all things: personal correspondence, commit tracking, defect notification, task notification, etc... Email is all to often used as a mechanism to pass-the-buck.
The only way to deal with this email overload is to set boundaries on email usage. A lot of people will find these boundaries annoying, if not unworkable. Just stick with it and lead by example. Eventually, in a time of high stress, you will be able to get to important messages fast and they will be left floundering.
My results
I am putting the summary first in hopes that you might actually try some of these suggestions. On average I get 50 to 200 work related emails a day. In any given day (saturday and sunday included) I will need to respond to 5 to 10 of them. That means that I get between 40 and 195 junk emails that pass (and should pass) my junk mail filters.
By focusing on making sure my inbox only includes import emails I have reduced my inbox to 3 to 5 message each check (and I check twice a day). On busy days I only ever check my inbox, relying on others to contact me via a different medium if they really need me. When there is a less busy day I go through the other inbox and deal with those messages.
At the time I am writing this (on sunday) I have 1 email in my inbox and 91 emails in my other inbox that were all sent saturday. A quick read of the 1 email and I will have to spend 5 minutes reviewing code, but the rest can wait until monday.
Use the right messaging system
Use email for messages that do not need an immediate response. Since there is no message size limit, make sure you use the most of it. Write emails that are well detailed and specific. If at any point a message can be answered with "Ok" or some other monosyllabic word then email was not the correct choice.
Use Instant Messages (IM,IRC,etc...) for conversations that need semi immediate responses, and a possible record. Many IM packages can log conversations for later viewing, which is useful when you forget things. There are message length and formatting restrictions so this forces the messages to be brief and specific.
Use Phone, Skype, or face to face contact when a response is needed immediately.
Use Twitter, or some other global message posting service to track commits, continuous integration fails, defects, etc...
Use a wiki, or blog to track generic instructions or documentation.
Check email twice a day (only)
The easiest way to train people not to use email as a crutch is not use it as one yourself. Only check email twice a day, and give a concerted effort to reduce that to once a day within a month, and once a week within 6 months. Setup the other messaging systems so that email is used only for what it needs to be. And when people step out of line, correct them.
Email should not be the first thing that you check in the morning, as you should not be working out of email. It should also not be the last thing you check as it will disrupt your already stressful commute/home life. Instead check email 2 hours after the start of the day, and 2 hours before the end of the day. If you work a 9-to-5 that means once at 11am and once at 3pm.
The day you start doing this, tell the people that send you the most email and the ones that you will most affect by the change, and no one else. You are not trying to be sneaky, but if you blast an email to everyone then you are going to make it a big deal; which it is not. The others will learn over time.
When someone tells you that you need to check your email and read their message do it, but only check their email, ignore all other messages.
Don't use Inbox as an archive
Once you are finished reading an email, either deal with the email and delete it or archive it. Create a separate archive folder and move emails there if you need to save them. Your goal is aways to reduce the inbox to zero
Create an other inbox
Create a filter that will dump any messages where you are not the direct recipient into a different folder. This should be the first filter you create, but the last filter that is applied to any message. Create as many other filters and folders as you can to move useless messages round. The goal is to remove any message that you do not need to act on so that what is left is just what is important. The trash can is a good folder to dump things that are truly useless.
Use the server's filtering mechanism
When possible have server do all the filtering that way you can use multiple email clients and will not be dependent on leaving an email client on. All Exchange servers and many online email services can do server filtering. When using Outlook, be careful, the ease of creating filters is sometimes offset by the fact that it lies about what filters can be saved to the server. Though harder, since MS didn't spend much time on the server-side features of Exchange, it is better to build the filters on the server directly.
Reduce the inbox to zero (in one sitting)
The goal is always to reduce your inbox to zero. Once all the filters are in place, the only thing left to actually deal with all the important emails (at least that is the hope). When dealing with email decide if the email should be dealt with, deferred, or archived.
If time is really an issue then find the messages to archive and defer first, and move them. That way what is left is just the stuff to deal with now.
The only way to deal with this email overload is to set boundaries on email usage. A lot of people will find these boundaries annoying, if not unworkable. Just stick with it and lead by example. Eventually, in a time of high stress, you will be able to get to important messages fast and they will be left floundering.
My results
I am putting the summary first in hopes that you might actually try some of these suggestions. On average I get 50 to 200 work related emails a day. In any given day (saturday and sunday included) I will need to respond to 5 to 10 of them. That means that I get between 40 and 195 junk emails that pass (and should pass) my junk mail filters.
By focusing on making sure my inbox only includes import emails I have reduced my inbox to 3 to 5 message each check (and I check twice a day). On busy days I only ever check my inbox, relying on others to contact me via a different medium if they really need me. When there is a less busy day I go through the other inbox and deal with those messages.
At the time I am writing this (on sunday) I have 1 email in my inbox and 91 emails in my other inbox that were all sent saturday. A quick read of the 1 email and I will have to spend 5 minutes reviewing code, but the rest can wait until monday.
Use the right messaging system
Use email for messages that do not need an immediate response. Since there is no message size limit, make sure you use the most of it. Write emails that are well detailed and specific. If at any point a message can be answered with "Ok" or some other monosyllabic word then email was not the correct choice.
Use Instant Messages (IM,IRC,etc...) for conversations that need semi immediate responses, and a possible record. Many IM packages can log conversations for later viewing, which is useful when you forget things. There are message length and formatting restrictions so this forces the messages to be brief and specific.
Use Phone, Skype, or face to face contact when a response is needed immediately.
Use Twitter, or some other global message posting service to track commits, continuous integration fails, defects, etc...
Use a wiki, or blog to track generic instructions or documentation.
Check email twice a day (only)
The easiest way to train people not to use email as a crutch is not use it as one yourself. Only check email twice a day, and give a concerted effort to reduce that to once a day within a month, and once a week within 6 months. Setup the other messaging systems so that email is used only for what it needs to be. And when people step out of line, correct them.
Email should not be the first thing that you check in the morning, as you should not be working out of email. It should also not be the last thing you check as it will disrupt your already stressful commute/home life. Instead check email 2 hours after the start of the day, and 2 hours before the end of the day. If you work a 9-to-5 that means once at 11am and once at 3pm.
The day you start doing this, tell the people that send you the most email and the ones that you will most affect by the change, and no one else. You are not trying to be sneaky, but if you blast an email to everyone then you are going to make it a big deal; which it is not. The others will learn over time.
When someone tells you that you need to check your email and read their message do it, but only check their email, ignore all other messages.
Don't use Inbox as an archive
Once you are finished reading an email, either deal with the email and delete it or archive it. Create a separate archive folder and move emails there if you need to save them. Your goal is aways to reduce the inbox to zero
Create an other inbox
Create a filter that will dump any messages where you are not the direct recipient into a different folder. This should be the first filter you create, but the last filter that is applied to any message. Create as many other filters and folders as you can to move useless messages round. The goal is to remove any message that you do not need to act on so that what is left is just what is important. The trash can is a good folder to dump things that are truly useless.
Use the server's filtering mechanism
When possible have server do all the filtering that way you can use multiple email clients and will not be dependent on leaving an email client on. All Exchange servers and many online email services can do server filtering. When using Outlook, be careful, the ease of creating filters is sometimes offset by the fact that it lies about what filters can be saved to the server. Though harder, since MS didn't spend much time on the server-side features of Exchange, it is better to build the filters on the server directly.
Reduce the inbox to zero (in one sitting)
The goal is always to reduce your inbox to zero. Once all the filters are in place, the only thing left to actually deal with all the important emails (at least that is the hope). When dealing with email decide if the email should be dealt with, deferred, or archived.
If time is really an issue then find the messages to archive and defer first, and move them. That way what is left is just the stuff to deal with now.
Sunday, December 5, 2010
How to be a bad boss
Being a boss is a complicated thing. It is your job to get people to do things, sometimes things they do not want to do. And it is especially complicated in the software industry, where it is like herding cats.
I see a lot of posts on how to be a good boss, but the problem there is that they often forget to mention the things that can and will immediately erode any success you might have had. I am going to assume that as a reader you strive to be a person who others are willing to follow.
Nobody is perfect, so you will probably have done at least one of these things in the past. Or you do then without even knowing. Now is your chance to stop, and be a constructive boss who people want to work for.
Be smarmy
Yep, this is number one. Smarmy people are falsely friendly (think used car dealers). Notice I did not say do not "be mean." As a boss sometimes you will need to be mean, or at least not very nice. And even that should be kept to a minimum, but it is never OK to be smarmy. All it does is make people uncomfortable confiding in you, which means they will either find better employment (if they can) or they will sabotage you.
Here are some examples of what I mean by smarmy:
Some ways to tell that you have already failed at this:
Be a hypocrite
A hypocrite is someone who says one thing and thinks or does another. It can be as overt as being prejudiced (racist, sexist, etc...) or as covert as being passive aggressive. Being a hypocrite is risky because when other people find out, you are just being deceitful, and no one wants to deal with that.
One example is saying that code needs to be high quality but not leaving time for testing. Overtly this often resembles explicitly adding a testing phase at the end of coding and then cutting it if coding goes long. Covertly this is often assuming that testing is done as part of coding, but scoffing at longer estimates. Speed and quality have a tenuous relationship. Something done slowly may or may not be of quality, but something quickly is almost never of quality.
The best way not to be a hypocrite is not to bring your values and prejudices into the equation. To do this though you have to understand what your values and prejudices are. In the case of the no testing, quality is explicitly stated as the important part, but speed is implicitly stated as the important factor. More specifically speed at the cost of quality is stated as the import factor. To avoid this, it is important to explicitly state the importance of all three tenets of the project triangle: that way you avoid the embarrassing case where one tenet goes to 0 unintentionally. See: Project Triangle.
Be arrogant
I am not talking about being hard headed or stubborn. I am talking about being truly arrogant. Stubborn people will listen to reason, assuming the opposing argument is good enough; arrogant people cannot be directly convinced. There are two forms of arrogance to watch out for: arrogance of idea, and arrogance of presenter. Arrogance of idea is simply dismissing an idea because it is in direct conflict with your internal ideas or values. Arrogance of presenter is rejecting an idea because of who presented it.
Two engineers approach you with different solutions to the problem of releasing on time: one says to keep the feature set and stop doing unit testing, and the other says reduce the feature set but keep the unit testing. Which do you choose? If you choose "keep the feature set" then you wrong. If you choose "keep the unit testing" you are also wrong. If you chose either (based on only the information provided) then the choice you made was based on you internal values only and not based on the problem being presented.
In the context of work the truth is that new hires probably know more about a given framework than you, and certainly will have a different perspective on how things should be done. They are probably offering you this knowledge, because they have already encountered the problem you are now seeing and have found an appropriate solution. It is tempting to dismiss this simply because a new hire presented it and they don't know the full business impact of their suggestion. But ask yourself: if the system architect presented you with this idea would you accept it? If yes, then you are suffering from arrogance of presenter and should tread lightly.
I suggest instead that you judge an idea (never a presenter) on its merits in the context of only the problem (never on facts you assume to be true). And make sure you are consciously and actively judging the idea, and you are not adding your own problem or values.
Offer post hoc rewards
A post hoc reward is a reward given after work is complete. In physical work the effects of post hoc rewards are well known and lead to better results, but in knowledge work offering post hoc rewards has a distracting effect. Work will take longer and be of lower quality. It will make employees very good at performing work that maximises their incentives, and not at developing a quality product. Be aware that offering reward for work done defines a tangible value for that work, which may demoralize an employee who feels under compensated as a result.
http://www.youtube.com/watch?v=u6XAPnuFjJc
Intrinsic rewards can and should be used. These are things that are given universally and without reservation. Basic examples would be vacation, and health benefits. Other examples would be a free day to work on any project the employee wanted, or free soda/tea/coffee. These intrinsic benefits help endear you and the company to the employee.
Accept estimates less than 4 hours
This may only be true in software, but tasks never take less than 4 hours. A task is really an atomic complete chunk of work, so to be considered complete it must be coded, tested, reviewed, and committed. However, some employees will claim they finish tasks sooner. Often these people are cutting corners (not testing, or not getting a review) or they are doing a bunch of tasks that should have logically been considered one task.
Either way they are playing a game with the numbers to get their counts higher, which means that you are probably rewarding over aggressive estimates, and have a huge defect backlog. Well done!
Assume research is intrinsic
I have seen this bite so many bosses, where they say something like "tasks cannot take longer then 4 days." The problem is that now you have employees trying to split tasks that have little or no real research done. So when it comes time to implement you have a bunch of small tasks that are too small to warrant research, but no real clear direction because no real research was done.
Estimates of several weeks or months are fine early in the process. But enough time needs to be given to investigate feasibility prior to high level scoping. Prior to implementation, time should be given to research an implementation and split the tasks out. All of this time should have been blocked in as a single unit during high level scoping.
Require meetings
Meetings cost time and money. And in addition to the meeting itself there is time before the meeting where people ramp down, and time after the meeting when people need to ramp back up again. Both ramping phases are about 10 minutes each.
To monetize this for you, let's say you have 12 employees going to a meeting, and on average they make $24 an hour, and the meeting is 15 minutes (a scrum). The total chunk of wasted time is 35 minutes or about $14 per employee. For the company that means you wasted $168. And that does not include any prep time employees had to take.
In general, meetings need to be kept to a minimum and kept on track because they will end up being the single most costly event both in terms of money and productivity.
Watch your employees work
Nobody is comfortable being scrutinized. Do not set up your office so that you are looking into your employees' cubes, and don't wonder around aimlessly, and never under any circumstances hover. By doing this you are showing your employees that the most important thing is to look busy (a function of the keyboard and finger), not to solve problems (a function of the brain). At the point where your employees feel scrutinized they will work just hard enough to not get fired, and will partake in CYA games.
The best example is Office Space the movie. Little more needs to be said.
I see a lot of posts on how to be a good boss, but the problem there is that they often forget to mention the things that can and will immediately erode any success you might have had. I am going to assume that as a reader you strive to be a person who others are willing to follow.
Nobody is perfect, so you will probably have done at least one of these things in the past. Or you do then without even knowing. Now is your chance to stop, and be a constructive boss who people want to work for.
Be smarmy
Yep, this is number one. Smarmy people are falsely friendly (think used car dealers). Notice I did not say do not "be mean." As a boss sometimes you will need to be mean, or at least not very nice. And even that should be kept to a minimum, but it is never OK to be smarmy. All it does is make people uncomfortable confiding in you, which means they will either find better employment (if they can) or they will sabotage you.
Here are some examples of what I mean by smarmy:
- Suggest that a problem can be solved by the employee working overtime
- Using scrum (or any general meeting) to point out an employee's failure
- Joke about firing an employee
- Make any sarcastic comment about an employee in the presence of others
- Only talking to an employee when you need them to do something (i.e., I am only talking to you because I want something)
- All laughter stops when you enter the room
- Conversations between you and an employee die quickly
- Employees no longer tell you about issues they are having
Be a hypocrite
A hypocrite is someone who says one thing and thinks or does another. It can be as overt as being prejudiced (racist, sexist, etc...) or as covert as being passive aggressive. Being a hypocrite is risky because when other people find out, you are just being deceitful, and no one wants to deal with that.
One example is saying that code needs to be high quality but not leaving time for testing. Overtly this often resembles explicitly adding a testing phase at the end of coding and then cutting it if coding goes long. Covertly this is often assuming that testing is done as part of coding, but scoffing at longer estimates. Speed and quality have a tenuous relationship. Something done slowly may or may not be of quality, but something quickly is almost never of quality.
The best way not to be a hypocrite is not to bring your values and prejudices into the equation. To do this though you have to understand what your values and prejudices are. In the case of the no testing, quality is explicitly stated as the important part, but speed is implicitly stated as the important factor. More specifically speed at the cost of quality is stated as the import factor. To avoid this, it is important to explicitly state the importance of all three tenets of the project triangle: that way you avoid the embarrassing case where one tenet goes to 0 unintentionally. See: Project Triangle.
Be arrogant
I am not talking about being hard headed or stubborn. I am talking about being truly arrogant. Stubborn people will listen to reason, assuming the opposing argument is good enough; arrogant people cannot be directly convinced. There are two forms of arrogance to watch out for: arrogance of idea, and arrogance of presenter. Arrogance of idea is simply dismissing an idea because it is in direct conflict with your internal ideas or values. Arrogance of presenter is rejecting an idea because of who presented it.
Two engineers approach you with different solutions to the problem of releasing on time: one says to keep the feature set and stop doing unit testing, and the other says reduce the feature set but keep the unit testing. Which do you choose? If you choose "keep the feature set" then you wrong. If you choose "keep the unit testing" you are also wrong. If you chose either (based on only the information provided) then the choice you made was based on you internal values only and not based on the problem being presented.
In the context of work the truth is that new hires probably know more about a given framework than you, and certainly will have a different perspective on how things should be done. They are probably offering you this knowledge, because they have already encountered the problem you are now seeing and have found an appropriate solution. It is tempting to dismiss this simply because a new hire presented it and they don't know the full business impact of their suggestion. But ask yourself: if the system architect presented you with this idea would you accept it? If yes, then you are suffering from arrogance of presenter and should tread lightly.
I suggest instead that you judge an idea (never a presenter) on its merits in the context of only the problem (never on facts you assume to be true). And make sure you are consciously and actively judging the idea, and you are not adding your own problem or values.
Offer post hoc rewards
A post hoc reward is a reward given after work is complete. In physical work the effects of post hoc rewards are well known and lead to better results, but in knowledge work offering post hoc rewards has a distracting effect. Work will take longer and be of lower quality. It will make employees very good at performing work that maximises their incentives, and not at developing a quality product. Be aware that offering reward for work done defines a tangible value for that work, which may demoralize an employee who feels under compensated as a result.
http://www.youtube.com/watch?v=u6XAPnuFjJc
Intrinsic rewards can and should be used. These are things that are given universally and without reservation. Basic examples would be vacation, and health benefits. Other examples would be a free day to work on any project the employee wanted, or free soda/tea/coffee. These intrinsic benefits help endear you and the company to the employee.
Accept estimates less than 4 hours
This may only be true in software, but tasks never take less than 4 hours. A task is really an atomic complete chunk of work, so to be considered complete it must be coded, tested, reviewed, and committed. However, some employees will claim they finish tasks sooner. Often these people are cutting corners (not testing, or not getting a review) or they are doing a bunch of tasks that should have logically been considered one task.
Either way they are playing a game with the numbers to get their counts higher, which means that you are probably rewarding over aggressive estimates, and have a huge defect backlog. Well done!
Assume research is intrinsic
I have seen this bite so many bosses, where they say something like "tasks cannot take longer then 4 days." The problem is that now you have employees trying to split tasks that have little or no real research done. So when it comes time to implement you have a bunch of small tasks that are too small to warrant research, but no real clear direction because no real research was done.
Estimates of several weeks or months are fine early in the process. But enough time needs to be given to investigate feasibility prior to high level scoping. Prior to implementation, time should be given to research an implementation and split the tasks out. All of this time should have been blocked in as a single unit during high level scoping.
Require meetings
Meetings cost time and money. And in addition to the meeting itself there is time before the meeting where people ramp down, and time after the meeting when people need to ramp back up again. Both ramping phases are about 10 minutes each.
To monetize this for you, let's say you have 12 employees going to a meeting, and on average they make $24 an hour, and the meeting is 15 minutes (a scrum). The total chunk of wasted time is 35 minutes or about $14 per employee. For the company that means you wasted $168. And that does not include any prep time employees had to take.
In general, meetings need to be kept to a minimum and kept on track because they will end up being the single most costly event both in terms of money and productivity.
Watch your employees work
Nobody is comfortable being scrutinized. Do not set up your office so that you are looking into your employees' cubes, and don't wonder around aimlessly, and never under any circumstances hover. By doing this you are showing your employees that the most important thing is to look busy (a function of the keyboard and finger), not to solve problems (a function of the brain). At the point where your employees feel scrutinized they will work just hard enough to not get fired, and will partake in CYA games.
The best example is Office Space the movie. Little more needs to be said.
Saturday, December 4, 2010
GIT with SVN
Normally, I would just use GIT without a bridge to another control system, but many companies use SVN. There are just so many benefits to using GIT that, for me, I am going to use it if there is a bridge to repository type the company uses. I certainly don't hate SVN or CVS or Perforce, but GIT allows me to work the way that I know I am most productive; which is commit early, commit often.
What I mean by commit early, commit often is that I commit even if I only have part of the solution. As I find the other parts of the solution I commit those as well. That way when I am 2 or 3 days into a fix I already have the commit messages saved in GIT, so I don't have to remember what I did for those 2 or 3 days. When the solution is shippable only then do I push it up to the company's repository.
Benefits of GIT include:
With GIT's power comes a little bit more complexity, and here I will detail the method that I have developed over months of fits and starts. That way you can experience the benefits of using GIT for day to day work, but still use SVN when dealing with corporate.
Settings up the SVN Bridge
You can have GIT manage an entire SVN repository, branches and all. However, for GIT to do this it must checkout every revision of the SVN repo. This can be very painful when there are a lot of commits. Instead I recommend only managing a single branch starting a specific revision near HEAD. You will lose history older then that revision, but it does save a lot of time for large SVN repositories.
For the below example I am going to assume we have a standard SVN repository at http://example.com/svn, the latest revision is 400, and the SVN username is test.
Find the latest revision of the repository:
The latest revision will start with an "r" and be within the first 5 lines.
Setting up a git repo:
Now you have a local GIT repo in dev that is synced to SVN trunk at revision 400. And when you git svn dcommit the user test will be used.
Always work in a branch
In my company before anything is allowed to be checked into SVN it must go through a peer review. In any given day I might work on 2 or 3 bugs/tasks. For each, I create a GIT branch with the bug/task ID and work there. When I am done I use git log -p to list the diffs that I submit for review. Then I move on to the next item, while the fix is being reviewed. When the first bug/task is reviewed and accepted I jump back to master, rebase it, jump to the branch, rebase master, jump back to master and merge the branch, and finally svn dcommit everything. After I mark the bug/task complete I also delete the branch. If the code is not accepted then I still have a branch where I can make the required corrections and repeat the process.
It might sound complicated, but it really isn't. The only reason for all this rebasing is so that GIT's native merge tools deal with SVN merge conflicts. I am not sure why, but they are far better then what the SVN bridge can do, and will ultimately lead to few headaches for you.
In code it looks like:
This style also works well if your boss comes over at the 11th hour and assignes you a new emergency assignment. When you are done with the emergency switching gears is as easy as switching branches.
DCommitting your changes
As states above I use the checkout, rebase, checkout, rebase, checkout, merge, dcommit style. This seems cumbersome until you understand the purpose.
From any branch always checkout into master. This allows master to stay pure of your changes and makes its less likely that git svn will fail.
Once master is up-to-date checkout the branch again and rebase the master changes into the branch. Fixing any rebase conflicts there might be. By fixing them on the branch we keep master clean so we are using git's rebase/merge capabilities, not the SVN bridge's. There are times this step can be skipped, but once you have to deal with your first rebase conflict from the bridge you will wish you had branched.
Now that the branch holds the latest code to be dcommitted to SVN: checkout master, merge the branch, and dcommit master. You could rebase the changes from the branch if you prefer, it really makes no difference because your changes are on top of SVN now either way. Once done all of master's log messages will be rewritten to what is in SVN.
All together it looks like this:
Pro Tips
Different user names
Use a different username for SVN and GIT. That way it is easy to see in the log what is committed to SVN since the bridge will rewrite the commit log from what SVN says.
Commits that are in SVN also have the SVN revision number in the log message, but I find it easier to use usernames since it is at the top of the log message.
Setup Aliases
Git allows more commands to be added via aliases. An alias can be a shortening of a git command: st = status. Or it can be a shell command that git will execute test = !sh -c 'echo "it works!"' (notice the leading !).
Here is the alias part of my ~/.gitconfig file looks like:
Notice that st-br, up-br, and co-br are basically all the set of commands I noted above in single command style.
Stashing changes
The stash is a hidden place that git can keep changes that are not yet ready to commit. This is very useful if you get switched to another task and really don't have time to fully vet a change on the current task. You can stash the outstanding change and later replay them.
git stash keeps a queue of changes so you can stash more then one thing, but you can only replay them top down.
Resources
What I mean by commit early, commit often is that I commit even if I only have part of the solution. As I find the other parts of the solution I commit those as well. That way when I am 2 or 3 days into a fix I already have the commit messages saved in GIT, so I don't have to remember what I did for those 2 or 3 days. When the solution is shippable only then do I push it up to the company's repository.
Benefits of GIT include:
- Being able to share non production ready code (Peer to Peer)
- Being able to have many local branches
- Being able to logically group commits (via local branches) and push all at once
- Fantastic branch switching/merging
- Rarely will you ever have to fix a merge conflict yourself
- Rebase as well as merge
- Rebase is SVNs style of linear commits
- Merge is non-linear and tries to keep commits sequentially ordered by date. So if two branches are merged and both were actively worked on then the commits are intermixed. (makes a lot more sense in practice then in writing)
With GIT's power comes a little bit more complexity, and here I will detail the method that I have developed over months of fits and starts. That way you can experience the benefits of using GIT for day to day work, but still use SVN when dealing with corporate.
Settings up the SVN Bridge
You can have GIT manage an entire SVN repository, branches and all. However, for GIT to do this it must checkout every revision of the SVN repo. This can be very painful when there are a lot of commits. Instead I recommend only managing a single branch starting a specific revision near HEAD. You will lose history older then that revision, but it does save a lot of time for large SVN repositories.
For the below example I am going to assume we have a standard SVN repository at http://example.com/svn, the latest revision is 400, and the SVN username is test.
Find the latest revision of the repository:
svn log http://example.com/svn/trunk | head
The latest revision will start with an "r" and be within the first 5 lines.
Setting up a git repo:
git svn init --username=test http://example.com/svn/trunk dev git svn fetch -r 400
Now you have a local GIT repo in dev that is synced to SVN trunk at revision 400. And when you git svn dcommit the user test will be used.
Always work in a branch
In my company before anything is allowed to be checked into SVN it must go through a peer review. In any given day I might work on 2 or 3 bugs/tasks. For each, I create a GIT branch with the bug/task ID and work there. When I am done I use git log -p to list the diffs that I submit for review. Then I move on to the next item, while the fix is being reviewed. When the first bug/task is reviewed and accepted I jump back to master, rebase it, jump to the branch, rebase master, jump back to master and merge the branch, and finally svn dcommit everything. After I mark the bug/task complete I also delete the branch. If the code is not accepted then I still have a branch where I can make the required corrections and repeat the process.
It might sound complicated, but it really isn't. The only reason for all this rebasing is so that GIT's native merge tools deal with SVN merge conflicts. I am not sure why, but they are far better then what the SVN bridge can do, and will ultimately lead to few headaches for you.
In code it looks like:
git> git svn rebase git> git checkout -b task1 ... work on task 1 git> git log -p -n X > task1.diff ... create diff of all (X) changes needed for task1 ... email the diff for review git> git checkout master git> git svn rebase git> git checkout -b task2 ... work on task 2 ... when task 1 is approved commit what you have for task 2 and dcommit task1 ... return to task 2 when task 1 is committed
This style also works well if your boss comes over at the 11th hour and assignes you a new emergency assignment. When you are done with the emergency switching gears is as easy as switching branches.
DCommitting your changes
As states above I use the checkout, rebase, checkout, rebase, checkout, merge, dcommit style. This seems cumbersome until you understand the purpose.
From any branch always checkout into master. This allows master to stay pure of your changes and makes its less likely that git svn will fail.
Once master is up-to-date checkout the branch again and rebase the master changes into the branch. Fixing any rebase conflicts there might be. By fixing them on the branch we keep master clean so we are using git's rebase/merge capabilities, not the SVN bridge's. There are times this step can be skipped, but once you have to deal with your first rebase conflict from the bridge you will wish you had branched.
Now that the branch holds the latest code to be dcommitted to SVN: checkout master, merge the branch, and dcommit master. You could rebase the changes from the branch if you prefer, it really makes no difference because your changes are on top of SVN now either way. Once done all of master's log messages will be rewritten to what is in SVN.
All together it looks like this:
git> git checkout master git> git svn rebase git> git checkout task1 git> git rebase master ... SVN needs your changes to be rebased so rebase master ... by rebasing onto to a branch it is easier to deal with rebase failures ... fix any rebase issues git> git checkout master git> git merge task1 ... could merge or rebase, doesn't matter here git> git svn dcommit ... mark the task closed git> git brach -D task1 ... svn doesn't always mark the branch merged properly so use -D instead of -d
Pro Tips
Different user names
Use a different username for SVN and GIT. That way it is easy to see in the log what is committed to SVN since the bridge will rewrite the commit log from what SVN says.
- For SVN I use jkamenik.
- For GIT I use jkamenik at gmail dot com.
Commits that are in SVN also have the SVN revision number in the log message, but I find it easier to use usernames since it is at the top of the log message.
Setup Aliases
Git allows more commands to be added via aliases. An alias can be a shortening of a git command: st = status. Or it can be a shell command that git will execute test = !sh -c 'echo "it works!"' (notice the leading !).
Here is the alias part of my ~/.gitconfig file looks like:
[alias]
# Old SVN aliases
ci = commit
co = checkout
st = status
stat = status
# stuff I find useful
br = branch
df = diff
rm-all = !git st | grep deleted | awk '{print $3}' | xargs git rm
add-all = !git st | grep modified | awk '{print $3}' | xargs git add
st-br = "!f(){ git co master && git svn rebase && git co -b $1 }; `f`"
up-br = "!f(){ git co master && git svn rebase && git co $1 }; `f`"
co-br = "!f(){ git up-br $1 && git co master && git merge $1 && git svn dcommit }; `f`"
Notice that st-br, up-br, and co-br are basically all the set of commands I noted above in single command style.
Stashing changes
The stash is a hidden place that git can keep changes that are not yet ready to commit. This is very useful if you get switched to another task and really don't have time to fully vet a change on the current task. You can stash the outstanding change and later replay them.
git stash keeps a queue of changes so you can stash more then one thing, but you can only replay them top down.
git> git stash ... hides all modified files git> git stash list ... lists all stashes git> git stash apply ... applies the top stash, but does not remove it git> git stash pop ... applies the top stash, and remove it
Resources
- GIT <-> SVN workflow: http://www.biostat.jhsph.edu/~rpeng/biostat776/workflow.html
- Effectively using GIT with SVN: http://www.viget.com/extend/effectively-using-git-with-subversion/
Subscribe to:
Posts (Atom)