Although my maven bitching has been mostly snarky, I have come to truly believe it is the wrong tool for a growing enterprise and, like centralized version control, will lead to a situation where tools dictate process (and design).

But, what is maven actually good at?

• Maven is great for getting started -- you don't have author an ant file (or copy one from an existing project)
• Maven is great for enforcing a standard project structure -- if you always use maven, your projects always look the same

Dependency management is not a build step

Maven is the equivalent of doing a sudo gem update everytime you call rake, or doing a sudo yum update before running make. That's just insane. While automated dependency management is a key feature of a sophisticated development process, this is a separate process from developing my application.

Maven's configuration is incredibly verbose

It requires 36 lines of human-readable XML to have my webapp run during integration tests. Thirty Six! It requires six lines just to state a dependency. Examining a maven file and tying to figure out where you are in its insane hierarchy is quite difficult. It's been pretty well-established outside the Java community that XML is horrible configuration file format; formats like YAML have a higher signal to noise ration, and using (gasp) actual scripting language code can be even more compact (and readable and maintainable).

The jars you use are at the mercy of Maven

If you want to use a third-party library, and maven doesn't provide it (or doesn't provide the version you need), you have to set up your own maven repo. You then have to include that repo in your pom file, or in every single developer's local maven settings. If you secure your repo? More XML configuration (and, until the most recent version, you had to have your password in cleartext...in a version 2 application). The fallout here is that you will tend to stick with the versions available publicly, and we see how well that worked out for Debian.

Modifying default behavior is very difficult

Since maven is essentially a very, very high-level abstraction, you are the mercy of the plugin developers as to what you can do. For example, it is not possible to run your integration tests through Cobertura. The plugin developers didn't provide this and there's no way to do it without some major hacking of your test code organization and pom file. This is bending your process to fit a tool's shortcoming. This is limitation designed into maven. This is fundamentally different that "opinionated software" like Rails; Rails doesn't punish you so harshly for wanting to tweak things; maven makes it very difficult (or impossible). There was no thought given in Maven's design to using non-default behavior.

Extending Maven requires learning a plugin API

While you can throw in random Ant code into maven, the only way to create re-usable functionality is to learn a complex plugin API. Granted, this isn't complex like J2EE is complex, but for scripting a build, it's rather ludicrous.

Maven is hard to understand

I would be willing to bet that every one of my gripes is addressed through some crazy incantation. But that's not good enough. The combined experience of the 7 developers at my company is about 70 years and not one of us can explain maven's phases, identify the available targets, or successfully add new functionality for a pom without at least an hour on the net and maven's documentation.

A great example is the release plugin. All five developers here that have used it go through the same cycle of having no idea what it's doing, having it fail with a baffling error message, starting over and finally figuring out the one environment tweak that makes it work. At the end of this journey each one (myself included) has realized all this is a HUGE wrapper around scp and a few svn commands. Running two commands to do a source code tag and artifact copy shouldn't be this difficult.

Maven's command line output is a straight-up lie

[INFO] ------------------------------------------------------------------------
[ERROR] BUILD FAILURE
[INFO] ------------------------------------------------------------------------
[INFO] Compilation failure

Maven doesn't solve the problems of make

Ant's whole reason for being is "tabs are evil", and that tells you something. While maven's description of itself is a complete fabrication, it at least has its heart in the right place. However, it STILL fails to solve make's shortcomings wrt to java:

• Maven doesn't recompile the java classes that are truly out-of-date
• Maven recompiles java classes that are not out-of-date
• Maven doesn't allow for sophisiticated behavior through scripting
• Maven replaces arcane magic symbols with arcane magic nested XML (e.g. pom files aren't more readable than a Makefile)

Maven is slow

Conclusion

Apache's Ivy + Ant is probably a better environment than maven for getting things done; a bit of up-front work is required, but it's not an ongoing cost, and maintenance is much simpler and more straightforward. Tools like Buildr and Raven seem promising, but it might be like discussing the best braking system for a horse-drawn carriage; utterly futile and irrelevant.

The best way to get started with Git and have a better experience at work if you have to use SVN is to use git svn as a client to Subversion. You can take advantage of Git's awesomeness while not requiring your team or infrastructure to change immediately.

Setup

Working on Trunk

1. git svn rebase # Optional: only if you want to get work from svn; you don't have to
2. Hack some code
3. git add any new files you created.txt
4. git commit -a
5. Repeat from step 2 until done

Sharing Your Changes

1. git svn rebase
2. git svn dcommit

If you got Conflicts

1. Git will tell you about them, so go and resolve them
2. For each file you had to resolve, git add the_filename
3. git rebase --continue
4. Repeat until done

Working with SVN's branches

1. git svn fetch # This updates your local copy of remote branches
2. git checkout 1.3.x# This checks out a remote branch, which you shouldn't work directly on
3. git checkout -b 1.3.x-branch # This creates a local branch you can work on, based on the remote 1.3.x branch
4. Hack some code
5. git add and git commit -a as needed
6. Follow same procedure as above for Sharing Your Changes. Git will send your changes to the 1.3.x branch in SVN and not the trunk

Merging the Changes You Made

So What?

Gotta Fix a Bug Real Quicklike

1. git stash
2. git checkout production-branch-name
3. git checkout -b bugfix-xyz
4. Fix bugs
5. git commit -a
6. git svn dcommit
7. git checkout master
8. git stash apply

Can't commit to SVN due to a release

1. git commit -a
2. Continuing working

Blocked on Feature X, Want to work on Feature Y

1. git checkout master
2. git checkout -b feature-X
3. Work on Feature X
4. git commit -a etc. as I work
5. Get blocked; meeting next week. D'oh!
6. git checkout master
7. git checkout -b feature-Y
8. Work on Feature Y

Type your log message, save it, realize you forgot to reference a bug ticket #

1. git commit --amend

Advanced Stuff

Topic Branches

Save your Experiments

Cherry Pick

Mindlessly Backup Your Repo

1. ssh your_user@some.other.box.com
2. mkdir awesome_project
3. cd awesome_project
4. git init
5. exit
6. git remote add other-box your_user@some.other.box.com:/home/chrisb/awesome_project
7. git push --all other-box
8. echo "git push --force --all other-box" > .git/hooks/post-commit && chmod +x .git/hooks/post-commit

With regard to this blog on REST compliance

Me: The Gliffy API is RESTFul
REST Compliance Officer: Does a "PUT" update the data at the given URL?
Me: Yes.
RCO: Trick Question! It's "URI". Is the only way to create a new resource done with a "POST"?
Me: Yes.
RCO: Is there exactly one endpoint, from which any and all resource locators are discoverable?
Me: Um, no, that puts undue burden on the client libraries, and over-complicates what we were trying to accomp....
RCO: YOU ARE NOT RESTFUL! READ FIELDING'S DISSERTATION, THE HTTP SPEC AND IMPLEMENT AN RFC-COMPLIANT URI PARSER IN THREE DIFFERENT LANGUAGES. NEXT!

Thank GODS that REST doesn't have a spec. If it did, it would still be in development.

P.S. If you are going to coin a term and you want to bitch about it being misused, maybe calling it a "style" isn't the best idea.

In the beginning, EJB was a bloated mess of XML configuration files that allowed some sort of ultimate flexibility that absolutely no one needed nor cared about. And it sucked. So developers started using conventions to keep track of the four classes required to make a remote method call, and XDoclet was created to automate the creation of the XML configuration files. And it sucked less. Following in EJB's footsteps, Hibernate did the same thing. And XDoclet followed. And it still sucked.

So, annotations were created to essentially formalize what XDoclet was doing, instead of considering how horribly broken the implementation of J2EE or Hibernate was. And now that we have annotations, the "implementation pattern" of "ultimate flexibility through annotations" has made its way into numerous Java frameworks, such as JAX-RS and JPA.

Regarding JPA:

@Id
@GeneratedValue
@Column(name="person_id")
public int getPersonId() { return personId; }

I have a Person class with a getPersonId method. Can JPA just assume that it maps to the PERSON table, and the PERSON_ID, respectively. Further, couldn't it figure out that it's the auto-generated primary key since the schema says primary key auto increment. All the information is there and available to the framework to figure this out.

The same goes for EJB. I have a class named FooStatelessBean. How about we assume it's a stateless session bean, and it's interface is defined by its public methods? It can then provide FooRemote and FooLocal for me, and I don't need to configure anything or keep three classes in sync.

Just because Java doesn't have all the Ruby dynamic magic doesn't mean we can't make things easy. In reading Surya Suravarapu’s blog post about CRUD via JAX-RS I can't help wondering why it takes so much code to call a few methods on a class?

Did the designers of JAX-RS not even look at how Rails does things? I get a PUT to the url /customers/45. We should default to calling put(45) on the class CustomersResource. Only if I want to obfuscate what's going (e.g. by having FooBar.frobnosticate() handle the request) should I be required to provide configuration.

Even in Surya's example code, he's following some conventions: His resource class is suffixed with Resource and his POST method is prefixed add. This should be baked into the spec. It's like EJB all over again with the common conventions that aren't supported by the framework because of too much useless flexibilty.

Supporting convention over configuration is easy in Java. In just a few hours, I had a tiny web framework that proves it¹. It wouldn't take much more effort to allow the default behavior to be overridden, but, unlike JAX-RS, EJB, or even the Servlet spec itself, it doesn't punish developers who follow conventions. It makes their lives easier and thus encourages good behavior.

So, the point of all this is that annotations encourage bad framework design; unnecessary configuration is a major part of many Java frameworks and specs. And I have no idea why.

¹it unfortunately breaks down at the UI layer, due to a statically typed and compiled language not being a great choice for implementing web UIs, but that's another issue.

My command line interface for Gliffy is relatively complete. It works pretty well, though the error handling isn't very clean. It's written in Ruby (RDoc here) and can be used as a Ruby client for Gliffy.

I decided on Ruby since that would be the most fun and didn't require learning a new programming language. I initially tried to make an ActiveRecord-style domain-based interface, but it was just too difficult and it was hard to see the real benefit. At the end of the day, I think integrating Gliffy into another application is a relatively simple thing, and a procedural interface would probably be the easiest way to do that. So, I modeled it after the PHP client library, more or less.

The command line interface uses the Ruby client library and provides just the basic functions I need:

> gliffy ls
321654 Some Diagram
987654 Some Other Diagram
> gliffy edit 321654
# Takes you to your browser to edit the diagram

I'm already feeling like providing access to the folders via the command line would be helpful (they are exposed in the Ruby client of course). Not sure how much the API will ultimately change (it's in private beta now), but hopefully not too much.

GitHub Pages (explained here) is yet another awesome feature of GitHub. You can publish, via git, arbitrary web content (even piping it through Jekyll for Textile markup and syntax highlighting). They have been keeping a tremendous momentum of late; introducing new features on a regular basis. I hope they keep it up. GitHub is, IMO, crushing SourceForge and Google Code in terms of simplicity, ease-of-use, and overall functionality.

Gliffy hooked me up with access to the private beta of their API (which I helped design and implement). I create a PHP client and experimental MediaWiki plugin to validate the API while working for them, and now I want to get something else going in my spare time.

My first thought was to make a Ruby client, because I think it would be fun and relatively easy. But, I have to admit that a Wordpress plugin would be more useful to me personally. That being said, A Trac extension would be useful at work, since we are using Trac (which is python based, and I can't say I'm too interestedin Python at the moment). I think if GitHub allowed git access to project wikis, it would be cool to allow easier integration of Gliffy diagrams to GitHub project wikis.

At any rate, I don't have tons of time outside of work, so I want it to be something easily achievable, and also something Chris and Clint are not likely to work on themselves....

So, the "Ruby way" is to use underscores to delimit most identifiers, e.g. "add_months_to_date", as opposed to the Java camel-case way of "addMonthsToDate". This was initially something that irked me about Ruby, mostly because typing an underscore is kindof a pain (shift with the left hand and pinky with the other).

Now that I've started working, I've been reading a lot of code and realizing that code is more often read than written. Ultimately, camel case is a just lot harder to read (especially if you create meaningful method names like myself and my co-workers seem to do).

It's pretty hard to defend:

Date calculatePersonDataUsageHistoryStartDate() {}

def calculate_person_data_usage_history_start_date()
end

// Calculates the start date of the

// person's data usage history

time_ prsn_dt_uhst_st_dt(){}

This would never fly with Java (and, honestly, look a bit weird), but I'm no longer gonna curse the Ruby convention.