Versioning packages and docker releases

[rachitnigam]

Calyx Packages

After #1377, we've started releasing individual crates corresponding to each folder in the repo. For example the calyx crate pulls in all the dependent crates and builds the compiler for people to use as a binary. This means that the easiest way to play with Calyx now is to install it through cargo:

cargo install calyx

Which installs the calyx binary representing the compiler.

An appropriate semantic versioning scheme for the compiler is useful so that dependent projects like Filament can have stable builds. I propose trying to following the semantic versioning guidelines to the best of our abilities. As more people use Calyx, we can address any problems that show up.

Docker Images

Our docker image release process is currently very ad-hoc. We just build the image on whatever the latest version of Calyx on master is and pushing the new image to calyx:latest. This means that anyone using the Calyx image relies on the latest tag which might change under their feet.

A more appropriate solution here is to build the docker image with a particular version of the compiler and version the Docker image itself. Going forward, we should release new versions of the Docker image based on the version of the calyx crates.

For example, the latest version of calyx on crates.io is v0.2.0. Given this, the version of the docker image tag should be calyx:0.2.0. There is one problem with this: what if we want to release a new version of the image where the calyx package version hasn't changed but one of the tools has?

A different option is say that new docker containers will only be release for major or minor version of Calyx (terminology from semantic versioning) and we will not release patch version of the package as docker images. The benefit of this is that we can use the patch part of the version as the indicator that something about the tools has changed in the docker image.

For example:

• calyx:0.2.0: Uses the calyx package v0.2.0
• calyx:0.2.1: Uses the calyx package v0.2.0 but has changes made to the tools setup in the docker image.

I'm not wedded to either idea but it would be good to figure out a solution soon.

[sampsyo]

All good points! One possible low-effort compromise could be that we get tagged Docker releases corresponding to each crate release, and also bump some other tag like calyx:dev with the current contents of the main branch. That doesn't solve the problem for situations that really need a Docker image that's "like 0.2 but with better Docker stuff," but maybe the :dev version would suffice for most cases.

[rachitnigam]

Hm, right. The verbose solution is kind of like calyx:0.2.0:dev:0.0.1 but then it's not clear what 0.0.1 is supposed to version