Skip to main content

Reanimating Zombie Projects Vol. I: Hamcrest Reflection

Posted by mkarg on December 27, 2013 at 9:14 PM PST

One day I found myself in the situation that I had to write a unit test which checks whether my code is annotated in a particular way. I wondered how one could do that without doing an integration test that actually processes that annotations. My first idea was to use the Reflection API, which in fact worked, but was not looking smart. In fact, I wanted to have a Hamcrest matcher instead, since tests are much more readable that way. So before turning my code into a matcher (which is easy but has potential for code duplication with other projects), I did as I always do: I googled for some open source. And luckily, such a project existed: Hamcrest Reflection. The project, founded by Hamcrest author Nat PRYCE, was in a very beta state: Almost done, not published, no downloads, no site, no build scripts, few bugs, in short: rather dead. What a good chance for me to contribute to open source! So I just adopted the project to get it to live again, allowing people to download and use it easily, and to make it pretty simple for others to contribute. Or in other words: I adopted a zombie project to reanimate it. Here is what I did:

1. Build and publish to Maven Central unchanged

I needed really quick a working JAR in Maven Central to finish my own project. So I checked out the code from Nat's SVN repo, then checked that the original source worked correctly (which it did, but due to a wrong test assumption I had to @Ingore a test), packed a JAR by hand, wrote a minimalistic POM, and published everything on Maven Central. For that, I applied for another project hosting and synchronization at Sonatype OSS Maven Respository (https://docs.sonatype.org/display/Repository/Sonatype+OSS+Maven+Reposito...), which syncs to Maven Central rather frequently. It is the fastest way to deploy open source to Maven Central, and it allows to publish even non-mavenized projects. In my case, I used mvn deploy:deploy-file to simply upload the manually built JAR, waited for some hours until the next sync was done, and was able to include Hamcrest Reflection in my own project by simply adding a Maven dependency entry. Yippee!

2. Request owner status at original author

Next I wanted to pimp the web site and upload some fixes. So I needed at least the contributor state, but hey, this is a zombie project, so I directly proposed to take ownership. I asked Nat PRICE by some concise email, and few hours later I was the project owner. Cool.

3. Publish initial web site

To get a zombie back into life again, people must learn what the stuff is good for, where to get it and how to use it. So the next step was to upload some initial web site, containing really only that minimum information. It contained the download link from Maven Central, and the GAV coordinates, so everybody was able to obtain and use it. Great.

4. Start using tracker

As soon as people are starting to use the software, they will find bugs or have ideas for new features. So they need a way to tell you. And typically you want to prevent to tell lots of people "I already know this". Typically, this is done using an issue tracker: People can check it before posting another bug report. As Nat hosted the project on Google Code, there was a tracker set up already, but unused so far. So I just added the sole known bug to the tracker to pevent more and more people telling me the same problem. Strike.

5. Providing a build script

Know that I had a public list of open bugs, I wanted to be able to merge fixes. For that, I needed to get rid of building JARs by hand. So I needed a build script. In my case, it was simple. As I had an initial POM already from the Maven Central upload, I just needed to extend it with few lines so that it actually builds the JAR and runs the test. Mainly changes were adding the existing source paths and dependencies, and after few minutes I had mvn clear test run perfectly. Yes!

6. Mavenization

As Maven is a de-facto standard (and due to its declarative style my absolute favorite) I wanted to Mavenize the project, which effectively results in more people being faster able to contribute, due to CoC. In fact this was as simple as moving files in the default place, getting rid of Nat's self-invented folder structure. Now everybody familiar with Maven would find things where expected. Nice.

7. Code Cleanup

One thing which happens always as soon as you accept contributions from other people is formatting mismatch. Someone has set his line length to 80 while you work with 160, you both do autoformat, and you're screwed, as the diff won't be concise to read anymore. That was the case here, where Nat obviously had used blanks while I used tabs, and I love to have parameters and variables final where Nat did not care. So I used Eclipse's automatic code cleanup and formatting to get all the missing finals, this's, tabs, and so on. This is a one-time burden for SVN, but after that, all commits will solely contain of the real changes only, as I am the only active committer and have saved an Eclipse profile for this project. Fine.

8. Tell people how to contribute

To wake up a zombie, you need help of others, as a living project is hard to drive alone. But how shall people know how they can help? So as the project was in an at-most simple way to get an build, I added the absolute essential information about contributing to the single-page web site on Google Code. Now I just need to wait for contributions and nobody will every again need to ask me by email how he can help. Good.

9. Fixing bugs

The sole bug was rather simple to fix, so I removed the @Ignore and added the fix. Now the way is free for an initial automated release. Yay!

10. Releasing

Certainly it is not very smart to upload files by hand to Maven Central. In fact, I want to get this done simply by mvn release:prepare release:perform. This was the most simple thing to do: Marking as SNAPSHOT, committing, running Maven, done. So here it is: Hamcrest Release 0.1-3, fully automatic built, signed and published on Maven Central.

11. What next?

Well, for me, the project does what I need, so I just wait for feature requests and bug reports. Or for someone who has great plans with it and wants to take over ownership and possibly drive more automation, like using a public CI service. For me, I think my job is done: Maven Hamcrest turned from a half-baked zombie to a fully functional project infrastructure. Time to look out for the next zombie!

12. I want you for zombie reanimation!

Why not joining me? If you know a zombie which you like to be maintained again, just follow my example and adopt that project. It is simpler as you think. The complete steps above just demanded few hours of my spare time. If I can do it, you can do it, too! :-)

Comments

Really informative text for anyone looking for guidelines to ...

Really informative text for anyone looking for guidelines to contribute to open source. Thanks