Wednesday, January 30, 2019

Governance on demand

I have talked about the Spectrum of Open Source Governance Models before. After rereading Nadia Eghbal's excellent post Governance without foundations I feel tempted to add one more: Governance on demand.

Why that?

Nadia suggests a theory in the last footnote of her post, "that projects only need to define governance at the first sign of conflict". Intuitively, this makes immediate sense. We have all seen the projects which seem to work very fine without any thoughts about governance, and we also have seen those projects where attempts to set up formal governance have brought things to a halt instead of serving the project. So doing it at the last responsible point in time, when you actually need it, sounds like a very attractive model.

Being able to add governance on demand needs a high level of awareness and reflection. It also needs a culture which is open to the idea of governance, has the means to facilitate discussions about it, and is able to come to a conclusion. It is the point where you have to "decide to decide".

This is not easy, especially in the context of a conflict. It can be paralysing. Making decisions without having defined structures, without having precedence, takes responsibility and courage. Maybe not everybody will go along with it. You don't know because you haven't done it before.

One model which seems to be a quite natural outcome of such a "we need governance, now" situation, is the "benevolent dictator". When conflict arises, the founder or another exposed person steps in and takes a decision. This sets a trajectory for the project, which might be right or not. It depends on the project, on the people, on the environment.

Another model which comes naturally is to follow the "those who do the work decide" principle. This adds local, high context governance. It has to be underpinned by common values and a common sense of direction, though. Otherwise it will fail to solve the kind of conflicts where active people seem to stand against each other.

If you have a strong culture, it might appear you don't need governance. If you have shared values, if you have a common mission, if people learn by imitating healthy behavior from others, then it's easy to take decisions and to preempt conflicts. This could also be called a state of implicit governance, because it is there, but it's not formulated.

If you have a strong culture, then you are also prepared to add governance on demand. This can become necessary because of growth, a changing environment,  or other factors which can't be addressed by existing intuition.

From this point of view: Build culture first and governance will follow.

These are my thoughts. I would be more than happy to hear about your thoughts as well.

Foot note: In some way "governance on demand" is not a governance model in itself, but more a meta model. It doesn't tell how the governance regarding the project then has to look like but only answers a part of the question how to get there. It is in the nature of governance models to also cover this meta level, though. Maybe "governance on demand" is more a governance element than a model in itself. It governs the evolution of governance models.

Wednesday, January 9, 2019

Beautiful GitHub labels with Terraform

Managing issues is part of the daily life of most software projects. Reacting to bug reports, feature requests, pull requests, tracking what's going on and where to put attention, all that is usually handled in the bug or issue tracker of the project's choice.

On GitHub there are the GitHub issues, and they have become quite powerful over time. Just recently GitHub added the capability to show related issues, pin issues to repositories and to move them between repositories.

One important tool to manage issues on GitHub are labels, those nicely colored badges you can add to issues to get a better overview, to filter lists and queries, or to build further automation such as the presentation of good first issues to people new to the project.


If you have a lot of labels it tends to become a bit of effort to manage them well, especially if you want to keep colors consistent and descriptions up to date. It becomes even more effort when you try to do so across different repositories. We have all seen the psychedelic potpourri of colorful labels which tends to happen when you use labels generously.

Last year I saw Mitchell Hashimoto's excellent talk about anything as code at the Open Source Datacenter Conference in Berlin. He showed there how to use Terraform to manage infrastructure as code beyond the typical management of computing infrastructure such as servers or networks. He showed how to use it for more administrative tasks such as managing teams on GitHub.

This is a great approach because it replaces clicking around in a user interface by a more programming-like approach of maintaining configurations, preferably version controlled, and applying the same rules on them as on code. So you can do pull requests, review changes, have the history of what happened in git, run tests and other automation easily, etc.

The GitHub provider for Terraform also handles labels so I thought I would give it a try to manage labels as code. Directly doing this in the Terraform configuration is possible but it's a bit cumbersome and limited in what you can do with the data in this format. So I decided to put the data into a good old YAML file and writing a bit of Python code to deal with it.

The result is beautiful-labels, a small tool to manage GitHub labels from a YAML description via Terraform. It scans your repository for existing labels and their data, creates a YAML description from it, and then provides you the tools to turn it into a Terraform configuration.

Terraform is great in handling the state of things in the cloud, it takes care of operating the API in an effective way, figuring out what needs to be updated, and gives the user control, for example by providing a dry run which tells what would change without applying the changes yet. This is all quite convenient and powerful.

One thing beautiful-labels is supposed to make easy is the management of label colors. In addition to the convenience of managing them in YAML instead of having to use the UI, it also adds the option to generate an overview of the labels as SVG, nicely grouped in categories. This helps in grouping things together using colors and generally can augment documentation about how you intend labels to be used.


The tool is in an early state but it works. I use it to manage the labels in the inqlude repository on GitHub.

You could add another step of automation by letting CI run Terraform on commits to the YAML file. Maybe something to try for the future. As managing labels is not something you usually do on a daily basis, some manual step might also be good enough.

One caveat with labels is that GitHub uses the name of the label as identifier. That usually works great but can be a bit tricky when changing the name of a label. For this case I recommend to do it in the GitHub UI for now.

There are some other approaches how to do this kind of stuff. One of them is labeler which is a nice tool written in Go to manage labels from a YAML description. It directly operates the GitHub API. The advantage is that it's self-contained but it lacks the power of Terraform in terms of state management. Another is Zach Dunn's post "How we organize GitHub issue: A simple styleguide for tagging" which introduces the notion of color-coded categories.

It's wonderful when pieces come together, such as the GitHub API, Terraform, YAML, git, and people writing open source code around that. They result in a way to beautifully manage labels without having to put in too much effort.

If you have feedback or input please don't hesitate to drop me a line. I would be happy if beautiful-labels would be useful for you as well. Let me know how it goes. :-)

Governance on demand

I have talked about the Spectrum of Open Source Governance Models  before. After rereading Nadia Eghbal's excellent post Governance with...