Legislating is patch review

Patch review is a process by which newcomers and experts debate proposed changes to a codebase–a textual description of how a particular human-created system is to function. In KDE, we use Phabricator for this, but we’re switching to GitLab soon. Both serve the same purpose: to provide a forum where proposed changes can be discussed, revised, and decided upon.

It occurred to me recently that this sounds a bit like the process of lawmaking. Politicians propose bills (patches) that amend their government’s code of laws (codebase) which are passed through committees and hearings (the review process) and eventually get voted on (reviewed) and either pass (get merged) or require revision (go around for updates), or fail (get abandoned).

Pictured: typical 18th-century patch review process

I’m reasonably confident that there’s little overlap between politicians and software enthusiasts. In my home country of the USA for example, most of our federal government politicians are former lawyers, businesspeople, or educators. “Software engineer” is listed as a “more unusual” former profession.

This strikes me as a shame. While lawyers, businesspeople, and educators are quite unfamiliar with the process of transforming a proposal for improvement on a systemic scale into a permanent alteration of the rules that affects everyone, software people do it every day. Likewise, software people like us tend to have little experience in the political process. We act like we invented patch review, but our governments have been doing it for hundreds of years! The overlap got me thinking: perhaps there is something that each group can learn from one another.


Have a constitution

Governments write constitutions to make their foundational principles clear and obvious. That way, everybody knows which ideas are central to the society’s identity, and which ones are off-limits.

Lesson for software engineers: Make your software’s guiding principles, explicit, not implicit. People often figure this out organically, but it’s much easier if your software has a constitution-like document and clearly indicates which features are non-negotiable when it comes to proposing their implementation or removal.


Don’t neglect trust

If you have a bad relationship with the people reviewing your patch, they will suspect your motives, nitpick your changes, and generally react with low enthusiasm. Even if your patch is a good one, the reviewers’ opinion of it will be clouded by their judgment of you. Therefore, don’t neglect your social relationships and act like a jerk, or else the whole process basically doesn’t work.

Lesson for politicians: don’t ignore or damage your social relationships with your colleagues or else your entire job is a big waste of time. Adopt a mindset that legislation is a collaboration rather than a majority-rules deathmatch or an opportunity to make speeches on a stage. Also, arrive with pure motives. If you’re there to try to tilt the playing field towards your favored groups, the people who represent the opposite side will notice and oppose you at every turn, and you’re likely to have a frustrating and unproductive career full of outrage-filled press conferences but not much real accomplishment.


Review in stages

In governments, often bills undergo review by multiple committed before they’re presented to the full body for debate and voting. This is good, because it gives a chance for obvious mistakes to be corrected in advance of the final vote.

Lesson for software engineers: use a multi-step patch review process, with relevant experts in control at each step of the way. For example, the big-picture software architects should review a patch for to make sure it conceptually makes sense in the first place; then backend programmers should dive into its technical implementation; the UI designers should go over its user interface, and so on.


Keep patches small

Large patches are hard to review and fill the reviewers with a sense of dread. They touch many things and therefore have more opportunities to change something in a way that a stakeholder will object to. They often get bogged down in process and conceptual arguments. For these reasons, it’s best to keep patches small and focused, and split a large change into a series of individually-manageable patches that each depend on one another, known as a dependency chain.

Lesson for politicians: avoid 1,000 page mega-bills. If a bill needs to be enormous in order to work, there’s probably a deeper conceptual issue with it that everyone senses.


Have an institutional memory

Records of how bills are moved along in the lawmaking process are kept meticulously. This preserves institutional memory, so that newcomers don’t make the same mistakes that their older colleagues and forefathers already learned from.

Lesson for software engineers: Keep records of why decisions were made–and even more importantly, why they were reverted. If you move from one infrastructure system to another, migrate all the data so history isn’t lost. This prevents the phenomenon of newcomers who propose the same changes and repeat the commit/regress/revert cycle.


Make reversion easy

When a patch causes regressions, it can be reverted. Oftentimes it’s better to fix it, but if the fixes are too invasive or the regressions outnumber the benefits, it may be a better idea to revert the change and try again. Making reversion easy promotes a culture of innovation and experimentation. People won’t be as worried about merging things, because if they cause problems, it’s easy to undo the changes. Change becomes playful and fun, rather than consequential and scary.

Lesson for politicians: Don’t make it too hard to repeal bad laws. When a newly-passed law causes problems in a society, it’s tempting to try to amend it to fix the problems, and sometimes this works. But sometimes it just needs to be re-done from scratch, like a bad patch in software. Being willing to repeal laws that aren’t working defuses tension. That said…


Don’t rush

Bills and patches that get through their processes quickly are often problematic, riddled with unseen regressions and unanticipated consequences. This is much less common in governments, because the lawmaking process usually has deliberate safeguards put in place to ensure that a bill is not transformed into a law too quickly before there’s been adequate time for debate.

Lesson for software engineers: Take your time so you don’t push out buggy, regression-filled software. However…


Don’t make your users live on the master branch

Rushing isn’t such a huge deal as long as you have a QA process and discrete releases. These tools provide time for regressions to be fixed and rough edges to be smoothed out. When patches can be evaluated in a safe sandbox of sorts and subsequently tweaked before their effects are released to users, it’s not so bad to move quickly. But you can’t expose your users to the churn stirred up by a fast process; it needs to be contained internally.

Lesson for politicians: You don’t need so much process surrounding lawmaking if you don’t roll out all approved changes immediately. Before new bills take effect, let them simmer for a while in a “release branch” where they can undergo QA so that regressions can be found before they’re inflicted on unsuspected citizens (users)!


As software people, there are lessons we can take from our governments’ successes (and more often these days it seems, their failures), because this aspect of our professions overlaps quite a bit. It also exposes an uncomfortable truth: changing the rules and behaviors of a system that effects everyone is inherently political. That’s why we invented patch review processes: to make sure that important voices are heard, that the system doesn’t become inhumane for people who depend on it, and that its overall trajectory is positive.

Personally I’m a lot more sanguine about the prospect of this in software than government right now, and I think that’s something that needs to change. The efficacy and positive societal impacts of our governments’ lawmaking seems to be at a bit of an ebb at the moment. But there may come a point in time when our experience in patch review becomes useful on a larger stage, and benefits not only users of KDE software, but also the people of the world. We shouldn’t be afraid of politics; our everyday experiences in KDE are in fact the prefect preparation! Far from being distant and scary, it’s something we’re engaging in–and succeeding at–every time we contribute to KDE. I think it’s time for us to become active in applying those lessons to the societies that we live in.

4 thoughts on “Legislating is patch review

  1. Great post, Nate. As someone who has thought, written and taught about laws, never about writing software, I learned a lot. I would throw two additional thoughts into the mix: Writing U.S. law is like “patching” but in other countries, (like Germany) codified law is much more comprehensive and less influenced by case law – (another form of patch). The give and take of the process is less flexible there, the comprehensive effort when the law is first constructed much more fundamental. More importantly: the passage of laws are subject to constellations of power. The power constellations often thwart the actual original purpose of the law. The affordable Care Act had a clear purpose: increasing access to health insurance. But this purpose was diluted because political power constellations meant that Do No Harm to health insurance companies was added as a a goal. This sort of muddling doesn’t really happen for the construction of software (or does it?). Engineers and lawmakers should work together, but political power is a beast that’s not easily tamed.

    Liked by 2 people

    1. Great point! In fact the kind of “requirement creep” you describe is not unique to lawmaking. It’s widespread in software too, as well as basically every other technical field, like product design. Every project that proposes bold or controversial changes has an inherent tendency to suffer from this as people who are scared of change but don’t have the power to stop it completely use what power they do have to insert additional requirements that the project not change some thing that they rely on or are familiar with. This generally contradicts the design vision of what the project is trying to be, and forces awkward compromises that impair the original purpose. It’s almost identical everywhere, really.

      And the solutions are the same: either reassure the people who are worried about the change, or exclude them from the process so they have limited power to oppose it. The latter option is faster and seems easier, but in the long term it backfires because it hardens an opposition wing that will try even harder to block the next thing you’re doing (again, this is totally true in software as well). Ultimately it’s better to make friends with the conservatives so they stop thinking you’re trying to destroy their way of life and the institutions they rely on than it is to make enemies out of them. They’re always too strong for that to work.


  2. Maybe you could do a post about the switching to Gitlab – what are the pros of the switch, why this decision was taken, what will change because of that, what were the hardships of Phabricator and so on.

    It’s not about justifying the switch, it’s just because this may be an interesting topic that could make people exciting and maybe more prone to jump into KDE wagon since it will be easier and more accessible (I think).

    I personally would prefer KDE to switch to Github but considering various reasons, Gitlab is the only sound solution and I applaud it. I would be curious about the behind the veil aspects and what is expected to be better because of the switch.


Leave a comment

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s