Consulting Toolsmiths - Matt Doar

Curiosity and Control

2011-10-07T14:34:00.000-07:00

I've also been thinking about why some people write code and some don't. I think there is indeed the creative aspect, and that's often expressed in other kinds of creative efforts. But there's also the aspect of curiosity about the software that we use.

Some people really like to know how things work, including their software. It seems to me that this is connected to a desire to control one's environment. So perhaps part of coding is about being control?

I must see what Computer Power and Human Reason has to say about this.

Life is Diff and Patch, Diff and Patch

2011-10-07T14:32:00.000-07:00

There are two common Unix tools named 'diff' and 'patch'. Diff tells you what the difference is between two files. Patch takes what diff told you and merges those differences (aka changes) to another file. Now every tool I've used in the last twenty years has its own need for diff and patch functionality. Consider:

Word or text documents - show me what's changed, aka 'track changes'. Merge (patch) text from one document to another

Java API - what changed between two versions of an API

JIRA (the issue tracker) - show me what's new in this bug, merge this configuration to another instance of JIRA

So diff and patch seems to be a common theme of what I do for a living. But life is also diff and patch at some level - see what's different between two people and merge those differences to another generation of people. There's more in this analogy than I can get into words right now, I think.

Accounting for Bugs in Agile Development

2011-09-16T10:18:00.000-07:00

There's always some discussion about how to account for the time spent fixing bugs in a project. I think it helps to view bugs as incomplete features, as in:

"I expected the feature to behave like this, but instead it behaves like that"

So the time spent fixing bugs can be measured in exactly the same way that features can be measured.

Joining CustomWare

2011-09-02T15:29:00.000-07:00

My status at CustomWare has changed from subcontractor to a permanent employee. We celebrated with a surprise ice-cream cake with "Chief Toolsmith" iced onto it. I suspect that's something that people are rarely asked to write on a cake.

Thanks for the welcome!

The Incomplete Image

2011-03-26T13:08:00.000-07:00

I find it remarkable how the same piece of music can touch me deeply at one time and yet barely affect me at another. The recording hasn't changed, so it must be me. This ties into the idea that art is not just what is created by another, but also depends how it is received at a certain time.

That's all.

On Anonymous Bugs

2011-03-09T18:14:00.000-08:00

Anonymity is a wonderful thing for many serious matters in this world. But posting unexceptional comments anonymously on a bug (or webpage) because you just can't be bothered to fill in your name is not wonderful. It just makes the anonymous author appear to lazy to register. And then the person reading the comment thinks less of the comment because it was made anonymously.

It's not just what you say, it's how you say it.

Filing a bug doesn't fix a bug

2011-03-09T16:06:00.000-08:00

"I filed this bug a year ago and it isn't fixed yet".
"Other bugs were more important than your bug"
"But, but, *I* filed it!" (tantrum follows)

I'm always surprised by the number of people who think that that a bug should automatically be fixed just because they bothered to file it. All that can be expected is that the reporter is thanked, the bug is looked at, and possibly moved to the next stage of its life. That might be closure or marking as ready for more work.

A better approach is for the project to explain prominently how their bugs are triaged and how limited their resources are. Details of how to provide more cash resources and what that buys is also helpful.

~Matt

What if Christmas became a world-changing event again?

2010-11-29T14:19:00.000-08:00

I came across the Advent Conspiracy today and I like it. And its ideas can be applied to any special day that has become poisoned by profit.

"What was once a time to celebrate the birth of a savior has somehow turned into a season of stress, traffic jams, and shopping lists.

And when it's all over, many of us are left with presents to return, looming debt that will take months to pay off, and this empty feeling of missed purpose. Is this what we really want out of Christmas?

What if Christmas became a world-changing event again?"

Word for the day: Disintermediation

2010-11-09T15:56:00.000-08:00

From Wikipedia: the removal of intermediaries in a supply chain: "cutting out the middleman"

I've been working as a JIRA specialist for some larger consulting businesses recently and this matter has come up in discussion a few times. I'm glad to see there's a nice long word for such a nasty practice. It's a sensitive matter for everyone but I naturally err on the side of caution, even if I've had existing business with the same customer that is now using the other consulting business.

I wonder if I can get my 14-year old to use it correctly in class. I reckon it would make her English teacher's day.

Because it is awesome!

2010-10-29T11:28:00.000-07:00

"Why did you bring it to share?"
"kus it is osum."

A standard part of US education is show-and-tell. Some classes have the children fill in a form before bringing something in, both to encourage their writing and stem the flow. My 6-year old Luke found a chunk of crystal and filled in a form. His quick and simple dude-style answer to the question "why?" was a lovely explanation of the wonders of our world.

Another job that I have more respect for, the more I know of it

2010-10-28T11:06:00.000-07:00

Gear Designers

Some clever people at NASA put together a document describing what goes into making a gear. The tooth shape and material questions I was aware of from my undergraduate days, but their calculations about just how different lubricants work around complicated shapes, expected gear lifetimes and dynamic force calculations are impressive. And it's all pretty modern knowledge apparently, mostly since the 1920's.

After reading it I'm amazed that helicopters don't crash more often!

I signed an oath

2010-10-25T13:18:00.000-07:00

Alistair Cockburn is a well-known programmer who is fed up with
infighting in software development. So he came up with an Oath of Non-Allegiance.

"I promise not to exclude from consideration any idea based on its source, but to consider ideas across schools and heritages in order to find the ones that best suit the current situation."

Makes sense to me, and for more than software development.

Hidden depths, and Things That Will Never Be

2010-09-28T17:39:00.000-07:00

A favorite xkcd cartoon and some things that will never be.

A Unicode book that is both concise and useful
A protocol with "Simple" in its title that has remained simple - SNMP, SMTP, SDLIP are just a few that have not.
Revision control merges with absolutely no conflicts

~Matt

Appearances and Expectations

2010-09-24T09:24:00.000-07:00

I've found that a spaghetti server is a great tool for scratching my back. We have one in the kitchen for food and different one on a shelf elsewhere. Of course, children like to copy their parents so 6 year-old Luke scratches his back just like his Dad, which I find rather endearing.

But sitting at the dinner table a few nights ago, he went very quiet, his eyes widened and asked "Dad, why is your back scratcher in the pasta?".

Just because two things look the same, they aren't necessarily the same.

Jobs that I have more respect for, the more I see of them

2010-09-20T17:28:00.000-07:00

Statisticians

99% of everything written about statistics is wrong, including this. So when people really do understand how to set up proper clinical trials or fit their data to useful distributions, I'm impressed. What most of us learned in school and university really wasn't enough to understand the traps for the unwary and naive in this area.

Statisticians also get to use some great words like homoscedasticity and kurtosis.

~Matt

Here comes AtlasCamp 2010!

2010-09-16T12:26:00.000-07:00

If you develop or maintain Atlassian products (JIRA, Confluence, etc), this event is a great place to be (October 11th - 13th, California, $200).

I'm looking forward to it again with a relish I rarely find for many group events.

http://www.atlascamp.com

JIRA articles are now at jiradev.blogspot.com

2010-09-15T13:31:00.000-07:00

I've started a new blog for JIRA-related posts over at jiradev.blogspot.com. Future technical JIRA content will appear there instead of in this blog

~Matt

My Review of Practical Development Environments

2010-09-01T11:27:00.001-07:00

Originally submitted at O'Reilly

Everyone wants a good technical environment for developing their software, and Practical Development Environments contains helpful guidelines for how to create and maintain a great development environment. It discusses some of the current tools that are available, covering different areas...

Good advice, tools sections dated now

By Matt Doar from San Jose, CA on 9/1/2010

Pros: Concise, Well-written, Accurate

Cons: Partly outdated

Best Uses: Intermediate, Toolsmith, Novice

Describe Yourself: Consultant, Sys Admin, Developer, Author, Toolsmith

I'm the author and the book still works as intended. Each chapter has a section on using software development tools (version control, builds, bug trackers etc). The second half of each chapter refers to tools in each area that were current five years ago, so these parts have aged correctly.

I've run a consulting business for the past four years based around many of the ideas in this book and find that, for the most part, they are working well for my clients.

~Matt

(legalese)

Action, Expectation, Observation

2010-09-01T11:04:00.000-07:00

I remember writing some parts of Practical Development Environments vividly, despite the sleep deprivation that writing a book and having a new child will produce. One such section summarizes what goes into a good bug report:

The three key points to bear in mind when creating a bug report should be:

How to reproduce the bug, as precisely as possible, and how often this will make the bug appear

What should have happened, at least in your opinion

What actually happened, or at least as much information as you have recorded

I still like what I wrote. And now I think it's good advice for other situations. For example,

Action: I was taking my brother's toy from him. It was his new toy.

Expectation: He should have let me take it because he wasn't using it anymore

Observation: He hit me!

Maybe I'll get it printed on my next batch of business cards:
Action, Expectation, Observation.

~Matt

Distribution of Scrabble word scores

2010-08-18T18:27:00.000-07:00

If you take each word in /usr/share/dict/words (OSX 10.5) that is 7 letters or fewer and can be created with the standard set of Scrabble letters, and calculate its simple value in Scrabble, then the histogram of the data looks like this.


1 | 10
2 | 52
3  | 240
4       | 753
5             | 1541
6                         | 3061
7                                       | 4744
8                                                   | 6220
9                                                             | 7462
10                                                         | 7043
11                                                    | 6439
12                                           | 5276
13                                 | 4061
14                        | 2959
15                 | 2078
16              | 1713
17        | 979
18      | 714
19    | 414
20   | 255
21  | 171
22 | 90
23 | 47
24 | 32
25 | 22
26 | 5
27 | 6
28 | 3
29 | 1

The most valuable word? "jackbox".

Marking ALL mail in gmail as read

2010-08-17T11:47:00.001-07:00

To mark all Google mail as read without having to page through lots of old messages

1. In the search box, type "is:unread", no quotes
2. In the dropdown that looks like a checkbox (yes, it does) select "All"
3. A link will magically appear that says "Select all conversations that match this search". When clicked, it selects all the messages that are not shown as well as the ones that are shown.
4. Finally, select "Mark All as Read" from wherever it is for you and wait a few minutes.

(via http://www.woodwardweb.com/technology/marking_all_mai.html)

It turns out that the search doesn't select messages in your Drafts folder.

~Matt

A fine and confusing error message from Java

2010-08-16T15:56:00.001-07:00


public String myFirstMethod() {
    String result = "Hello world";
    return result;;
}

A straightforward piece of code that rudely produces a compile-time error "unreachable statement at line 3". "What's so unreachable about that line?" you might ask. Those experienced in the way of Java compilers simply smile and point out the double semi-colon. Accordingly to the compiler, there is an (empty) Java statement between the two semi-colons and it is never reached because the methods always returns before it reaches it.

If I had written writing that error messages, I might have made it say "double semi-colon on line 3".

What price is a company's reputation worth? Answer: $4600

2010-08-12T16:56:00.001-07:00

A reputation once broken may possibly be repaired, but the world will always keep their eyes on the spot where the crack was.
- Joseph Hall

I've been lucky for the last four years as a consultant to not have any major problems with getting paid. So the story of the first client to behave really badly is worth telling.

Back in January 2010 I contracted with an organisation to do $12,000 worth of consulting work for them over the next few months. After two months I sent an intermediate invoice for $9,600 for the work completed so far. Around then the organisation decided due to a strategy change that they no longer wanted the work that I was doing. So they simply went quiet on me and wouldn't acknowledge any email or phone calls. I didn't know what was going on, just got a bit annoyed at the late payment and lack of communication.

Last week I dropped by their offices to sort this out. I received a rather chilly reception and was offered $5,000 as a final payment. Fed up with the five month delay and their lack of communication, I took the offer.

So I lost $4,600, and they lost all my trust and respect. When future clients ask me about that particular organisation's products, I'll probably say "tech is ok, but terrible business practices". Would I work for the same organization again? I'm a pragmatist so probably yes, but with 50% payment or more up-front.

Companies spend thousands of dollars on trade shows and advertising then throw the resulting gains away by treating another business badly. Crazy.

How irritated customers obey a power law

2010-07-02T15:34:00.000-07:00

There are over 4000 open issues about JIRA that people have voted for. The most popular vote has 592 votes but most issues have zero votes. I found a suprisingly good line to fit the data with a correlation coefficient 0.9882, if Excel is to be believed. I'm not sure that I actually believe in predicting what people vote for, but I guess this is one way of measuring your progress is how the coefficients of the predictor change over time. The flatter the line, the better job you are doing of evenly spreading out customers' irritation with your product.

As of July 2010, the coefficient of irriration for JIRA is -0.65.

ASCII art in log files and showing my age

2010-07-01T10:56:00.000-07:00

What is that? Well, let me tell you. It's supposed to be some ASCII art that my new-fangled JIRA bug tracker spits out into its log file at start up. It's supposed to serve some useful purpose. It fails (fails, I tell you) because when you view ASCII art that is longer than 80 characters in a terminal (this is a log file, remember) that text art just wraps around and resembles line noise. Yes, line noise like they used to have in the last century.

What's that? You think ASCII art is cool? Well so do I, in it's place. Which isn't my darn log files. What am I going to do about it? I'll tell you, I'll show 'em! Now get off my lawn.

My wife as a sea star

2010-06-25T13:35:00.000-07:00

Vacation Bible School ended today with the inimitable Banana Slug String Band. Katherine was their guest Sea Star. It opened up a whole new echinodermic side of her character to me. She certainly was moving around.

Drawing a line in the sand

2010-06-22T12:00:00.000-07:00

Joel Spolsky writing on his latest project concludes with

"Area 51 is not for everyone. If you don’t know what it’s for, or why it’s going to work, or you can’t figure it out, it’s not, actually for you."

Snark programmer, snark!

GNU license complexity

2010-06-17T11:47:00.001-07:00

The compatibility table at the GNU License FAQ makes my head swim. If this were for the different versions of an application, it would be taken out and shot.

I'll not spoil the punchline

2010-06-04T08:49:00.001-07:00

Too true.

From Geek and Poke

One Bug, Multiple Branches

2010-04-29T12:13:00.000-07:00

I enjoyed presenting and discussing some new ideas about how to use JIRA to track bugs in different branches along with their associated builds. This was all at the April San Francisco Atlassian User Group last night, kindly hosted by Atlassian.

My idea is to create a new issue type named "Build" and then create a new build issue for every build. Ordinary bugs in JIRA can then have regular JIRA links named "Present in Build" and "Absent from Build" connecting them to the specific builds in which they are found or fixed. The interesting part is that if you link the Build issues to other Build issues, you get a tree of related builds such as the diagram above that you can then use to deduce which bugs are present in any given release, and also which releases a given bug is likely to be in. Useful information that is rarely available in current issue trackers.

My presentation is available via Google Docs. Feedback welcome, as are beta testers for the ideas in JIRA.

Verification code for Empire Avenue: EAVB_KMCAYMVSLW

Software Engineering and Academia

2010-04-26T09:28:00.000-07:00

Bertrand Meyer has an excellent article about why academic computer science has a smaller impact than other academic disciplines do in their respective fields. As he puts it, "academic research has had its part, honorable but limited."

"Researchers in experimental physics or mechanical engineering employ technicians: often highly qualified personnel who help researchers set up the experiments and process results. In software engineering the equivalent would be programmers, software engineers, testers, technical writers; in the environments that I have seen, getting financing for such positions from a research agency is impossible."

"The only software we can produce, if we limit ourselves to official guidelines, is demo software. ... many of us work around the restrictions ... by spending considerable time away from research on programming and maintenance tasks that would be far more effectively handled by specialized personnel. The question indeed is efficiency."

For me, that's what a software toolsmith does.

How to change your OSX terminal color for ssh sessions

2010-04-08T14:28:00.000-07:00

Sometimes I have lots of terminal windows open for ssh sessions to multiple machines. It can all be a bit confusing even if I use the remote machine name in the shell prompt. So I got terminal colorization working for me with help from here and here.
There is a default color for all screens that are using ssh and you can also customize the colors for different remote machines. When you end the ssh session, the terminal returns to black on white.

This is for OS X because it uses the osascript command to change the colors but the rest of the shell script should be just fine for Unix.


$ cat /usr/local/bin/ssh
#!/bin/sh

# Color the OSX Terminal app according the hostname used in ssh
# Assumes you log in with a simple "ssh myuserid@remotehost"
# Place in a directory such as /usr/local/bin that is before the real ssh location

# The value of whatever was after the @ in the command
HOSTNAME=`echo $@ | sed s/.*@//`

set_bg () {
  osascript -e "tell application \"Terminal\" to set background color of window 1 to $1"
}

set_text () {
  osascript -e "tell application \"Terminal\" to set normal text color of window 1 to $1"
}

# Return to black text on white background
on_exit () {
    # echo exited
  set_bg "{65535,65535,65535}"
  set_text "{0, 0, 0}"
}
trap on_exit EXIT

# My color names
#  green   10000,40000,40000 
#  blue    10000,20000,60000 
#  orange  60000,40000,00000 
#  red     60000,00000,00000 
#  yellow  60000,60000,40000 

case $HOSTNAME in
  fisheye) set_bg "{60000,60000,40000}" ; set_text  "{0,0,0}" ;;
  jira|jira2) set_bg "{10000,40000,40000}" ; set_text  "{0,0,0}" ;;
# unused colors follow
#   blue) set_bg "{10000,20000,60000}" ; set_text  "{65535,65535,65535}" ;;
#  orange) set_bg "{60000,40000,00000}" ; set_text  "{0,0,0}" ;;
#  red) set_bg "{60000,00000,00000}" ; set_text  "{0,0,0}" ;;
#  yellow) set_bg "{60000,60000,40000}" ; set_text  "{0,0,0}" ;;
#  gray) set_bg "{60000,57000,55000}" ; set_text  "{0,0,0}" ;;
  *) set_bg "{60000,57000,55000}" ; set_text  "{0,0,0}" ;;
esac

/usr/bin/ssh "$@"

There's a way to do that in emacs

2010-03-31T14:33:00.000-07:00

Given a number of lines of text such as


foopy charlie
foo  bravo
food alpha

and you want to sort them by their second field so they end up like


food alpha
foo  bravo
foopy charlie

the right emacs incantation is:


C-u 2 M-x sort-fields

That's all.

Michelle Shocked concert

2010-03-29T09:19:00.001-07:00

Katherine and I went on our yearly pilgrimage to Moe's Alley to see Michelle Shocked last Saturday. Steve Wozniak was there too, quietly enjoying this tiny "Reggae Pub". As ever, Michelle was truly amazing. Her energy, her humility and that soaring voice. Mostly her older songs, but with lots of local guests and backing from a band lead by James Nash who just smoked that guitar!

As Michelle says of herself,

I've been through some dark times but I've experienced joy too. Now that joy can't be suppressed.

97 Things Every Programmer Should Know

2010-03-18T08:47:00.000-07:00

Another useful book in the "97 Things" series from O'Reilly has been published, this time for programmers. My contribution is "How To Use A Bug Tracker". There are more details at O'Reilly and Amazon.

This book was created by each person adding their contributions to a Wiki, where it was edited and discussed. The whole process worked really well due to the editor, Kevlin Henney.

p.s. My photo on the cover is four rows down, third from the left, just in case you're looking.

Ambiguity everywhere

2010-03-17T10:41:00.000-07:00

I use emacs for writing code, which is considered a bit old-school by many Java programmers. One of them recently commented that "watching someone use emacs is like watching ballet". Was that a compliment or not? "Graceful" and "efficient" come to mind, but maybe he just doesn't like watching ballet.

One of those mornings

2010-03-10T10:19:00.000-08:00

6am. Our eldest child woke me from my slumbers with "Daaaad, the toilet's overflowed!". Turns out it had thoroughly clogged itself late last night and then a leaky tank valve had allowed water to gradually drip into the bowl overnight. Ugg. However, the rather questionable design of many American low-flush toilets is not the point of this post. In the process of clearing the clog I realized that this was where an education comes in useful. I asked her to flush another toilet in the house which created a partial vacuum in the sewer line and helped my efforts with the plunger. It worked wonderfully! A discussion of the physics involved ensued, but the best bit was seeing my daughter continue to believe that her Dad could fix anything.

Which letters are never doubled in English words?

2009-12-23T12:55:00.000-08:00

There is now a handy website for searching an English dictionary using regular expressions. It appears that the only letters that are never doubled are 'j', 'q', and 'x'. Mind you, you have to go to Uzbekistan to get their unit of currency which is named a "tyyn".

Perhaps I should make up a word such as "sajjaqquixx" to fix the missing ones. I'm not sure what it means yet, and neither is Google. Suggestions welcome.

Happy Christmas,

~Matt

Testing, testing

2009-12-08T18:16:00.000-08:00

This log post should also appear on my Facebook page, along with a picture of our house as it was in 1948.

Christmas book ideas

2009-11-19T09:17:00.000-08:00

I've recently read two different graphic novels that I've been very impressed by. I recommend both of them for smart teens and older.

Logicomix, Apostolos Doxiadis and Christos Papadimitriou

The story of Bertrand Russell and his mathematical (and other) passions. An entertaining story with enough of the history of logic to make me think. Beautiful art of Athens too.

Grandville, Bryan Talbot

A well-written steampunk detective story using animals. But it's more than that, lots of references to all sorts of interesting things and people. The art is captivating and left me wanting more of it.

BitBake and reusing existing ipkg files

2009-10-27T16:44:00.001-07:00

I've spent a few days helping a customer with BitBake, a python-based build tool for embedded systems. One of the distributions that uses BitBake is OpenEmbedded, a "build-every-single-thing-from-source" Linux distro.

The customer had a number of existing ipkg packages and wanted to add them to the BitBake'd image. That turns out to be an undocumented use case, so here's the information to save other people the time we spent.

For a target architecture of armv5te, the recipe file for a package with an ipkg file named mypackage-1.2.0.3-1_armv5te.ipk looks like the code below.


DESCRIPTION = "My Package"
DEPENDS = ""
LICENSE = "GPL"

PN = "mypackage"
PV = "1.2.0.3"
PR = "1"
PACKAGES = "${PN}"

# Just fetch and place the ipkg in the correct place to build the rootfs.

# As used in openembedded/classes/image.bbclass via rootfs_ipk.bbclass
PACKAGE_INSTALL_append = ${DEPLOY_DIR_IPK}/armv5te/${P}_armv5te.ipk

SRC_URI = "\
  http://ipkg-repository.example.com/subdir/${P}_armv5te.ipk \
  "

do_unpack() {
  echo "Null unpack method"
}

do_patch() {
  echo "Null patch method"
}

do_configure() {
  echo "Null configure method"
}

do_compile() {
  echo "Null compile method"
}

do_stage() {
  echo "Null stage method"
}

do_install() {
  oenote Creating directory ${WORKDIR}/install/${PN}
  # A directory is needed for each member of PACKAGES
  mkdir -p ${WORKDIR}/install/${PN}
}

do_package() {
  echo "Null package method"
}

do_package_stage() {
  echo "Null package_stage method"
}

do_distribute_sources() {
  echo "Null distribute_sources method"
}

do_package_write() {
  oenote Copying the downloaded ipkg package from ${DL_DIR} to\
 ${DEPLOY_DIR_IPK}/armv5te
  install ${DL_DIR}/${P}_armv5te.ipk ${DEPLOY_DIR_IPK}/armv5te
}

Version: BitBake 1.8.3

It doesn't look like much by itself, but the work behind it was, er, significant. BitBake and OpenEmbedded have a good number of layers, moderate documentation and great power.

Other tips:

Don't execute BitBake in a subdirectory or it will rebuild the world in a new tmp directory there.

OpenEmbedded apparently doesn't check the return code from the ipkg install commands, so if your files aren't appearing in your image (rootfs) directory, then check their dependencies or run the explicit ipkg command that can be found in the relevant run* command file.

If ipkg asks for user input about overwriting a configuration file, then the OpenEmbedded do_rootfs() function will hang and you will need to kill both the ipkg and bitbake commands manually.

See http://bec-systems.com/web/content/view/79/9/ for more information about adding new packages to images.

There's no such thing as a unique name

2009-10-15T15:11:00.001-07:00

Reading an old post by James Clark about Thai personal names, I wondered how many different names I am addressed by. Surprisingly, I came up with eight.

John Matthew Simon Doar (birth certificate)
Matthew Doar (school name, birth family usage)
Matt Doar (work name)
Matthew Baginski Doar (family name after marriage)
Matthew B. Doar (shortened family name used for publications)
Matthew Baginski (used by systems that can't handle two words in a family name)
J. Matthew Doar (occasional form letters)

and strangest of all is the U.S. Immigration Service who refer to me as "John M. Doar" and once forced me to make up a signature for it on the spot! All I really want these days is to be unique enough for Google.

Handling large numbers of JIRA projects

2009-10-09T12:39:00.000-07:00

Once you have a large number of projects in JIRA creating an issue can become a bit tedious, scrolling through the long list of projects to choose just the right one. JIRA (Enterprise edition) already provides Project Categories that you can group projects into, so without further ado, here's a JSP hack to reduce the size of that list of projects by letting you select a project category first.

Installation

The modified file for JIRA 3.13 is createissue-start.jsp and replaces the file of the same name in your JIRA instance. There should be no need to restart JIRA. The usual disclaimers apply, drink responsibly, don't drive and derive etc.

My first build tool question

2009-10-09T12:21:00.000-07:00

gnu.misc.discuss

The post above from me in August 1994 asking for help with gnumake reminds me that I never did learn how to use a build tool in college. Fifteen years later, I still don't know the answer to the question that I asked, but I do know that make is still not my favourite build tool.

Still, at least the books about Make have improved with John Graham-Cumming's GNU Make Unleashed and Robert Mecklenburg's Managing Projects with GNU Make, Third Edition. That "Third Edition" part is important.

~Matt

Should you go to AtlasCamp? Hint: yes!

2009-09-23T10:31:00.000-07:00

This post is a friendly sales job for AtlasCamp, the Atlassian developers get-together that's happening October 21-23 in Half Moon Bay, California.

Cons

- Costs a bit of money this year ($200 instead of free)
- er ...
- that's it!

Pros

+ If your company depends on JIRA or Confluence and you've changed them somehow, this is the best place I've found for technical questions
+ Friendly people who write useful code at this conference, not just vapid schmoozing
+ Good presentations about what's changing in the products you depend on
+ Plenty of opportunities to tell the core Atlassian developers and top management exactly what you think of their products

See you there.

~Matt

She found it 13 years later

2009-09-03T10:41:00.000-07:00

Some stuff from old web pages when "Lizi", aka Elizabeth Shardon Baginski Doar, was first born. And indeed she did find them, all by herself, just the other day. I'm not sure she exactly loved it, but it was certainly a surprise!

I was born October 14th 1996 and am much loved by my parents. I like not sitting still and asking "why?". Below is an excerpt from my first email.


>fuukyiki7z x z>8jlj .l[
>'00 uyjkklglylewl;ghju7j

An interesting graph of contraction times during our daughter's birth. I think she'll love this page one day.

Does this bug tracker make me look whiny?

2009-08-27T17:22:00.000-07:00

I submitted a bug about JIRA to Atlassian recently and wondered who reported most of the bugs in their very public database. No surprise, about half of the ones in the last year are from Atlassian employees.

Over the last three years, it's a tie between Neal Applebaum and Sergiy Lizenko (ILS-Ukraine) who each submitted 81 issues, and myself trailing in third place with 39 issues.

~Matt

AtlasCamp 2009

2009-08-04T11:35:00.000-07:00

AtlasCamp is back, and it's moved to Half Moon Bay. It also costs something this year, but after the great time I had last year I'm looking forward to it.

Python Unicode oddness

2009-07-22T15:11:00.000-07:00

If you have a Python string with an invalid character for the current character set, then other characters may get removed unexpectedly. For instance:


>>> a = 'FOO\xe0BAR'
>>> print '%r' % a
'FOO\xe0BAR'

>>> print '%r' % unicode(a, 'utf8')
Traceback (most recent call last):
 File "", line 1, in 
 File "/Library/Frameworks/Python.framework/Versions/2.5/lib/python2.5/encodings/utf_8.py", line 16, in decode
   return codecs.utf_8_decode(input, errors, True)
UnicodeDecodeError: 'utf8' codec can't decode bytes in position 3-5: invalid data

Fair enough, \xe0 isn't a valid utf8 character. But if I tell the decoder to just ignore any characters it doesn't understand, it also eats the "B" and "A" characters!


>>> print '%r' % unicode(a, 'utf8', 'replace')
u'FOO\ufffdR'
>>> print '%r' % unicode(a, 'utf8', 'ignore')
u'FOOR'

That was unexpected. One day I'm sure someone will explain why it happens to me.

Making it easier to maintain JIRA workflows

2009-07-01T16:43:00.001-07:00

This is one for JIRA admins.

I've had to track down a few problems recently that were related to fields not appearing on screens, especially when issues were changing their status. The cause turned out to be customized Transition Screens. A Transition Screen is the screen that is shown while you are moving from one status to another, and it's easy to forget which screen goes with each transition.

Sure, you can click on each transition and look for which screen is being used, or you can look at the list of screens and see which transitions used each screen. However, as the number of transitions and screens begins to grow, workflows become harder to maintain. The precision hack shown here helps with this. Click on the image to enlarge and look at the "Transitions" column. Each line has had the text "with the screen "added.

When you view any JIRA workflow with the "View Workflow Steps" screen, the transitions between steps (statuses) now have their screen information shown as well. At a glance, you can now look at a single workflow and see which of your transitions have those troublesome custom transition screens.

The file to change is

atlassian-jira/secure/admin/views/workflow/viewworkflowsteps.jsp

and the modified version can be found here. This was tested with JIRA 3.13.2 and is also a good example of what you can do with JSP if you have to.

Remedy - free the attachments!

2009-06-23T10:27:00.000-07:00

I've inspected a lot of issue tracking databases in the last few months - JIRA, Bugzilla, TeamTrack, ClearQuest, Trac, GNATS and Remedy¹ - but the one I want to consider in this post is Remedy (a.k.a. the "Remedy Action Request System", part of BMC Remedy Service Management from BMC).

Remedy stores attached files in the database and compresses them to save space. That's fine, and they provide a compiled API library to talk to the running server application and extract and decompress the files. But if you're trying to get the data straight from the database, you're out of luck. Searching suggests that the file compression is some proprietary form of zlib but that's it. No source, no algorithm, nothing!

If you're providing an API to extract the data, why not show the customers the source? I suppose they might want to hide changes in the compression algorithm from users, but I can handle seeing that. I'm all for using carefully constructed APIs but not at the cost of the data being locked into one database.

¹ I know, I know, you're thinking "wow, those toolsmiths sure do live life in the large!"

I found a bolt-hole

2009-04-29T12:39:00.000-07:00

I finally rented an office near home. The main things I needed were:

* an internet connection
* reasonable airconditioning and heating
* peace and quiet

The last item is why working at home isn't always as easy as one might imagine. And it's not just the kids!

~Matt

Names for Bug States

2009-04-01T10:06:00.000-07:00

There is an interesting discussion going on over in a Bugzilla group about changing the default workflow (Open, Fixed, Closed etc) that comes with Bugzilla. My thoughts are that whatever they choose, everyone will want to change it to match their own thoughts on what states a bug should have.

What is really needed are some state names to guide users on how to use a workflow. So in the spirit of the day, I propose doing away with those vague and language-specific words such as "Open" and "Closed" and using integers instead. The first state that a bug starts in would be 0 (or perhaps 1 for non-engineering groups), then the next state should be 1, and then 2, and so on. Next, remove all transitions between states except to the next state and the possibly the previous state.

We now have a simple measure of the state of a bug, acceptable to all!

Tracking Those Personal Issues

2009-03-26T09:55:00.000-07:00

Geek Hero Comic

I suspect that some people use bug trackers for even odder things. JIRA has a personal license for just those sort of, well, personal, things.

I'm off to the summit!

2009-03-20T10:37:00.001-07:00

I went to the San Jose Atlassian User Group yesterday in the San Jose Museum of Art (great place for a meeting). And I won the drawing for a ticket to the Atlassian Summit!

Hope to see you there.

Neat solution for CSS footers

2009-01-23T13:01:00.000-08:00

When navigating a website, it's a bit disconcerting to see the text at the bottom of the page moving up and down the screen as the amount of text on each screen changes.

There's a neat fix using CSS over at http://www.cssstickyfooter.com. It apparently works on every browser I could think of.

~Matt

JIRA Customization Guidelines

2008-11-08T10:30:00.000-08:00

These are a few slides written at AtlasCamp today. The slides contain some general guidelines for customizing JIRA.

Braille typos

2008-10-31T13:36:00.000-07:00

I was on Caltrain recently and noticed that the Braille for many of the signs must either have typos, or uses some other version of Braille than I've heard of. How can I tell? Well, the places where the same letter occurs have different symbols in each place. The picture above is of a similar sign, and I notice that it also has errors, though different from ones on Caltrain's signs.

Is this sort of thing common with Braille transliterations? Or perhaps this is Grade 2 Braille?

Can you see what I see?

2008-10-21T10:18:00.000-07:00

Can you see anything in the pattern of this image?

If you choose colors for a software application, then make sure you print out a screen-shot of every screen on a regular black and white printer. If you can't understand something from looking at the printout, then you've used only colors to indicate something, and this will be a problem for up to 10% of your target audience.

The image above is part of a reverse colorblindness test. The image embedded in it is supposedly only visible to color blind people. I can see a circle very clearly but it would obviously be foolish to rely on color-typical people being able to see it.

USS Pampanito is a Steampunk Submarine

2008-10-20T10:19:00.000-07:00

I had forgotten that the USS Pampanito was built at a time closer to Queen Victoria's reign than to today. Polished brass, great big chains, hydraulic lines and knobs everywhere!
There is also a great set of 360-views at http://www.maritime.org/tour/tatrvr.htm

Scientific Computing Survey

2008-10-16T16:32:00.000-07:00

-----------------------------------------------------------------
Interesting looking survey from Greg Wilson and others. If you're a scientist, I'd encourage you to add your information.

~Matt

Computers are as important to modern scientists as test tubes,
but we know surprisingly little about how scientists develop
and use software in their research. To find out, the University
of Toronto, Simula Research Laboratory, and the National Research
Council of Canada have launched an online survey in conjunction
with "American Scientist" magazine. If you have 20 minutes to take
part, please go to:

http://softwareresearch.ca/seg/SCS/scientific-computing-survey.html

Thanks in advance for your help!

Jo Hannay (Simula Research Laboratory)
Hans Petter Langtangen (Simula Research Laboratory)
Dietmar Pfahl (Simula Research Laboratory)
Janice Singer (National Research Council of Canada)
Greg Wilson (University of Toronto)

Preprocessor Warning Signs

2008-10-07T11:07:00.000-07:00

Using #if 0 makes searching hard

Some symbol is not defined so you grep for it and you find it in a file. But you've forgotten that you commented that part of the file out. So the symbol exists in the source but not in the .o file, leading to puzzled head-scratching. A better idea is to delete the unwanted lines since you can find them in your version control whenever you want them, and perhaps even leave a message about what they were.

Try this to see how many times you've done this:


[mdoar]$ find . -name \*.[ch] | xargs grep '#if 0' | wc

#ifdefs for unit tests mean that the code tested differs from the code used in the product

If #ifdef has to be used to make a function testable, then perhaps the function needs refactoring? If possible, use the build tool to create the tests, not the preprocessor. Some sample quotes at random from the web:

"I don't ever use ifdefs for unit testing because code should never know it's being unit tested."

"Tests must be non-invasive. I don't want to have to add #ifdef UNIT_TEST declarations into my production codebase as it'll end up making a mess and worse, could actually change behaviours. The framework and test code will be in an externally compiled project"

AtlasCamp

2008-09-09T10:07:00.000-07:00

So I've booked my place at AtlasCamp, Atlassian's first customer/developer love-in happening this November up in Marin County, CA. I'm not really sure what to expect except lots of product discussions, and I suspect a drink or two. Maybe we'll write some code, I don't know. I'm looking forward to it.

Anyway, if you're also going and would like to carpool from around San Jose, I'll have a couple of places in my car.

~Matt

Response to "What is it like to write a technical book?"

2008-06-17T10:31:00.000-07:00

This is a fair and honest summary by Baron Schwartz of what it's really like. I wrote a book (and proof-read it better than this post) in 2005 and probably won't get a chance to do it again ("at least not with this wife!" says my dearest).

What a well-established publisher brought to the table for me was a guaranteed outlet for the book, more marketing than I would have had the energy or time to do, and a US$6K advance. They also provided high-quality images, indexing and copy-editing.

There's a nice progress chart of my work shown above and here with the total word count and words/day over time. If I were ever to do it again, I would estimate an overall rate of 500 words/day requiring at least 200 7-hour sessions, so 1400 hours. For comparison, my 120-page doctoral thesis took about 4 months of 6 day weeks with 10 to 12 hours/day, so about 1000 hours.

Consulting is like waiting for a bus

2008-06-14T09:25:00.000-07:00

Every few weeks I am contacted by people wanting help with their development environments. This is a Good Thing for a consultant, but I've started to notice something very odd; the new contacts always come in groups, just like buses. I never get one new contact in a day, it's always either none, two or three.

Now this might be explained if I did more public talks, or groups of colleagues recommended me, but I haven't been able to spot a pattern yet. It's not related to the day of the week either, though I know the budget cycle in companies affects when consultants are hired and fired. Anyone got any ideas? I wondered about synchronization theory but it seems like a stretch.

Making Bugzilla Read-only

2008-05-28T13:51:00.000-07:00

I finally got this working after a few frustrating attempts. So, what not to do first.

Change database-level user permissions

I actually got this working once but it took three or four iterations since Bugzilla needs to be able to write to some tables to let you log in. Also, once you have messed with the permissions, I find restoring them to the prior state to be fiddly. This approach is really at the wrong level.

The editbugs group

There's a system level group in Bugzilla named "editbugs" that is apparently related to allowing a user to edit bugs. However removing a user from the group does nothing that I could see.

What Worked For Me

1. For each product, check the Closed checkbox so that the product does not appear in the list of products where bugs can be created. This effectively stops new bugs from being created, though perhaps using the right URL might still work.

2. Define a new group named something like "CanStillEdit" that can be used for bugs and add it to all products. Don't add anyone to the new group yet.

3. For each product, edit the group memberships at the end of the configuration page and set the "Can Edit" checkbox for just the CanStillEdit group. Leave all of the other groups unchanged. Now only members of the CanStillEdit group can edit bugs. It took a few passes through the documentation about this feature to see what they meant.

If all goes well then trying to save a change to a bug will produce a big red box with an error message in it. Usually the error message is helpful ("you do not have permission to do that"), but sometimes it says things like "you tried to update X from to 123" which is confusing but harmless. Search works just as before.

Other details:

1. The other settings for the groups I was working with were Shown/NA.
2. Administrators can also still edit issues.
3. All this is for Bugzilla 2.x - I would hope that there are better ways to do this in the latest versions.

Big Red Button as a Psych Test

2008-05-26T12:34:00.000-07:00

In a recent post Raymond Chen talks about Big Red Switches and various people weigh in with recollections about pressing such things. Well, I have in my possession a Big Red Button that I found at the excellent Triangle Machinery & Tool Co in San Jose. When I had a desk, I used to have it mounted with a thick cable running from it to under my desk. It wasn't connected to anything but it told me lots about the people around me.

Most people would ask "what's that for?" or "is it connected?", but occasionally there would be someone who would press the button and then ask the same questions. Those are the people you should never let into a server room!

Emacs, OS X and the EDITOR variable

2008-05-14T11:52:00.000-07:00

This took a bit of fiddling to get right, so I offer it up to the Great Google Index with the hope that it may save someone else some time. The EDITOR environment variable is what is used by Unix applications (such as Subversion and git) when they want to start an editor for input. Starting emacs from the command line in OS X uses the open command.

To get this working with emacs and OS X Leopard I had to make the file /usr/bin/emacs contain:

#!/bin/sh
open -nWa /Applications/Emacs.app/Contents/MacOS/Emacs "$@"

This opens a file using a new instance of emacs and waits until emacs exits.

Three Hard Lessons in Consulting

2008-05-14T08:41:00.000-07:00

1. Don't start the project until everything is ready. If a machine needs more memory to run the next version of an application, wait for the memory.

2. Stop working after the agreed period of time. It's better to disappoint a client and renegoiate than to surprise them with unexpected billable hours.

3. Windows infrastructure has a price. Locked directories, having to use Notepad, Wordpad or install Emacs, debugging complex service configurations: all of these things add up to about 25% more time taken during major tasks such as upgrades.

I'm officially and practically platform-independent in the services I provide. Linux, Unix, Windows, OS X, I do them all. But from now on I'm going to start charging different rates for Windows environments. Not a lot, just enough to offset the extra time and effort that they require.

My Dash Express

2008-05-02T10:39:00.000-07:00

Funnily enough, I'm not much a tech fan-boy. Generally what happens is that our friends are first adopters, and then we use their cast offs a few years later. I wrote a book on a discarded laptop and I watch films on a second-hand screen, while sitting on a pre-loved sofa. It's not just that I'm cheap, it's also a green thing.

So what on earth persuaded me to spend $400 last month on a new GPS, the Dash Express? That's just what my dearest wife wanted to know as well. Now, she has no use for such navigation devices having spent most of her life in the Bay Area. But now that I travel to different clients for work I was getting lost more often than seemed sensible, even for my relaxed approach to navigation.

The attractions of the Dash over other GPS systems for me are:

- GPS, cellphone and wifi antennae are all used. The GPS is for positioning, the cellphone for traffic information and internet connections while on the road, and wifi for updates at home
- I can right click on an address in a web page and send it to my car. No more typing on tiny screens. This is great.
- I can search while I'm on the road. For example, when I get near my destination I realize I have to park somewhere, so I can search for parking right then.

The downsides are:

- $10/month subscription fee, though the first three months are free
- Routing is slow and favors highways
- I had to screw a bracket onto my dash to secure it since CA doesn't allow anything to be mounted on the windscreen.

So far I've been happy with it, though I'm expecting great things from the first few software updates later this year. It has certainly saved me from some major blunders since I've been using it. And my wife refers to the Dash as my mistress!

Atlassian User Group, Palo Alto

2008-05-02T10:19:00.000-07:00

Well, I enjoyed the Atlassian User Group yesterday at Stanford. I'd forgotten just how complex getting a parking spot can be there, but I made it with only a few surprised comments from my new mistress. I gave a summary of my JIRA MultiSite post, but the things that I enjoyed most were:

- seeing what's coming up in JIRA 4.0 (nice work from Nick Menere and others)

- asking Mike (CEO) both technical and business questions and seeing him handle both well

- meeting lots of smart people using JIRA, with an eye to new clients of course.

The sponsors Stanford and WANdisco provided a good spread of food, which always helps such things. I'd recommend any JIRA administrators in the Bay Area come to the next one.

More bugs than revisions

2008-04-22T15:45:00.000-07:00

(Debian bug count from http://master.debian.org/~ajt)

Heard as an aside: "that project's got more bugs than revisions!"

Which made me think what kind of project might reasonably expect that statement to be true. The space shuttle software as a whole, perhaps? Lots of testing implies lots of bugs, and scrupulous code reviews means fewer commits.

At the other end of things, many small projects might get a few hundred revisions and then a few hundred bugs over time. Of course, most bugs will end up closed in one way or another.

Anybody able to point to a real project with more bugs than revisions?

Just costs you double

2008-04-16T16:44:00.000-07:00

Me: "just" costs you double.
Them: Huh?
Me: Every time you use "just" to describe a feature or a process it tells me you've made a gross assumption about what I'll need to do ...

That comment on a post titled All I Need Is A Programmer made me nod in agreement. "Just" is a warning sign in conversations for me, like "always", "never", and the dreaded "trust me".

All those phrases make me think of exceptions. "Always? Well, there is that edge case ...". "Just? Why 'just'? What about ..." and I begin to wonder whether the person really knows what they're talking about.

Just say 'no' to 'just'. (You knew that was coming, right?)

The Mac Mini as a Laptop and VMWare Fusion

2008-03-17T20:26:00.000-07:00

I needed a new laptop because the one I had borrowed had disk errors in the Windows registry, as disks do after too long running Windows. Since I find laptop screens, keyboards and mice uniformly awkward, I bought a laptop without the keyboard, mouse or screen - a Mac Mini. (Frys, US$750)

The upsides, apart from being less than half the price of a decent Mac laptop, are that it really is compact and there are some decent virtualization choices (Bootcamp, Parallels and Fusion). I went with VMWare Fusion and overall, it behaves as you might wish. Easy to install, cheap at $100 and runs most VMWare images.

The downsides of not buying a laptop are that power outages become more significant without a battery, and perhaps the disk drive isn't mounted in a suitable manner for carrying the box in a bag every day? Swapping from VM to VM, or VM to host OS sent the swap rate soaring, so I installed an extra 1GB of RAM to help with that. While installing the extra memory, I took a good look at the hard disk and it seems to be mounted just as it would be in a laptop, so I'm hoping that the disk will survive being moved every day. If anyones else has experience with mac mini hard disk lifetimes, I'd be interested to hear from you.

And so today, I had another "virtualization is great" moment. The server that I had traveled an hour to work on was busy having its motherboard replaced. Since I actually wanted to work on was the OS configuration, so I booted the Windows server image with Fusion on my little Mac Mini, did the necessary work, and moved right along. Very neat.

2008-02-26T09:35:00.000-08:00

The February issue of Python Magazine is out and contains my article "Using Python and SOAP to create a CLI for JIRA" about the Python CLI that I wrote for JIRA a while ago. The article's summary reads:

Many web applications include an API that lets you interact with them from the command line as well as with a browser. In this article, Matthew shows how to build a command line interface for JIRA, a well-known issue tracking system, using Python and SOAP. JIRA is a Java application, but using SOAP allows you access to many of its features using just Python.

One hint that I wish I had remembered to add is that when you have a redirect to your JIRA server, for instance when http://jira.mycompany.com is redirected by Apache or IIS to http://jira.mycompany.com:8080, you may see your login mysteriously fail. The answer is that you have to use the redirected URL with the JIRA CLI. You can find out what the redirected URL is by running the CLI with the argument -v10 to increase the logging verbosity and look at the line that starts with "Host". This example shows that the port to use is 8080.

*** Outgoing HTTP headers **********************************************
POST /rpc/soap/jirasoapservice-v2 HTTP/1.0
Host: localhost:8080

Finally, a use for those JIRA user properties

2008-02-20T17:28:00.000-08:00

One of the most useful JIRA plugins I've found is the JIRA Toolkit, described as "a bunch of neat custom fields Atlassian have developed for their own use". As an aside, if they're so neat and useful then why aren't they in the core product?

One of the more recently developed fields is the View User Property custom field, which is currently only documented in the issue that last link refers to. This handy little field allows you to display properties that you previously added to a user, as a read-only field in each issue.

For example, add a property named "Company" to some of your users in JIRA, then install the JIRA toolkit and create an instance of the View User Property field. Now configure it with "reporter:Company". Add the new field to some screens and the value of the reporter's Company field will show up in the issue. This also works with "assignee:Company". You can even get a user name with "My Custom Field:Company". This will use the user name found in the custom field named "My Custom Field". Just use the JIRA custom field name, including any spaces.

I've just used this to associate a company name with every customer user, and I'm sure there are a number of other pieces of per-user information that could be displayed with this field. One missing piece for this field is the ability to search for issues with particular values.

Evaluating JIRA Multisite

2008-02-14T09:57:00.000-08:00

Given the number of organizations already using JIRA across a WAN, there is plenty of interest in finding ways to improve the experience. I've had a few clients suggest using distributed databases, changing HTTP caching behaviour or not using HTTPS. None of these are really great fixes, and are complicated by the fact that JIRA keeps much of its data in a local Lucene index outside the database for performance reasons.

So when WANdisco announced a beta of JIRA Multisite last November in partnership with Atlassian, I was interested to see what it would do. It's billed as a high availability solution and in doing that it gives you local JIRA servers with all your data nicely synchronized. There is another approach that was announced at about the same time, the JIRA clustering solution Scarlet. I haven't evaluated Scarlet yet but it appears to have a single point of failure by default.

I contacted WANdisco to ask for an evaluation copy and they were happy to help. They have an existing replication tool for CVS and Subversion that they've connected to JIRA. You need their tool and their instance of JIRA. As an aside, though they are keeping up with each release of JIRA, I'd rather have instructions about how to modify my existing instance of JIRA to work with their tool, but I'll take what I can get for now.

To provide high availability you have to have 3 or more instances of JIRA, but since I was mainly interested in how each sites' performance changed, I just set up two instances of JIRA, one in San Jose, CA and the other in Bangalore, India. The connection between the two sites is a clogged T1 at best and the team in India often have sluggish response times from JIRA.

Setup Experience

WANdisco wanted to set the tool up, but I did it myself in an hour for the two nodes. Instructions were beta quality, but not bad. After that piece of stubbornness, their tech founder worked out what I had done wrong in about an hour, and then together we had it all working in another hour. Three hours from scratch is pretty good as these things go.

Testing

I modified a bug in San Jose and watched the change appear in India a second or two later. Then I modified a bug in India and saw the change locally in about the same time. Just as expected. Then we stopped one of the JIRA servers, made some changes, waited a bit, restarted the server and saw the changes all get synchronized. Other users updated issues over the next month and the changes appeared just as expected. The big win was that the users in India saw their local response improve dramatically. The underlying WANdisco replication tool was rock solid for the month's evaluation.

Restrictions

The version I tested didn't synchronize attachments, but that has been added since then. You do have to use the same OS (and database I believe) for all the instances of JIRA. This was not a problem for me, but if you have a Windows server in one location and Linux in another, it won't work.

I didn't try https, but I did set up LDAP authentication and that worked as expected

I'm pretty sure that if I wanted to go back to one instance of JIRA I could have exported the data and then reimported it into a non-multisite instance of JIRA.

Cost

Pricing is public and is US $7500 per instance of JIRA, which is about 50% more than the current Enterprise license cost. This seems about right given the cost of the tool and the target customers. Support comes from WANdisco and JIRA, in that order.

Summary

JIRA Multisite is still in its early stages, but it is very promising. It worked well for me with little effort, and provides good value for the price.

Perspective of a 3-year old

2007-11-28T10:46:00.000-08:00

A few choice observations from my youngest son in the past few months. I'm posting them as reminders that not everyone thinks as we expect them to.

During the minor earthquake in San Jose, we all went outside. Afterwards he kept running outside then back inside again. When asked why, he said he was "looking for more earthquakes." (I guess we found one outside the first time?)

We came across a dried-up deer carcass, and I was teaching him to use a stick instead of his hands to touch roadkill. This lead to a discussion about death and whether the deer would come back to life. I gently explained that the deer was done with its body now. He looked thoughtful for a moment, and then drove the stick through the carcass, exclaiming "you stay dead then!"

When asked during the Christmas Pageant rehearsal what kinds of animals were in the manager with Jesus, he piped up with "pterodactyls!". To his disappointment, he is going to be a lamb instead.

Choosing Project Names

2007-11-13T10:27:00.000-08:00

The discussion What' in a Project Name? over at Coding Horror reminded me of section 3.6.1 of my book Practical Development Environments:

Project names are usually chosen by engineering groups, with one name for each significantly different version of the products that they are working on. There should be no need to change a project's name once it has been chosen. Product names, on the other hand, are the names that customers see, and these names are usually chosen to help a product sell or to become popular. Product names can change at the whim of a market research poll or a new VP of Sales.

Some general guidelines for choosing names for projects are:

Keep it short

Since project names may appear in filenames or source code, shorter project names are preferable; four to six characters is common. Longer names will only be abbreviated anyway, and usually in two different ways.

Use distinctive sounds

Project names should sound different from each other when spoken aloud by people whose native language is not the one used by the rest of the group. Even if everyone speaks English, having two projects named "ctest" and "seebest" is too close for comfort.

Use low-frequency letters

It's much easier to be confident that all references to a project name can be found if the name contains characters that are less common in the local language. This is a good argument for choosing project names that use unusual characters, such as the letters q and z for English.

Apocryphal aside: a few years ago there was a project named IDS that apparently had a function named IDSConnect. Then the project was renamed DIS and all its functions were renamed accordingly, which led to their function for creating connections being renamed to DISConnect. The letters d, i, and s are too common in English to simply reuse them in
such an anagram.

Make it unmarketable

Sometimes a project name will be reused as a product name, but not if it is already trademarked, or if you make it odd or crude enough! Project names don't have to have a theme, though that can be fun. They don't even have to be meaningful, just memorable with an obvious way of pronouncing the word. You can choose a number of suitable names once and then let people decide which one they want to use next. Names of stars, types of sushi, rare diseases, and characters from comic books are some ideas to start with for project names.

Unexepected side effects in shell scripts

2007-10-10T13:29:00.000-07:00

Shell scripts that fail to preserve the expected environment are a waste of everyone's time. For instance, you call a function which changes the current directory to somewhere else for its own purposes but fails to change back on all exit paths from the function. Trying to remember which directory you might be in later on becomes combinatorially difficult as more conditional statements are added over time. To make it more concrete:

BAD:


function MyFunction() {
   cd some_random_directory
   # Do something useful
}

GOOD:


function MyFunction() {
   # Change to the necessary directory
   pushd some_random_directory

   # Do something useful

   # Now pop the directory off the stack    
   cd -
}

If you have conditional statements, then make sure you catch them too:

BAD:


function MyFunction() {
   # Change to the necessary directory
   pushd some_random_directory

   # Do something useful and test something
   if [ "${test}" == "value" ]; then
       return # Oops, this function left us somewhere unexpected
   fi

   # Now pop the directory off the stack    
   cd -
}

GOOD:


function MyFunction() {
   # Change to the necessary directory
   pushd some_random_directory

   # Do something useful and test something
   if [ "${test}" == "value" ]; then
       # Don't forget to pop the directory off the stack    
       cd -
       return
   fi

   # Now pop the directory off the stack    
   cd -
}

Basically, preserve an expected and known state between function calls, just like any modern other programming language.

Why tags are rarely used as you would expect

2007-10-09T08:34:00.000-07:00

As a recent introduction to version control explains, a tag is a way to record a snapshot of the state of some files at a moment in time. When I ask clients why they want to tag their source code, one reason is always "so we can reproduce a build later on". And we generally nod our heads and move on.

The funny thing is that I've never actually seen a tag used for that purpose. Tags do get used to decide whether a particular bug fix was in a certain build, or as references for released builds. But as a developer if I need an earlier build, it's probably to debug a customer problem, which means that the software was already released. Since my build process will have carefully preserved any build artifacts such as debug symbol files, I already have the files that I need.

The other observation is that build systems are designed to be able to use different branches. So if I really needed to recreate a build, I could always branch from the tag and then build using the head of the new branch. Of course, this assumes that nothing else in the environment has changed.

In summary, tags are necessary, but maybe it's not for the reasons that we usually assume.

Thoughts on Making Things

2007-10-09T08:13:00.000-07:00

It's time to get some thoughts out of my head about making things. Physical things, software things, relationship things. You know, things. That's what engineers do after all.

Nothing is Monolithic

Nothing created by people is a monolith. It's always made up of smaller things. Something may seem greater than the sum of its parts, but only by how we treat it. Really, it is just a number of things put together.
For instance, a beautiful painting may well move me greatly, but at one level it is still flecks of paint on canvas.

Everything is a Hack

"Hack" in the sense of changing a thing to work around a problem. Nothing created by humans springs fully formed into existence; everything is an extension of what came before. Whatever you see around you has taken multiple versions to become what it is now.

Everything looks different when you think about how it was made

This was an epiphany for me at eighteen, when I began to look around me and ask "how was that thing made?". Once you consider how a thing could have been produced, you understand that thing in a different way. And just as children are no less marvelous after you've read a book on reproductive science, software and hardware is still amazing even when you're the one creating it.

Python + bash + ssh = too many layers!

2007-10-03T17:41:00.000-07:00

I was reminded by a recent project that many (most?) hardware failures occur at the connections between things. That's why percussive maintenance gets results. I was writing a tool to execute lots of commands remotely on multiple machines, with the different commands being synchronized from one machine. I chose to write the tool in python, and that made creating it nice and easy.

But the shell commands to be executed had to be communicated to each machine. Now I could have written all the commands and their arguments (some of which contained the dreaded spaces) into separate files, copied them over with scp and executed them remotely. Except that there was a fair amount of analyzing of results and deciding what to run next based on the results of the analysis. This is generally tedious to do with bash and can be hard to maintain.

So I decided to keep the control logic in the python tool and use ssh to send each command separately to the remote machines. Which works, but the extra headache of getting all the spaces escaped and quoted added a major amount of maintenance pain to the tool. I could have encapsulated it all more cleanly, I'm sure, but it all "just grew" in scope and size.

The final block in this tottering tower was that some of the commands had to be run using sudo, but not all of them. Getting all those sudo strings in the right place took a few hours of my life from me without feeling that I got much for it. So it goes.

I've tried using CORBA, WebServices etc over the years, but they feel pretty heavyweight for this sort of thing. So the question I'm asking myself is: how could I have done it better?

JDiff 1.1.0 released

2007-09-03T15:19:00.000-07:00

I finally got around to incorporating a few patches into a release for JDiff, the Java doclet I wrote years ago to generate Javadoc-like reports about the changes between two versions of a Java API. I still think it's a cool tool, in my opinion. And in the opinion of Apple, Oracle and Sun too.

I took the opportunity to rearrange all the source files to make it easier to work on, and combined all the Ant files into one big build.xml file. I noticed when I was updating the documentation that I had to tell some Java developers what Ant was in 2001, which is not the case now. I'm still trying to wrestle the repository into Subversion in SourceForge.

Scott McCloud at Hijinx Comics

2007-08-21T10:24:00.000-07:00

I had a great time last night hanging out with my son Jacob (8) at our local comic store Hijinx Comics with Scott McCloud, his family and a bunch of other locals in the know. Scott McCloud is probably the most self-aware and thoughtful person creating comics at the moment. I liken the year-long tour he is just finishing to a professor travelling the world to spread his knowledge. His original book Understanding Comics has been worth re-reading every few years - it's one of those books, like Edward Tufte's. Any kind of collaboration between them would be an amazing thing to behold.

The other thing we really enjoyed was his family being there. Jacob was amazed to find any girl who liked Pokemon as much as he does, and Scott's wife Ivy is also a great presence in any room. Many thanks to Dan Shahin for organizing the get-together.

Atlassian has acquired Cenqua

2007-08-01T17:21:00.000-07:00

Which is not surprising, given how many of my customers use both Jira for bugtracking and FishEye as a front-end browser for their version control. What's funny to me is that I suggested it to Scott Farquhar, the CEO of Atlassian last month at the Silicon Valley Atlassian User Group meeting, but I didn't pick up on why he looked a bit surprised by my suggestion that "hey, y'know, Atlassian should buy those FishEye guys!". Next time, I'll just ask if he wants to play poker.

No word on the terms of the deal, but from my perspective, it's great news. Best wishes to all involved.

The largest, longest-lasting hack ever?

2007-07-27T09:10:00.000-07:00

Hack, in the sense of "workaround", created by humans, elegant or not, and not restricted to computing.

My current contender is upper and lower case letters in English. It's like mixing two fonts in the same document. If scribes and early printers wanted ways to break up text, making different shapes for the same letters is an odd way to do it. Maybe space constraints were their real problem?

And what about double quotes? Someone came up with the idea of using a small mark before and after a word or phrase to set apart. Then someone else decided to just use the same marks twice. I'm surprised we haven't seen triple and quad quotes appear over the centuries.

What's your vote for the longest-living and largest hack in the history of humanity?

Useful "FishEye for Jira" plugin

2007-07-25T13:56:00.000-07:00

Jira is easy to integrate with CVS and Subversion, but there's a FishEye for Jira plugin that can give you even better integration. If you are using FishEye (think ViewVC on steroids, plus change logs) as a front-end to your CVS or Subversion repositories, you should definitely investigate this plugin.

The screenshot below shows how the plugin replaces the Commit tab in Jira with a new FishEye tab.

Why is this a better approach?

The default mechanism used by Jira to connect issues to commits is by looking for issue identifiers in commit messages. For example, a commit with the message "Fixing TST-1234 again" is probably referring to the issue TST-1234. So far, so good.

The problem is that getting this information from CVS and tracking ongoing changes involves running "cvs log" and parsing the output. I recently came across one such file that was 90MB and took 10 minutes of churn to produce. Since the commit is only connected to the issue when this file is reparsed, there is often a sizable delay between making a commit and seeing it appear for the issue in Jira. Subversion integration with Jira is less of a load on the Subversion server, but still suffers from the same delay.

The FishEye plugin is much smarter than that. It uses the FishEye API to remotely query your FishEye instance each time that you refresh the FishEye tab of an issue inside Jira. FishEye has already indexed all the commits for its own purposes, so it can provide up-to-date results far faster than the out-of-the-box approach. Another benefit is that Jira no longer needs to load down the CVS server, or even contact the Subversion server.

Nitty Gritty

Installation is just like any other plugin, with some configuration in a .properties file. Remember to enable the API access in FishEye, and use the same names for repositories in the configuration file that you used when defining them in FishEye.

Priority Inflation

2007-07-18T09:04:00.001-07:00

In most companies and projects, limited resources mean that as the ship date for a release approaches, only bugs with Priority 1 and 2 get fixed; the others are closed or deferred. Over time this practice leads to priority inflation. Someone entering a bug knows that this bug won't stop the product, but she remembers that none of her Priority 3 bugs got fixed last time and she really wants this one fixed, so she makes it a Priority 2. In the extreme, by a process of induction, all bugs become Priority 1 bugs and the purpose of the field is lost.

There's not much you can do about this except be aware of it happening and remind people what the priority fields are actually for.

The Lack of Difference between Priority, Severity, and Urgency

2007-07-18T08:09:00.000-07:00

Chapter 7 of Practical Development Environment discusses tracking bugs. This article expands on ideas about bug priorities from there. The short version is "life is simpler if you rename all your priority fields to show who cares about one."

The strip is from Hans Bjordahl's very funny Bug Bash site.

Priority, Severity, Urgency, ... huh?

Most bugs have a field to indicate how serious the bug is. A common series of values goes something like this:

1 - The bug stops the product, and no workaround is possible
2 - The bug stops the product, but a workaround is possible
3 - The bug breaks a minor part of the product
4 - The bug is cosmetic or an irritation

To make this field useful, you have to make it really easy for users to find out what each value is supposed to mean, right when they are entering the bug. Some people expect higher values to mean that the bug is more important. Some bug trackers provide tiny little icons to confuse you still further because you can't remember what each icon means.

Where's that Thesaurus?

But there are more serious problems with this field in practice. The first problem is that English has a lot of words for some rather similar ideas. Quick, does "priority" mean the same as "importance"? What's the difference between "urgency" and "severity"? If English is not a user's first language, this makes using your bug tracker much harder work. Yes, the words do have specific meanings but if you have to stop and think about those meanings, then they're not good words to use. My suggestion is to pick one word and use it exclusively. I'm going to use "Priority" for the rest of this discussion, but you can choose your own favorite.

Priority for Who?

"But that's not right!"you mutter, "priority doesn't mean the same as urgency." Well, actually, I think it does, depending on who's priority we're referring to. For instance, the priority of a particular bug for the engineering team is a totally different thing from the priority of the very same bug for a Sales Engineer on site with a customer breathing down their neck. The different words usually mean priority for different groups of people. If they really do mean different things, then make it more obvious. For instance, use "Due Date" instead of "Urgency" to make the sense of time explicit.

My key suggestion is to have multiple priorities for a bug but name them per team. For example, the fields could be Development Priority, QA Priority, Support Priority, and so on. You can even have a "CFO Priority" for bugs that are stopping a contract being signed at the end of a quarter. That way, everyone gets to record which bugs really matter to them, and then they can work out which ones get worked on first. And as a side benefit, no-one gets offended when their favorite bug's priority is reduced to "Minor".

Of course, this approach means that the leaders of the teams involved in producing the product have to talk to each other regularly about what they actually want the teams to work on. Call me crazy, but that seems like a good idea to me.

Priorities that are set by Customers

One last thought: some companies allow customers to enter a priority when filing a bug. This usually becomes a "how irritated are you right now?" field. Which is useful data, but perhaps not what you originally expected to record in that field. However, when you change the value of the customer's Prioritity field, it's always a problem. If you increase the severity, the customer worries whether the problem is perhaps part of a bigger issue. If you decrease the severity, you appear to be minimizing his distress. If you provide this kind of field for customers, I suggest you allow them change the values themselves.

Unit Testing and the New Testament

2007-07-12T11:47:00.000-07:00

Taken out of context and not the intended meaning, but last Sunday it struck me that this reads like a quote from some article about unit testing:

"Each one should test his own actions. Then he can take pride in himself, without comparing himself to somebody else, for each one should carry his own load."

Galatians 6:4,5 (NIV)

Review: Beautiful Code

2007-07-11T09:10:00.000-07:00

Rating:

10/10 for all developers beyond their first project.
9/10 for beginners who may not see as much of the beauty yet.

Edited by longtime O'Reilly editor Andy Oram and pragmatic academic Greg Wilson, their new book Beautiful Code (O'Reilly, June 2007, 618 pages, US $44.99) is a collection of 33 chapters written by a number of people who have all written lots of ugly code, and then written some very beautiful code. Each chapter is a chance for them to describe the ideas and code that they feel stand out in a humdrum world of temporary workarounds that last forever.

The list of authors is impressive, including "K&R" Kernighan, "Pearls" Bentley, and many of the names behind some substantial modern software projects, but the first thing that I noticed about this book was lots of code snippets, in languages that range from Fortran to Python. And the code snippets are indeed beautifully formatted (with a good lay-flat binding). But in the end the beautiful code is included to make the ideas behind it all the more concrete, in which it surely succeeds.

The range of topics is the next obvious aspect, from writing a regex matcher, to what makes an API useful. I've included the whole list at the end of this review and you'll likely see something that catches your own interest.

Another theme of the book is that almost no-one gets it right first time, but just look at what can be done when you keep trying. As we hear in preschool, "the process is as important as the product", and watching any expert at work is always educational. This book describes experts' mistakes, their wrong paths, "aha!" moments and then their final successes with admirable honesty.

So how much of a developer do you have to be to appreciate this book? My guess is that you should have written a good-sized project, and then admitted to yourself that your creation was ugly. Only then can you see beauty by comparison. This book is destined to become a classic.

~Matt

Disclaimer: Greg Wilson reviewed my book Practical Development Environments in 2005, and O'Reilly sent me a copy of Beautiful Code for this review.

The book includes:

Chapter 1, A Regular Expression Matcher, by Brian Kernighan, shows how deep insight into a language and a problem can lead to a concise and elegant solution.

Chapter 2, Subversion's Delta Editor: Interface as Ontology, by Karl Fogel, starts with a well-chosen abstraction and demonstrates its unifying effects on the system's further development.

Chapter 3, The Most Beautiful Code I Never Wrote, by Jon Bentley, suggests how to measure a procedure without actually executing it.

Chapter 4, Finding Things, by Tim Bray, draws together many strands in Computer Science in an exploration of a problem that is fundamental to many computing tasks.

Chapter 5, Correct, Beautiful, Fast (In That Order): Lessons From Designing XML Verifiers, by Elliotte Rusty Harold, reconciles the often conflicting goals of thoroughness and good performance.

Chapter 6, Framework for Integrated Test: Beauty through Fragility, by Michael Feathers, presents an example that breaks the rules and achieves its own elegant solution.

Chapter 7, Beautiful Tests, by Alberto Savoia, shows how a broad, creative approach to testing can not only eliminate bugs but turn you into a better programmer.

Chapter 8, On-the-Fly Code Generation for Image Processing, by Charles Petzold, drops down a level to improve performance while maintaining portability.

Chapter 9, Top-Down Operator Precedence, by Douglas Crockford, revives an almost forgotten parsing technique and shows its new relevance to the popular JavaScript language.

Chapter 10, The Quest for an Accelerated Population Count, by Henry S. Warren, Jr., reveals the impact that some clever algorithms can have on even a seemingly simple problem.

Chapter 11, Secure Communication: The Technology of Freedom, by Ashish Gulhati, discusses the directed evolution of a secure messaging application that was designed to make sophisticated but often confusing cryptographic technology intuitively accessible to users.

Chapter 12, Growing Beautiful Code in BioPerl, by Lincoln Stein, shows how the combination of a flexible language and a custom-designed module can make it easy for people with modest programming skills to create powerful visualizations for their data.

Chapter 13, The Design of the Gene Sorter, by Jim Kent, combines simple building blocks to produce a robust and valuable tool for gene researchers.

Chapter 14, How Elegant Code Evolves With Hardware: The Case Of Gaussian Elimination, by Jack Dongarra and Piotr Luszczek, surveys the history of LINPACK and related major software packages, to show how assumptions must constantly be re-evaluated in the face of new computing architectures.

Chapter 15, The Long-Term Benefits of Beautiful Design, by Adam Kolawa, explains how attention to good design principles many decades ago helped CERN's widely used mathematical library (the predecessor of LINPACK) stand the test of time.

Chapter 16, The Linux Kernel Driver Model: The Benefits of Working Together, by Greg Kroah-Hartman, explains how many efforts by different collaborators to solve different problems led to the successful evolution of a complex, multithreaded system.

Chapter 17, Another Level of Indirection, by Diomidis Spinellis, shows how the flexibility and maintainability of the FreeBSD kernel is promoted by abstracting operations done in common by many drivers and filesystem modules.

Chapter 18, Python's Dictionary Implementation: Being All Things to All People, by Andrew Kuchling, explains how a careful design combined with accommodations for a few special cases allows a language feature to support many different uses.

Chapter 19, Multi-Dimensional Iterators in NumPy, by Travis E. Oliphant, takes you through the design steps that succeed in hiding complexity under a simple interface.

Chapter 20, A Highly Reliable Enterprise System for NASA's Mars Rover Mission, by Ronald Mak, uses industry standards, best practices, and Java technologies to meet the requirements of a NASA expedition where reliability cannot be in doubt.

Chapter 21, ERP5: Designing for Maximum Adaptability, by Rogerio Atem de Carvalho and Rafael Monnerat, shows how a powerful ERP system can be developed with free software tools and a flexible architecture.

Chapter 22, A Spoonful of Sewage, by Bryan Cantrill, lets the reader accompany the author through a hair-raising bug scare and a clever solution that violated expectations.

Chapter 23, Distributed Programming with MapReduce, by Jeff Dean and Sanjay Ghemawat, describes a system that provides an easy-to-use programming abstraction for large-scale distributed data processing at Google that automatically handles many difficult aspects of distributed computation, including automatic parallelization, load balancing, and failure handling.

Chapter 24, Beautiful Concurrency, by Simon Peyton Jones, removes much of the difficulty of parallel program through Software Transactional Memory, demonstrated here using Haskell.

Chapter 25, Syntactic Abstraction: The syntax-case Expander, by Kent Dybvig, shows how macros-a key feature of many languages and systems-can be protected in Scheme from producing erroneous output.

Chapter 26, Labor-Saving Architecture: An Object-Oriented Framework for Networked Software, by William Otte and Douglas C. Schmidt, applies a range of standard object-oriented design techniques, such as patterns and frameworks, to distributed logging to keep the system flexible and modular.

Chapter 27, Integrating Business Partners the RESTful Way, by Andrew Patzer, demonstrates a designer's respect for his programmers by matching the design of a B2B web service to its requirements.

Chapter 28, Beautiful Debugging, by Andreas Zeller, shows how a disciplined approach to validating code can reduce the time it takes to track down errors.

Chapter 29, Treating Code as an Essay, by Yukihiro Matsumoto, lays out some challenging principles that drove his design of the Ruby programming language, and that, by extension, will help produce better software in general.

Chapter 30, When a Button Is All That Connects You to the World, by Arun Mehta, takes you on a tour through the astounding interface design choices involved in a text editing system that allow people with severe motor disabilities, like Professor Stephen Hawking, to communicate via a computer.

Chapter 31, Emacspeak: The Complete Audio Desktop, by TV Raman, shows how Lisp's advice facility can be used with Emacs to address a general need-generating rich spoken output-that cuts across all aspects of the Emacs environment, without modifying the underlying source code of a large software system.

Chapter 32, Code in Motion, by Laura Wingerd and Christopher Seiwald, lists some simple rules that have unexpectedly strong impacts on programming accuracy.

Chapter 33, Writing Programs for "The Book," by Brian Hayes, explores the frustrations of solving a seemingly simple problem in computational geometry, and its surprising resolution.

Using computers in another way

2007-07-10T10:05:00.000-07:00

It seems to be the final destination for many machines - the doorstop. The lucky ones may become a foot rest or supports for the next generation of monitors. I'll have to bear that in mind next time I spend money on a machine - what else can I use that box for?

Field-level permissions in Jira

2007-07-06T09:45:00.000-07:00

Notice how the Fix Version/s field is read-only? This is something that many people have wanted for a while with Jira. I've posted a description of how I restricted who can edit individual fields on the wiki for Atlassian Jira. It doesn't handle the case of completely hiding a field from a group of people, but It Worked For Me.

~Matt

Writing an Effective Bug Report

2007-07-03T16:28:00.000-07:00

This is a short excerpt from Practical Development Environments and contains a number of useful links to other guidelines.

~Matt

The three key points to bear in mind when creating a bug report should be:

How to reproduce the bug, as precisely as possible, and how often this will make the bug appear
What should have happened, at least in your opinion
What actually happened, or at least as much information as you have recorded

Many applications can generate a textual description of how they have been installed and configured. If such a description is available, you should always add it to the bug. The application may also contain some tests to check that it is still configured correctly. If so, you should run the tests and attach their results too.

As well as providing correct and useful information in the bug, it's important to check that you behave as expected for the project. This is especially true for open source projects. Maybe you should ask questions first on a users' mailing list before escalating the issue to a developers' mailing list? Or you may mark a bug as maximum priority, because it's stopping your work, only to see it downgraded because no one else is blocked by that bug. Etiquette is important, and imperious commands to "fix this bug immediately" rarely help anything.

One common cause of frustration with bug tracking systems is related to how their information is added. Bugs are too often added with vague descriptions, missing information, premature conclusions, or a best guess at the real build label. A classic situation is when a complex program has a bug deep inside it, but the only error message that is visible is one from some unrelated area. That area often gets bugs from the deeper level assigned to it, much to the frustration of the developer responsible for it. Adding some good local documentation to wherever people add new bugs can go a long way to improving the quality of all the bugs.

Some useful documents with general advice about creating bugs include the Mozilla Project's Bug Writing Guidelines and Simon Tatham's How to Report Bugs Effectively. There are also many examples of more site-specific documents about writing bug reports; these contain product specific information such as descriptions of what each part of the product does. Two of these are Opera's Guidelines for Filing Good Bug Reports and FreeBSD's Writing FreeBSD Problem Reports.

Slightly off-topic, but also useful, is Eric S. Raymond and Rick Moen's classic article How to
Ask Questions the Smart Way. This document has some excellent reminders and strong opinions about how to interact well with groups of technical volunteers.

Using Jira for Test Tracking

2007-06-27T11:44:00.000-07:00

I'm giving a brief talk tomorrow on using Jira for Test Tracking at the first California Atlassian User Group tomorrow. More details on the user group may be found here.

(update: here are the slides and they're also attached to the Atlassian page)

On the Naming of Protocols

2007-06-19T10:23:00.000-07:00

Words to never use in your protocol name: "simple", "trivial", "lightweight", since the results never are.

Signs That You Are Not Comfortable With The Command Line

2007-06-19T10:07:00.000-07:00

Some signs that you aren't as comfortable as you could be when using a command line. Drawn from observations over twenty years at many companies.

Runs all over the Tennis Court

To see what's in a directory, you type:

cd  very/long/path
ls

or even worse

cd very
cd long
cd  path
ls

This is the easy way:

ls very/long/path

Drives With Accelerator, Brake, Accelerator, Brake, ...

You start an editor to look at a file, then quit the editor to list the directory, then start the editor to look at the file again. Repeat. At least bring up another window and edit the file from there. Or browse the directory from inside your editor.

Tells Jokes With Too Much Detail

You type every character in file or directory names. Autocompletion comes with almost every shell and will do the typing for you.

Never Takes Elevators

You move around the command line only with the arrow keys. Sometimes doesn't even hold them down for repeat but instead presses the desired key many, many times. Keboard shortcuts to move around and delete larger blocks of text such as words not used.

Word Doesn't Play Nicely With Code

2007-06-19T10:00:00.000-07:00

Don't cut and paste from Word or Outlook into Eclipse, Jira or any non-Windows application. Or if you do, then at least disable the smart-quotes stuff in Word How to disable smart quotes in word:

Tools, AutoCorrect Options, AutoCorrect - uncheck all correct and capitalize boxes
Tools, AutoCorrect Options, AutoFormat As You Type - uncheck all correct and capitalize boxes
Tools, AutoCorrect Options, AutoFormat - uncheck all correct and capitalize boxes

Windows applications use a character set that is not UTF-8, which is what is used by most browsers, editors, etc. This is usually not a problem since the Windows character set is mostly compatible, but if you have smart-anything enabled inWord (smart-quotes, auto-format etc) then character such as double quotes and hyphens get quietly converted into characters that look nicer on the screen but don't work in source code.

The following pipeline will tell you which Java files contain non-ASCII characters. These might be valid instances of non-ASCII characters, but they ought to be checked.

[mdoar@toolsdev Projects]$ find SystemServices/ -name "*.java" | xargs perl -nwe 'print "$ARGV\n" if /[^[:ascii:]]/'  | sort | uniq -c | sort -rn | more
19 SystemServices/src/java/com/packetmotion/sysservice/exception/SystemException.java
...

To see the line numbers in each file:

[mdoar@toolsdev Projects]$ find SystemServices/ -name "*.java" | xargs perl -nwe 'print "$ARGV:$.\n" if /[^[:ascii:]]/'

Some Different Approaches to Integration

2007-06-19T09:55:00.000-07:00

"Customers buy this as a single product, so think of it as a single product!"

The recommended approach if you want to make a change that you know will break other people's code (and it's your responsibility to test for that as far as possible), then you should communicate (not a one-way email) with the people involved and agree which of the methods below you are going to use to minimize disruption to the rest of the organization.

Example

Vivek wants to remove a method named getFunky() from a class used by the Client, and maybe by other components.

He makes his changes in his sandbox and checks that they work, then builds as much of the whole product as he can.
He notices that as expected he will break the Client
Just to make sure, he also looks at the Javadoc or uses Eclipse to identify other users of the method, and finds out that the Manager now uses getFunky too. Good thing he checked!
He communicates with two developers who are comfortable with changing the affected code in the Client and Manager, and together they decide how to make the necessary changes (see the choices below for some ideas)
Just to repeat the obvious - an email sent to a group and gets no responses is not communication, it's just a feeble excuse at teamwork. Integration requires two-way exchanges.
The changes are committed and life moves on.

No prizes for guessing that I don't think much of approach #2 (Break the Build), but if you decide to do this, make sure that you mail all-eng@example.com so that everyone else in the team is aware and isn't inconvenienced by the broken build.

Handy tip: your local address book may show who is in each email alias

Different Approaches

1. Don't remove the existing functionality, just add the new functionality

Pros: Nothing should break

Cons: Can be fiddly to get right, leads to overly complex code that eventually needs removing anyway

2. Check it in, break the build, and wait for other people to fix it

Pros: Quick and easy, for you at least.

Cons: Can bring development for the rest of the company to a halt. Not a career-enhancing approach if used too often.

3. Send out the changed files in email for people to develop against before you commit them

Pros: Simple

Cons: You may miss some, tedious for people to use. Generally, a bit 20th century.

4. Send out a patch for all the changed files

Pros: less likely to miss files, a bit easier to apply

Cons: harder to send multiple changes as multiple patches

5. Create a private branch, make your changes there, tell people which directories to use the branched version for.

Pros: Easier to continue working on your changes and for other people to accept them when ready

Cons: A bit more work to set up the branch in the first place