What We Open Sourced, and What We Did Not

On 20 August we pushed the compiler and the command line tool out of our private repository and into github.com/cordango. Three days later you could install it in one line. Somebody then looked at the dates on the GitHub organisation and concluded we had started building Cordango that week, which was a funny thing to read after seven weeks of not sleeping much.

So here is the boring version. What is actually in there, what you can do with it, what you cannot, and where we drew the line between the open part and the part we sell.

The short version

cordango/cordango is Apache-2.0. It holds the format we use to describe an application, the thing that checks a description is valid, and the generator that turns that description into a real application you own.

Cordango the product is the hosted platform companies run on. That is not in the repository and is not going to be.

Both halves read the same file.

What you can actually do with it

Install the CLI, write an app definition, and run two commands:

cordango check    is this description valid
cordango build    turn it into a working application

What comes out of build is an ordinary repository. ASP.NET Core and EF Core on the back, Vue and Vuetify on the front, a Dockerfile, a compose file, and migrations you can read. Entities, a REST API, roles and per-field permissions enforced on the server, sign-in, a first run setup screen, and a demo dataset so the thing is not empty the first time you open it.

It has no dependency on us. No licence server, no account, no phone home. Delete the toolchain afterwards and it still builds.

There is also cordango import, which takes an application out of a Cordango instance and turns it back into files, and cordango login and cordango publish if you want to go the other way.

The one I would try first is cordango check, because it runs on a laptop with no account and no network. That was deliberate, and I will come back to it.

What you cannot do

You cannot run Cordango from it. People hear open core and picture a self-hostable version of the product with the expensive parts removed, and that is not what this is. It reads the same file as the platform does. That is the whole of the relationship between them.

The generator has one working target today, dotnet-vue. Node, Python and React are in the readme because that is where this is going, not because you can use them. The flag will not accept them yet. PostgreSQL is the only database.

And the whole thing is pre-alpha. It works end to end and nothing about it is stable.

Where the line is

Our first instinct was to cut it by feature. Open the parts that are easy to give away, keep the parts that took longest. That is the obvious way to do it and I have changed my mind about it, because what you get at the end is something nobody can finish anything with unless they pay you. That is a demo wearing a licence file.

So we cut it by job instead.

Writing an application and checking that it is correct is one job. That job is open, all of it, and it runs offline with no account, because a validator you can only run against somebody else's server is not a validator. It is an API call.

Running many companies on one system is a different job. That is the platform and it stays ours. The shared company foundation every app in a workspace reads from, the assistant that builds an app with you, the company research, the machinery that keeps a large model of numbers correct while several people are editing it. None of that is in the repository.

Getting this right on the first attempt mattered more than it usually does, because Apache-2.0 cannot be taken back. Anything we pushed stayed pushed. The argument had to happen before the button, not after.

The part I would want to know about

The generator refuses to build rather than quietly shipping less than your definition asked for. If it cannot do something, it stops and tells you the code and the exact path in your file that caused it.

You can override that with a flag, and then it writes every gap into the generated readme and into a build record that stays with the project. A partial build cannot later be mistaken for a complete one, which is the failure mode I actually worried about.

I like this more than I expected to. (It also means our roadmap is legible from the diagnostic codes, which was not the plan when we added them.)

Go and look

github.com/cordango is the organisation. docs.cordango.com is the documentation, and it went online the same day the tool became installable, because a tool whose manual is not written yet is not really installable. The quickstart goes from nothing to a running application, and concepts explains the app definition if you want to understand the format before you install anything.

If you generate something and it refuses to build, send me the diagnostic code. That list is how we decide what to do next, and most of what is on it today is things we have not got to yet rather than things we cannot do.