Over the last year and a half it has happened quite frequently that users on our mailing lists or Gitter channels asked: "What is this OBR you people keep talking about?". It was something that would most often be mentioned when we were frustrated with the current project setup making things more difficult than necessary.

How it all started

To understand what the OBR really is you first need to know how our project was organized all these years. Ceylon started out with nothing but the parser and the code that checks and models our unique typesystem, we call it the "typechecker". When we started working on the compilers new modules got added, first for the Java Virtual Machine, later for JavaScript. Then we added a module that handles downloading and caching of external modules retrieved from the Herd. This went on to the point that we wound up with 9 separate but very interdependent projects.

The problem

Now of course modularization is a good software engineering practise so there was no problem there. The problem was with the way we had created multiple Git repositories for each of the projects. We started noticing that for certain types of cross-module issues we often had to make changes to multiple repositories at a time. And when you do that, let's say you change 6 repositories for a single bug report or for a single new feature, you lose cohesion. The changes are all separate and you lose sight of the fact that they belong together. So if you need to go back in time looking for a specific problem and when it was introduced and by which code commit it suddenly becomes very hard to synchronize all the repositories in such a way that you get a working system. The famous git bisect becomes impossible to use.

It also caused minor problems when managing issues on GitHub because users, not knowing, would often open issues on the wrong project which meant manually copying the issue from one project to another (and sometimes even we didn't know where to put an issue and it would get moved several times).

Looking for a solution

So at a certain moment it became obvious that our project setup was working against us, that its structure made certain operations way too hard. A single repository on the other hand wouldn't have those problems. A single big repository, the only one for the entire distribution. So we started calling it the "One Big Repository", quickly shortened to "OBR".

But there were doubts that a single repository would become too big and unwieldy. And how would we go from 9 repositories to just 1? Are there tools to do that? And what about our GitHub issues?

Instead we first looked at tools like git submodule and git subtree which would allow us to keep our current projects but still treat them as a one. But after researching it for a while we came to the conclusion that although it might work it does make things more complex for the developer. And given the fact that most of us aren't Git experts and sometimes have trouble enough with it as it is we decided that the added complexity would not work in our favor. Besides the problem with the GitHub issues being separate would still remain.

The execution

One Big Repository it would be then, merging all 9 Ceylon distribution repositories into a single one. But how? No ready-made tools seemed to exist, just fragments of scripts and examples of complex Git commands. And for the GitHub issues we could only rely on their remote API.

I will spare you all the nitty gritty details on the many dozens of practise merges we did to get to a point where we were happy enough with the result but finally, last monday on November 16th, we made public the new OBR, the One Big Repository!

How to use it

Setting up a Ceylon environment for development used to be a big hassle. So much in fact that we created some pretty complex build scripts to do that all for you. So fortunately as a contributor you'd never notice, you'd just type ant setup and everything would be done for you.

But now things have become still easier, for you as a potential contributor the only that is needed is:

$ git clone https://github.com/ceylon/ceylon
$ cd ceylon
$ ant clean dist

For a more thorough explanation on how to set up a development environment and how to go from there to submitting your first contribution please visit Contributing to the compiler backend