weblog.masukomi.org

Getting the most out of version control for hosted web apps. May 23, 2007

Another graph for another friend who asked for a flow chart of the branching and
merging described in Best Practices for Web Development
html
/
pdf.



Update:

Michael says: I’m a little unsure, from you diagram, how, if your
trunk contains two completed and merged features that aren’t yet live (video
upload and REST API, say) you put one feature live without putting the other
live.  It looks like code only gets to the live branch via the trunk, but
it seems from your diagram that the trunk could contain all manner of complete
and semi-complete features.

He’s right and I cover this in more
detail in my Best Practices For Web Developers Essay
html
/
pdf
, but the basic idea is this: Your dev trunk holds the bug fixes and features
you want to see in the next release. If, as in Michael’s example, you’ve got the
video upload written, but maybe you don’t have the hardware in place to support
storing and serving gigs upon gigs of uploaded videos, so you decide to hold off
on deploying that. So you leave it be in it’s little branch, remembering to
update it at least once a week until you’re ready to include it in the general
codebase.



Have you come up with a
better solution to Michael’s problem? Please let me know if you have.



—

I’m really not thrilled with this particular chart though. It’s got no
flow. If you can improve upon it please
do so and send me a copy. I’ve got some ideas but nothing great. I really liked
the
Using
Darcs with SVN / CVS flow chart much better.



As always you can click on the image for a full sized version and / or
download
the Dia file too.










This
work is
licensed under a
Creative
Commons Attribution-Share Alike 3.0 United States License.

Using Darcs with SVN / CVS Flow Chart

A flow chart for a friend demonstrating, step by step, how you’d go about using
Darcs (or any other distributed version control system) with SVN / CVS. He needs
to do it for the most common reasons:

1) it’s a pain to branch and merge with CVS.

2) he’d have to coordinate with other departments like QA to get them working
off of whatever the current release branch happened to be at the moment and
convince them that it was a good idea.

3) currently his co., like so many, is working off of a single development
trunk. There are no other branches.



Click on the image to get a full sized version. Or
download
the dia file here.










This
work is
licensed under a
Creative
Commons Attribution-Share Alike 3.0 United States License.



Some earlier related posts:

Why
you should be using a distributed source control system

Using
Darcs with Subversion / CVS

[Update] Related posts:

Using Darcs WITH Subversion / CVS

Why you should be using a distributed source control system

Why do we keep doing it?

NOTE: It’s a rant. Sorry, they happen. But I actually do try and make some good
points with this one.



Why do we keep doing it?



I’m writing an entire freaking book
because of that simple question. Why? Every developer I know is all “Unit tests
are great!” or “Separate branches for released code and development code,” or
“short iterations are the best way to do things…” BUT…



It’s always “But…”

“Yeah I should write some unit tests for those new features but I’ve got this
really pressing deadline….”



“We just had our release but we only have the development trunk so I need to be
really careful about what I check in now…”



“Well we don’t really have ‘iterations’ here…but it would be good if we did.”



Why do we keep doing it?



We know better” And yet we keep doing it.

What is it we fear?

What is it we’re avoiding?

What the FUCK is wrong with us?



I want to bang my head against the wall in frustration at the stupidities my
friends, who know so much better, keep perpetrating upon themselves, and then I
hold myself up to the same standards and have to bang again for my own
shortcomings.



What THE fuck is wrong with us?



Do we really think it’s easier or faster to write untested code? I hear that a
lot. “I’d write the tests but I have to get this done quick…” And yet, the
mere fact that you have to get it done quick means that you NEED the unit tests
even more because you’re rushing and thus your bug count
will go up, and we all know that it takes
longer to isolate, confirm, write a patch and manually test a bug than it would
have ever taken us to just write a unit test for the code in the first place.
I’m not naive enough to believe that unit tests catch all bugs but we all know
they dramatically decrease the number that escape into the wild.

In spite of the obvious need for [version control], many programmers
don’t use it. One survey found that over a third of programmers weren’t even
familiar with the idea. -
Steve McConnell

Version control is a bit trickier most of the time because there
are other people involved and you end up having to explain
why using multiple branches is good, when
you should branch and/or tag, when and where to merge, and how to actually
branch and merge in the piece of shit version control system you’re using.
Because unless the mechanics of branching and merging requires essentially zero
thought that version control system you’re using IS a piece of shit. Fuck your
Subversion and Fuck your CVS. Their crap-ass branching and merging tools are
leaving you and your coworkers fumbling around like idiots because you can’t
figure out how the hell to use the freaking tools you’ve been saddled with.
Maybe you thought they were good. Maybe they were there when you started. But
the fact of the matter is that if you’re not branching and merging your code for
every freaking code spike and every new release or major bug fix because it’s
too much of a pain then it’s a piece of shit and you should stop using it.



There. I said it.



ARRGh! And no, I’m not going to touch the fact that so many coders only use
version control because it’s company policy and don’t even know how to roll back
a simple change.



Why is it that I have to embark upon a journey of hundreds of pages of writing
to give you the tools and impetus you need to start doing the things you know
you should be doing already? That I know
I should be doing already…

I need to find some answer to this…. Because, until I do I can’t finish the
book. I don’t want it to be a collection of useful techniques for developers who
want to be more agile. I want it to help you drag yourself and your coworkers
out of the freaking malaise of crap coding techniques that we all practice. I
want to get us to take concrete steps towards actually doing things the way we
know we should be. Because THERE IS ABSOLUTELY NO EXCUSE FOR CONTINUING TO ACT
IN WAYS WE KNOW TO BE CRAP. None. Fuck your excuses.



Maybe that should be the title of the new book: “Fuck Your Excuses.” You think
Barnes & Noble would stick it on their shelves with that title?

Maybe I’ve been going about this all wrong. Maybe the world doesn’t need another
300 pages of sensible writing on why you should adopt these good development
practices. We already know WHY. Maybe what the world needs is a Bitch-Slap with
some practical tools for getting off your ass.

I don’t know if it would sell but it sounds wicked-fun to write.



And re the version control thing? I’ve already written two posts about it:

Why
you should be using a distributed source control system

Using
Darcs with Subversion / CVS (sometimes you have to work around crap systems)

And a GREAT BIG FREAKING ESSAY

Best Practices for Web Developers
html
/
pdf

…which also happens to be the foundation of the book I’m writing.



And on that note I’m going to bed. Sorry about the rant folks. I’m frustrated
that I keep seing smart people do stupid things and I’m even more frustrated
that I keep catching myself doing them too.

Why you should add to the FizzBuzz Overthink May 21, 2007

I was discussing
FBO with a
friend whose work I really respect, but all he could see was a contrived
over-thought solution to an inherently simple problem. And he’s right. You can
solve a simple FizzBuzz in roughly five lines of code in pretty much every
language. But, FBO goes a ways beyond solving a simple FizzBuzz.



FBO teaches:

• how to conceptually break a problem down into it’s component parts.
  
• how to implement classes and methods and the difference between them.
• how to throw exceptions and handle them when you encounter them.
• how to validate user entered data and prevent it from leaving your app in an
  invalid state.
  
• how to document your code.
• how to unit test your code.
• how correctly structured code, documentation, and unit tests should look in
  a given language.
• how various languages compare to each other.
  

FBO does all of this without forcing the user to think about business logic.
FizzBuzz is an inherently simple problem that doesn’t have to be dumbed down so
that the student can easily grasp it. In fact, instead of being dumbed down, FBO
has had complexity added to it to make it more representative of a real
application. It supports dynamic modification of the start and end points of the
game which means you have to safely validate, and handle user input in a
sensible manner. A student can grasp the problem right away and focus on HOW to
break it down into it’s conceptual pieces in the example language. Furthermore,
it’s abstract enough that students don’t end up wondering about the
implementation of the features that a Blog, or Car, or whatever thing you’re
using as an example would have if you hadn’t dumbed it down so much to make it
easy to grasp.



So please,
grab
the latest version of the FizzBuzz Overthink, translate it into your
favorite language and send me a patch at masukomi at masukomi dot org. It
doesn’t take long it’ll help some newbs ( wouldn’t this have been helpful for
you when you were a newb? ) and it’s a
fun little exercise. It’s also a great way to learn a new language.

FizzBuzz Overthink as a Teaching Aid

UPDATE: I’ve created a new subdomain for
the FizzBuzz Overthink project (
http://fbo.masukomi.org
), updated the links below to reference it instead and modified the Readme in
the project (and the default page of the site) to reflect the new goals of the
project.

UPDATE 2: There’s a JavaScript example in there now too which, of course, includes unit testing. More details here.

---

I was talking with someone the other day who mentioned, in passing, how they
wished they had some good examples of how to do unit tests for his co-workers.
There are, of course, plenty of examples of how to do unit tests but I haven’t
seen many online that show them in the context of a complete but simple
application. This conversation made me remember my
FizzBuzz
Overthink (FBO) that I’d written in Java, and it occoured to me that it
would make a great teaching application. Translating an existing FBO into a
language you’re trying to learn is also a great way to get your head around it.



The FBO demonstrates how to break down an application into useful methods, how
to write unit tests for those methods, and how to document them.



So, I’ve added a Perl version of the FBO, with docs and unit tests, although I
used
Natural
Docs for the documentation instead of standard POD because ND is just
light-years ahead of POD in my opinion. You can grab the new Java + Perl
versions
as
a zip file or better yet check it out with
darcs from
http://fbo.masukomi.org/code/FizzBuzzOverthink/
so that you can improve upon it and / or add your own language to it to help
make it a more useful teaching aid. Just use
darcs send to send me a patch with
your changes ( masukomi at masukomi dot org ). I think there are a lot of people
who would benefit from a PHP version and I’d personally love to see Haskell and
Erlang versions.

The Homosexual Agenda 2007 US Pocket Edition May 19, 2007

My Second Book is out!



As many of you know I helped co-author the
Professional
Java Tools for Extreme Programming book. Well, I am happy to report that

The
Homosexual Agenda 2007 US Pocket Edition is now available!

What’s even better is that it was written entirely by me!



Special thanks to everyone at Homosexual Agenda Press and the support of all the
H.A. members. We’re sorry about the delay in getting this out, obviously it was
supposed to be ready by January but, as you can guess, some printers are
hesitant to take on this project either because of their own religious beliefs
or fear of reprisal from the religious-right. So, we’d like to give a massive
shout-out to
Lulu.com.
Not only are they open-minded enough to help publish just about anything. This
year, because of the delay in getting this printed, we’ve decided to sell it
just barely above cost. We’re only making
$0.21 per book. We’re more concerned with getting this information out to every
H.A. member than making a profit off of it. Next year, we hope to pre-print a
number of copies to help reduce the price and get this up on Amazon &
B&N too. If we see a strong enough demand for this year’s copy we may take
the necessary steps to get it up on Amazon.com and B&N.



Thanks again to everyone who helped with the creation of this book. I love you
all and I am sooo proud of what we’ve accomplished!



P.S. We’re really going to need everyones help in getting the word out on
this since it obviously didn’t make it into this years H.A. catalog. Please pass
the link on to all your gay contacts.



Some links to help promote the books page on Lulu.com:


Digg

del.icio.us
Reddit

We’re raising money to buy a new ISBN number for this book, and do a small print run so that we can get put it up on Amazon.com. Every contribution helps. We’re hoping that everyone can contribute $30 or more but even five or ten dollars would help. If you’d like to see The Homosexual Agenda 2007 US Pocket Edition up on Amazon please help out at Pledgie:

Heuristically Driven Development Flow Chart May 18, 2007

This flow chart will only make superficial sense unless you’ve read
the
Triage section of my
Best
Practices for Web Developers essay, which I happen to have just updated with
an expanded Triage section.






Click on the thumbnail for the full-sized verison. If you’d like, the Dia file
is also available if you feel like tweaking it.

Failing to Address Time Scarcity May 16, 2007

I’ve started a near-complete rewrite of
TicketEverything!
[1] I need performance, bug fixes, and a refactoring of code to allow for easier
addition of new features and unit testing. The UI needs some improvements too.
But, I, like everyone else I know, have far more tasks on my plate than time to
do them. Pondering this problem I realized that there is a serious flaw in the
current time tracking application and agile methodologies: none of them address
time scarcity.



Time Tracking apps come in to the picture too late. They may be great at
tracking how much time you spent on a task but by then the time is already gone.
Whether you spent it on the appropriate task or not is moot at this point
because there are no “do overs”. Some Project Management apps let you put in
estimates and most Agile methodologies have techniques for tracking your past
development velocity so that you can better estimate your future velocity but
every Time Tracking and Project Management app that I have seen to date is based
on the flawed assumption that there is plenty of time. Sure they may allow you
to enter a “deadline” or “due date” and happily point out that the estimates for
your to-do items will go beyond your due date but that’s generally the extent of
it. And the agile methodologies just assume that if you don’t have time to do it
in this milestone you’ll just do it in an upcoming one. It’s like turning to a
person and saying “Your bills exceed your income this month but I’m not going to
help you decide which ones you would be better off paying now and which should
be put off without screwing you.”



When it comes to software development your to-do list almost universally
requires more time to complete than you have available. I can’t think of a real
project I’ve worked on where it didn’t and many would argue that the moment you
stop adding features to a piece of software is the moment you consign it to
being dead and / or obsolete. Most agile methodologies act as if the only
deadline is the next milestone. Scrum uses a
burn-down
chart but it’s ultimately misleading because it’s not really working towards
completion as it implies. It’s working towards some milestone and there is a
huge pile of other features for the next milestone that are conveniently
ignored.



Time is not unlimited. It is probable the scarcest resource in software
development. We need tools that help us choose where to spend our time.
ListfulThinking[2] is a good, although visually crude, first step towards this.
It prioritizes based on Internal and External Importance as well as Technical an
Creative Feasibility. In my experience those last two basically boil down to
time required. We need a system that will automatically prioritize our tasks for
us like it does but we need to take the next step and have it actually consider
the specific amounts of time required and available when prioritizing our tasks.



In short our tools and techniques need to evolve to allow us to prioritize our
task not only in terms of importance but in terms of time scarcity.



[1] After great deliberation I have decided to use Ruby on Rails for the rewrite
even though writing the exact same functionality in Django would probably give
me about a 2x speed boost (Python’s just that much faster than Ruby). In the end
it came down to plug-ins. Rails has them. Django doesn’t. The plug-in library
for Rails is going to save me countless hours of work and give my users more
features. It will take me less time to optimize my database usage and templates
than it would for me to manually code all the features I’ll be getting from
plug-ins, which I’d have to do if I used Django. Yes I considered TurboGears too
but it doesn’t have many plug-ins yet and Django still gives you more out of the
box functionality.



[2] Yes, ListfulThinking is crude. Yes it would be great to have a web based
version of it that was pretty and filled with Ajax goodness. And, yes, I’ve
actually have a working prototype of just that…But, I’ve got too many
higher-priority things on my plate to finish it in the limited time I have
available.

Please tell me your 80 / 20 rule(s). May 14, 2007

I’m reworking my Best Practices for Web Development
(html,
pdf
) essay into a full-fledged book with much more info and along the way the 80/20
rule, or Pareto Principle, has worked itself in. But, in thinking about it I’ve
realized that there are many applications of the 80/20 rule in software and many
of them don’t have anything to do with Pareto’s original observation. So, I’ve
started putting together a list of the basic 80/20 rules that exist in the
software industry.  So far I have the following and a few others that are almost the reverse (but I just started
really):

• 80% of your results come from 20% of your work
• 80% of your problems come from the same 20% of causes.
• 80% of your project is characterized by the initial 20% of decisions
  (framework, language, infrastructure, and metaphor choices mostly).

I would really appreciate it if you’d take a minute to drop me an e-mail at
masukomi at masukomi dot org or left a comment here for all to see with your 80
/ 20 rules.

How Greasemonkey can save your webapp time and money May 11, 2007

For the most part web developers spend our time guessing what features people
might want and how said features should be integrated. Frequently we guess wrong
and that wastes time and sometimes frustrates users. But there are tons of users
out there who also happen to be developers and they’re actively implementing new
features for their favorite sites with
Greasemonkey.
UserScripts.org
has over 6,000 scripts. That’s 6,000 features with working implementations for
popular sites at no cost to those sites! Free I say. Each one is a feature
someone wanted so badly that they figured out how a site worked and then wrote
working code to modify that site to implement that feature. If you’ve got a
somewhat popular webapp you owe it to yourself to watch userscripts.org and
google for other greasemonkey scripts for your site. Check out what people have
done, see how it works, maybe the rest of your users would like that too…



Consider offering some free goodies to people who send you cool greasemonkey
scripts. Even if it’s just a free t-shirt (go to CafePress and whip one up if
you have to). Maybe even put up a page of user submitted scripts. Some of your
own developers may even make them to implement features they wanted that may not
have been appropriate for all users of your site. Just make sure to emphasize
that they’re unsupported. ;)



Side note: this post was inspired by the creation of
my
first Greasemonkey script. It’s something for people who use Reddit and
del.icio.us. Not useful to Reddit in it’s current form but the idea behind it
might be very good for Reddit if expanded to support more bookmarking sites.