Diaries of a module maintainer, part 1 - Gardening the issue queue

I've been maintaining a growing amount of modules over the years. I am starting to document my observations, habits and challenges, in the hope they'd be useful to other Drupal coders.

Psychology of this coder

I devote time and energy to the development of a module. Since I consider myself a software craftsman, each module is a creation of mine - an artifact to which I try to imbue functional and aesthetic values. I also imbue each module a life of some sort, since it will be utilized on (hopefully) many sites, go through evolutions, and have a lifetime until it is no longer needed and used.

All this just to say that I develop an emotional relationship toward each module, and the moods of these relationships are reflected in my habits.

The issue queue

Handling issues is the daily activity of every maintainer. Before we get more abstract, let's see some simple practices I follow here:

Documenting the commit

I make it a point to link specific commits to the issue that motivated them. So for issue #2047473 "text shows incredibly small", I committed a fix whose comment says:

Remove non-portable CSS #2047473

Drupal cleverly links the issue number to the issue page above. However, there's no mention of this commit on the issue page. That's why I add a comment - to the issue, this time - typically saying

Committed a fix on some branch.

and I link this sentence to the actual git commit page. It would be great if Drupal.org included an automatic list of referencing commits on the issue page, just like Trac (and I'm sure other SCM sites) does.

Documenting the fix

When marking an issue as fixed, I make sure to explain how the issue was fixed, to set the expectation of the reporter and other interested users. They can then test the fix more easily, and the probability of getting useful feedback is higher.

For example:

I basically removed the padding declaration for the input elements.

In the case of responding to feature requests, I include in the fix comment a short description of the new functionality and UI that were introduced, and describe a short recipe to test them. Often, when dealing with 3rd party modules, it's not clear where in the Drupal UI the functionality is made accessible. That's what I am trying to avoid here with the description / recipe - I am sure that screenshots would also be useful.

I've also seen maintainers attach their own committed patches to the issue - I find this clarifying to quickly assess the fix (from the perspective of an interested user). Maybe allowing the Drupal git server to embed the commit (like GitHub does) would solve this more cleanly.

Stay tuned for...

  • Designing the module page
  • Making releases
  • Working with co-maintainers
  • Integrating with Drupal and other modules
  • Submitting patches to other modules
  • Designing module UI
  • Handling rising complexity
  • Providing professional services around your modules
  • ... and whatever else may come!

Comments

Not all maintainers reference the commit that resolved the particular issue after closing it. Though I am seeing this become a standard procedure, I image a system where after linking the commit to the node number drupal.org posts a comment on the issue thread referencing this commit. Why not? ~AlexB

Just ran into this great article by Rik de Boer on the very same topic. He talks about many of the points in my future list :-)

Definitely good practise, but it's a shame that much of this post is about dealing with deficiencies of the version control/issue tracking system in use. Why can't we just admit that the community doesn't have the resources to build something to rival the likes of github? We should let someone else maintain our issue tracker so we can concentrate on improving Drupal.

I've seen discussions about maintaining Drupal code on Github, or a separate Github instance. That would solve many problems, and relieve the Drupal.org maintainers from a huge chunk of work - in exchange for $$$ of course.

Some great tips here, especially the point of posting back to the issue how to test a fix. Simple, but I know that I need to do it more often.

You may wish to investigate dreditor (http://drupal.org/project/dreditor). This is a browser extension for Firefox and Chrome (maybe others) that will automatically generate commit messages based on an issue title and give credit to those that participated. Worth a look.

Well, instead of linking to the commit, you could link to the commitdiff, like this: http://drupalcode.org/sandbox/kratib/2046343.git/commitdiff/fd1d192

Great idea, thanks! I've switched to doing this.