Migrating Oh My Zsh to our GitHub organization

$ mv robbyrussell/oh-my-zsh ohmyzsh/ohmyzsh

Background

How the project started was already talked about in this blog post by Robby. It talks of the serendipity and dumb luck of starting a popular and still growing project, and some of the philosophies behind it. Since then, 10 years have past (we celebrated it in style), and the size of the project made evident that we were lacking something. Something that only a GitHub organization could give us.

Liquid error: internal

The organization was created in September of 2016(the first public reference is of late 2016), but it wasn’t put to use for real until beginning this year when a repository for GitHub Actions was created. We didn’t really talk about a migration until much later, probably because the thought of breaking something was too stressful. It turned out though that we didn’t have any reasons to be concerned.

The final decision was made 2 weeks ago: the project had grown so much that it didn’t make sense to have it hamstrung by being under a personal account. GitHub has many features and advantages for open source projects that are only applicable under an organization.

Some of the main features of GitHub organizations that we needed were member roles and fine-grained permissions, to easily onboard maintainers at a pace we’d be comfortable with, and also a better experience with GitHub Actions that we couldn’t get with the project being under a personal account. We’re excited to dive in and find many other cool stuff that GitHub has built.

The process

As it turns out, the process of transferring a personal repository to an organization is really easy and has very few caveats. It’s obvious that GitHub did really think it through. Here are some of the items we thought important to cover for the transfer (taken from #8388):

1. Update main / billing email address to Robby's email
2. Notify the teams
3. Transfer repository to @ohmyzsh
4. Rename repository from oh-my-zsh to ohmyzsh for consistency
5. Update all instances of old URL in codebase
6. Update all instances of old URL in the wiki
7. Update website install guide
8. Add automatic remote reset when performing an upgrade (this should check the remote matches robbyrussell/oh-my-zsh)

3 and 4 are the only really necessary ones. Everything else comes second: we could live without doing them but they’re a nice-to-have, as GitHub takes care of redirecting the old URLs. There have been no documented hiccups while the transfer was in process; this really says a lot about GitHub.

What does this mean for the end user?

Great question. We attempted to make this transition as simple and seamless as possible and, as we’ve said before, GitHub has made it very easy. Here are the things that have been transferred along with the repository:

• Issues, including Pull Requests
• Wiki
• Stars
• Watchers
• Webhooks
• Forks associated
• Issue assignments to members of the organization

We also added an automatic reset of the git remote URL in the ohmyzsh folder ($ZSH). This reset only applies if the git remote is the default one (robbyrussell/oh-my-zsh via HTTPS). For this reset to be applied, there needs to be a 2-step upgrade: once to download the remote reset logic, and once again to apply it. As always, you can trigger an upgrade with upgrade_oh_my_zsh.

Users using an SSH URL or other valid git remote URLs should make the change manually. Again, nothing happens if this isn’t done, GitHub takes care of the redirection, but it’s just to avoid confusion.

Going forward

The project has been a little behind the times compared to other successful projects. We want to fix that from now on. One of the things we’re fixing is that the community doesn’t have a place other than GitHub issues to talk to each other. This is why we have created a Discord server, with the goal of putting users in touch with each other and also to get support from the community. We have other goals in mind to get the project to the state that the community deserves that we'll get to in a future article.

Developers

Robby Russell: original creator and maintainer.
Marc Cornellà: maintainer for the past few years.
Larson Carter: newly added maintainer.