Drupal.org Issue Workspaces


DrupalCon Los Angeles was full of great sessions.

I never finished a day disappointed. One of the more interesting sessions was Issue Workspaces: A better way to collaborate in Drupal.org issue queues.

Drupal.org holds a unique place in the open-source world. While I'm sure one exists, I'm not aware of any one domain that hosts its own core project and nearly every one of its extensions. Its nearest counterparts might be Perl's CPAN or NPM. However, not even they are as ambitious as Drupal.org in terms of maintaining processes for validating users, maintaining profiles, linking to project contributions and providing documentation.

The benefits of this approach are significant, but so is the effort that goes into maintaining all this infrastructure. From Git hosting, to testing, to module application reviews, so much happens on d.o that many have advocated breaking out the services it provides into other self-hosted or third-party solutions. I won't attempt to cover all of these, but I'd like to focus on just one, the GitHub/GitLab/Bitbucket vs. Drupal.org debate.

Every self-respecting open-source developer has used GitHub and/or its contemporaries. Why? They've made it dead simple to share, evaluate, and find open-source projects. They've made great developer-centric Git UIs and they've simplified the contribution process with innovative workflows (read "pull requests"). It's trivial to contribute to a project on GitHub.com, and it's just as trivial to throw up your work for other's consumption. The same cannot be said for Drupal.org.

So why then do we love Drupal.org? Agree with me or not, there are quite a few reasons that can be thrown about. From the code quality to the community, Drupal.org's Git workflows offer quite a bit. By keeping our projects central to Drupal.org, we maintain a central repository of solutions and extensions to Drupal. This means fewer project duplications, canonical solutions (e.g. Views module), licensure enforcement, search, security review processes, central issue queues, aggregated statistics, among many other benefits. Other communities, like NPM, have found solutions to some of these problems (e.g., "star" systems and project registration), but none has created a completely integrated environment. Many a node module can be found free, in the wild. Of course, some may see this as a benefit, but I think that collaboration should be over competition (I know, not mutually exclusive); there are other stand-alone debates on this topic specifically.


One fundamental benefit that I've seen on Drupal.org trumps the rest in my mind though. And that's communal and centralized deliberation. That is to say, the conversation around an issue is kept to a single thread (disregarding duplicate issues). This is different from GitHub et al. because all of those solutions organize comments by commits and "pull requests."

To illustrate, imagine that Joe has an issue with Project X. Joe has to find the project's page on GitHub and create an issue. Joe then forks the project, does his work and submits a pull request. Nancy comes to the issue and reviews Joe's code. Nancy has some comments and decides she wants to make a change. Nancy now has to fork the project or Joe's fork, and submit a PR to his branch or create her own PR for the project. Now, Joe comes along and appreciates her ideas, but has some concerns with one of her changes. Where should Joe make his comments? He can add a comment to his issue, which may or may not have Nancy's commit associated with it. He could go to her pull request and make a comment. He could also make an inline comment on one of her commits. As the issue gains traction, a third and fourth person might join the discussion, they may create their own forks and comments. One can no longer just read the single canonical issue to bring themselves up to speed. Whose fork is canonical? Whose work has been abandoned? The problem can be exponentially difficult to solve. This is the ugly side of distributed collaboration/deliberation, admittedly pessimistic, but nonetheless an outcome that is all too probable.

On Drupal.org, we instead have a patch-based workflow that has encouraged and enabled us to work on a single issue in an ordered, single thread. Joe comments, adds a patch, Nancy comments, adds a patch, and Joe responds in the issue queue and only in that issue queue. Any following collaborators can come to the thread, read it chronologically and add their contributions to the last patch or last agreed upon patch.

In short, the beauty of the d.o issue queue is that it imposes a chronological order in the collaborative process. It allows us to deliberate together and helps us make sense of everyone's work as a whole. We only have so much brainpower. On the other hand, the beauty of Git is that it handles the unordered and distributed nature of code commits. Unlike patches, commits don't quickly become "stale." And when they do, it's much more trivial to refresh them. This is the brilliance of a distributed VCS - it helps us reason about something inherently chaotic. The issue queue is how we reason about the meta-discussion around that same code.

The issue workspace proposal promises the best of both worlds. We can clone and work independently, we can increase the velocity of our contributions, and we can preserve all of the benefits we get from a single deliberative issue queue. For those reasons alone, I'm very excited to see what this Drupal.org innovation can bring.

Note: This is an expanded cross-post of my original comment on Drupal.org Issue #2488266: [META] Improve Git workflow on Drupal.org by implementing issue workspaces