Move your FOSS project to an org!

By default, forges like GitHub make you create new repositories under your own account. But most open source projects should rather be in an “organization”, even if there isn’t a corresponding legal entity for them.

In this post, we’ll assume your repository is on GitHub, but most of it applies to other forges like GitLab or Codeberg.

The downsides of personal repos

If you’re interested in attracting contributors to your project, personal repositories are not very well suited for that. To onboard trusted contributors, your only option is to add them as “Collaborators”. This gives them write access to the repository, but not much more than that: they cannot onboard more people themselves, nor can they access most other repository settings.

Beyond the permissions that you can grant them, various other aspects of the platform will influence their relationship to your project. First, you are the only owner of the repository. Your username is prominently displayed in the header of every page of the repository and in the URL. This means that people also more likely to see you as the (only) person responsible for fixing things when they break, or reviewing external contributions. Second, the “Collaborator” status that you grant to trusted contributors is almost not advertised at all. The GitHub profile of a collaborator doesn’t show that you have granted them this trust, so it’s harder for them to take credit for their work on your project. In the GitHub repository itself, the list of collaborators isn’t shown either. As far as I know, it’s only possible to find out who is a collaborator by looking for messages that they wrote in issues or pull requests, where a small badge will be shown, or by inferring it from other actions (such as them merging a pull request).

Another aspect that can make a big difference is that collaborators that you invite do not automatically watch the project. So by default, they do not get notified by new issues or pull requests, making it less likely that they take responsibility for them.

Onboarding contributors with organizations

Meet GitHub organizations! When a repository is owned by an org, it means that:

  • people can be added to the project with various configurable permission levels, including as co-owners
  • users are able to advertise their membership to the project, shown both on their profile and on the organization’s profile
  • depending on their permissions, new members automatically watch certain repositories
  • the project is more identifiable as a team endeavour, as the association to your account is visually less prominent
  • the organization can be used to host multiple repositories that are topically linked. For instance, if you have one repository for a library and one for an example application that uses that library, it makes sense to have them both in the same organization.

Migrating is easy!

It takes three simple steps:

  1. create an organization (selecting the free, open source plan). It is common to use the name of the project (which is often the name of the repository) as org name too.
  2. go to the settings of your repository and transfer it to the org
  3. update any URLs to the repository so that they point to the new address. GitHub sets up redirections anyway, so the change should be transparent for most users.

If you had added people as collaborators to the repository, they will remain collaborators of the new repository, but it makes sense to add them as members of the organization instead (so that they can benefit from the above).

Why aren’t organizations the norm?

I wish forge platforms could create an associated organization for each new repository, by default. Creating a personal repository, for instance for your dotfiles, would still be possible but would need to be chosen explicitly.

But GitHub has a strong incentive not to do that. Its revenue model is centered around providing services for companies, so it conveniently uses the org creation page to advertise its paid features for teams:

Screenshot of the org creation page on GitHub, advertising two paid plans beyond the free one, with the first paid plan prominently marked as ‘Most popular’

If creating a free organization was done automatically at repository creation, this would likely mean less people sign up for the paid features. This unfortunately reinforces the impression that organizations are for companies or other legal entities, while they are totally suited for projects without an institutional home.

Implicit feudalism

Curious about the implications of platform design for team dynamics? Check out Nathan Schneider’s article on “implicit feudalism”, the tendency of online services to grant absolute power to the creators of a given space (be it a chat channel, social media group, or an open source project). And if you are really serious about making your project a community endeavour, maybe get a governance model for it?