Tag Archives: collaboration

The number one reason to start using git: interactive staging

Git is an excellent tool for collaborative software development in a number of ways. In my opinion, Git’s most valuable feature – which also happens to be one of its most underappreciated – is interactive staging: git add -i and git add -p. If you are a software development who does not use Git, or if you use Git but do not use this feature, you should not write another line of code until you learn it.

When working on a large project, there is no principle more important than that changesets are atomic. Combining more than one distinct change into a commit is highly detrimental to a project’s history. Muddled changesets are hell for future developers on the project, including Future You. The usefulness of log, blame, bisect, and (not to get hyperbolic or anything) version control itself, depends on commits being logically small units.

But, of course, software is not built linearly. You’re writing cool new feature X, but you notice that in order to complete X, you need to fix bug Y. The problem is that you’re already halfway finished with X. You could: generate a diff file, stash/reset your changes, fix Y, commit the fix to Y, reapply the X diff, and continue work on X. This is a pain. Or you could: commit a large changeset that contains X and Y. But this is lousy for the reasons described above. Ideally, you would be able to fix Y, continue with X, and then sort out the changesets just before commit.

This is what Git’s interactive staging lets you do. Start with a clean index. Begin hacking on X. Stumble on Y. Fix Y. Complete X. Then use Git’s stage to commit Y and X separately.

Here’s a real example. (What follows is a pretty basic situation. git add -p is a subset of git add -i, which is full of whiz-bang goodies.) Say I’m working on fixing some poor localization in BuddyPress. While doing so, I notice that some PHPDoc is missing. So I fix both issues, and git diff shows the following:


Now, I know that Changesets Should Be Atomic, so I want to commit the documentation changes separately from the bug fix. So, instead of git commit -a or git add . – which blindly stage all changes – I jump into patch mode with git add -p:


Git has determined what it considers to be the first “hunk” of changes. (Hunks: it takes one to know one.) I’m then asked whether I want to “Stage this hunk”. Normally I’ll just type y or n, but in this case I see that Git hasn’t made the hunks small enough, so I choose s, for “split”:


The hunk is now split into two. The first sub-hunk is the documentation fix. Let’s stage it with y. The second sub-hunk is the code fix, which we’ll skip for now with n. Rinse and repeat with the second big hunk. git status now shows the following:


The “changes ready to be committed” are the documentation fixes. These can be viewed with git diff --cached. The “changes not staged for commit” are the code changes. These can be viewed with git diff. I’m now ready to commit the first set of changes:


(I typed that commit message in my $EDITORvim – which you can’t see in this screenshot.) Then I’ll repeat the routine for the next set of changes, this time staging them all:


Git’s interactive staging is relatively simple, but will completely change the way you work, in ways that will result in meaningful improvements to your projects over time. This is, IMHO, the #1 reason to use Git, and if you’re not using it – because you’re an SVN user, because you didn’t know about it, because your GUI client doesn’t support it – it’s important enough that you ought to think about changing your toolkit.

Introducing Participad: Realtime collaboration for WordPress

Today I’m releasing the first public beta of a new WordPress plugin: Participad. Participad integrates an Etherpad Lite install into your WordPress installation, enabling realtime collaboration on the WordPress Dashboard or the front end of your WP site. If you’d like to download Participad, learn more about its features, or play with a demo site, check out participad.org. In the rest of this post, I’ll give some of the technical background about Participad, and some explanation of why it was built.

Participad was developed as part of some work I’m doing for thatcamp.org. If you’ve even been to a THATCamp unconference, you know that the first thing that generally happens in a session is that someone starts a Google Doc for collaborative notes, and tweets the link to the #thatcamp Twitter stream. In one sense, this is great – it’s very much in the spirit of THATCamp to have shared, crowdsourced, online notes for each session. But Google Docs, for all its coolness, is not the ideal tool for the job. For one thing, Google Docs are tied to a user’s account, making it very difficult to assemble a persistent, searchable archive of all THATCamp notes. There’s also the concern of storing user-generated THATCamp content on Google, which is alternatively benificent and malevolent, depending on the swings of the market.

Etherpad provides an ideal solution to the Google Docs conundrum. It’s a free software project that can be locally hosted, giving organizations and admins full control over the software and the data within. Etherpad has recently been rewritten as Etherpad Lite, an implementation in Node.js that is far more lightweight and easy to install than the original Etherpad, and, notably, has a rich REST API for integration with external software. This is what makes Participad possible: Participad uses iframes to display the Etherpad interface inside of WordPress, and then uses the EPL API to sync content between Etherpad Lite pads and the associated WordPress posts.

Participad is shipping today with three “modules”, each of which is a separate implementation of Etherpad Lite in your WP installation:

  • Notepads are the solution to the THATCamp/Google Docs problem described above. Notepads are a WordPress custom post type that can be created and edited from the front end of the blog by any logged-in user. Participad comes with a widget and a shortcode for displaying the Create A Notepad interface. And Participad redirects the Edit link seen on the front end of WP blog posts, so that it leads to a front-end editing interface. Content is synced back to the WP database every two minutes, or whenever a user clicks away from the Edit interface. In the spirit of THATCamp, Notepads can be “linked” to WordPress posts and pages, and a Participad widget can be placed in a sidebar that will display a list of a post’s Notepads. And because Notepads are just a species of WordPress posts, you can access lists of Notepads via an archive page.
  • Frontend is the Participad module that allows you to enable front-end, Etherpad editing for *any* WordPress content type. Turn it on, and the Edit link for any post will lead to an Etherpad interface, embedded in your theme where your static content would normally appear. Participad has a permissions schema that works with your WordPress installation, ensuring that only the users with the proper rights to edit a given piece of content through WP are able to edit that content through Participad as well.
  • Dashboard enables Etherpad editing throughout the Dashboard of your WP installation. All Edit screens – posts, pages, and other posts types – will have their WP editors (the Visual and HTML tabs) swapped out with a Participad tab. Autosave works just like it does in WP, and content is synced back to the WordPress database when you click Publish or Update.

I have a feeling that these three modules will cover most of the potential uses of Etherpad in WP, but if you have an unusual need, Participad is designed to be extensible. Build your own module by extending the Participad_Module class, in your own WordPress plugin.

Full instructions on setting up Participad can be found at http://participad.org/faqs/. Please note that Participad requires a separate Etherpad Lite installation, and for the moment, that installation must be accesible on the same domain as your WP install.

If you’d like to follow development, contribute fixes or improvements, or suggest future features, please visit Participad’s development home at github.com/boonebgorges/participad.

New BuddyPress plugin: BuddyPress Group Email Subscription

Email Options on settings page

Email Options on settings page

I’m quite happy to announce the release of a more-or-less stable (we hope!) version of BuddyPress Group Email Subscription, a BuddyPress plugin that allows for fine-grained, user-controllable email subscription to group content in BuddyPress.

This plugin is different from some of my others in that it was truly a group endeavor. The base of the plugin was written by David Cartwright, with a little bit of code from me. A nearly complete rewrite of the front-end and most of the guts of the plugin was undertaken by Deryk Wenaus. I wrote the daily and weekly digest functionality, along with some of the settings pages and various bugfixes throughout. The current codebase of the plugin is probably 60% Deryk, 30% me, and 10% David.

It was my first time working on a truly collaborative software development project like this, and it was a real pleasure working with both of these gentlemen. Thanks, guys.

Get BuddyPress Group Email Subscription here.

On the communal v. the individual student voice

On Thursday afternoon of this year’s Open Ed conference, a challenging contrast began to emerge between the approaches to student writing being espoused by the various speakers. First was Gardner Campbell and Jim Groom, who delivered a talk titled No Digital Facelifts: Thinking the Unthinkable About Open Educational Experiences. (This and other links go to Ustream recordings of the talks – they’re well worth your time, if you weren’t able to attend in person.) Gardner’s message echoed some of the familiar strains in Jim’s talk from the previous day, putting forth the idea that instead of herding students together into a single platform of our choosing, we should be giving them the tools and knowledge to be creators and curators of their own digital identity. (See this post at bavatuesdays for some of Jim’s thoughts on “a domain of one’s own”.) Gardner pushed this line of thinking a step further, suggesting that students literally become the sys admins of their own web space. Not only should students be able to move outside of the institutional platforms to develop their digital selves, the argument goes, but they should be free to choose and maintain whatever platform they’d like, without the different but perhaps equally cumbersome constraints of free/commercial platforms (like wordpress.com and others).

Now, before I start talking about where the tension arose, I should point out that while there’s something very right about this idea of Gardner’s, there’s something arbitrary about it as well. He suggests that we conceptualize something like cPanel as a meta-framework for the construction of identity. But why stop there? If cPanel > wordpress.com because of cPanel’s additional freedom to maneuver, doesn’t it follow that it’d be better to give each student a virtual machine with a bare OS on it? Or maybe for them to build their own kernel from assembly code, which would truly provide the most software freedom? The obvious reason is that at some point the tradeoff is no longer worth it: what you gain in freedom by dropping down a level of abstraction is not worth the extra effort you’d need to master the medium. And I’d argue that as time goes by, and software both advances to higher levels of abstraction from the raw code and at the same time becomes more useful, the calculus of determining the ideal level of abstraction is constantly in flux. To echo a discussion from this year’s THATCamp: while it might be the case that most students would benefit from learning some HTML and some basic programming today, it’s likely that there will come a point at which it’ll no longer worth the trouble; this, in much the same way that you don’t need to know assembly code to qualify as a computer geek (in most circles?!). A GUI like cPanel might be the right meta-framework for most students today, but we should constantly be reassessing this conclusion.

OK, so back to Thursday afternoon’s tension. The session following Gardner and Jim’s was led by John Maxwell and was titled Thinkubator: Wiki as CMS/LMS. (Actually, sandwiched between the two was a fricking awesome demo by Grant Potter of some work he’s doing with virtual worlds – but I’ll gloss over it for the purposes of this post.) John has been doing amazing things with the wiki, related to his research, to organizations he’s been involved with, and – most germane here – to his courses. He conceptualizes the wiki as a place where students – especially graduate students – learn to work in the way that scholars work. (John, I’m going to fill in some points you left unsaid here, so please tell me if I’m borking.) While it’s of course true that individual scholars maintain their own voices and perspectives, there is also a voice that emerges from a community of scholars who are writing about the same things, publishing in the same journals, editing and reviewing each other’s work, teaching in the same departments, etc. In one of the best one-liners of the conference, John pointed out that students get practice in developing this kind of communal space in kindergarten and in graduate seminars – but not in between. Multi-authored wikis are, by their very nature, communal spaces. Thus, when students do their work on a wiki, they are learning the sociology of group work and of their discipline at the same time that they’re learning the subject matter of the course.

So here’s the tension (which John himself articulates very clearly in his own reflection on the talk). The Campbell/Groom angle is that students are better served by stewarding their own spaces: emphasis on the individual voice. The Maxwell angle is that students learn about how scholarship functions by authoring together in a space like a wiki: emphasis on the communal voice.

There is a sense in which the tension might be fundamental, going to the heart of what we want our students gain from our classes. If the point of education is to shape students’ individual agency – to make them sys admins of their own souls (?) – then it makes perfect sense to make them sys admins of their online selves. If the point of education is to develop the next generation of scholars (or, if we want to take the point further, the next generation of society members), then the wiki approach might be more sensible. Insofar as there is a real conflict here, it might run even deeper than the purpose of education, but to the purpose of knowledge production itself: is it more important to foster and encourage each individual’s idiosyncratic “truth” scheme or our collective movement toward Truth?

From a practical point of view, the tension is probably not so stark. A student with a developed voice and identity is more likely to be able to step back and envision his or her place in communal spaces; and someone who is comfortable participating in shared knowledge development will be better equipped to develop his or her own particular point of view. But the contrast with respect to educational technology policy remains. A wiki setup like Maxwell’s is homogeneous and centralized, while the Campbell/Groom arrangement is various and distributed. I wonder how much of this is a technological accident, though, and to what extent the phenomenal qualities of Maxwell’s method can be superimposed on the Campbell/Groom architecture. What I mean, very roughly, is that we might envision a new generation of software whose underlying infrastructure is essentially distributed and customizable – respecting the agency of individual student-sysadmins – while communal spaces, rich with the versioning and community feature of wikis, can emerge at the higher levels of abstraction. I’m not smart enough to envision what this might look like in detail, but in theory it might preserve some of the educational advantages of each approach.

What do you think? Is there really a tension between the two approaches? Does the underlying technological model you choose for classroom work rule out certain rhetorical models, or does it just make some a little harder to attain?