Crystal Operation Agate


This is the fourth operation on the Crystal track, operations aim to deliver bigger content pieces compared to our ongoing work (like fixes, adding exercises, etc).

Crystal exercises on Exercism

It is an operation since this will be released over a period, usually 1-2 weeks (but this time it was released under 2 months).


  • Crystal 1.11
  • Test Runner overhual
  • Analyzer improvements
  • Windows improvements
  • Three new approach articles
  • Brand new document generator
  • Improvements to contributions
  • One new concept

Starting words

I know it has been a bit quiet from my side. I have had quite a bit of non-exercism-related work and projects going on. I have also decided to switch from monthly blog posts to quarterly blog posts like this one. Since the majority of content arrives around these operations doesn’t it make sense to write blog posts monthly.

I have some more stuff to announce later about my plans around contributing to Exercism, but that is for another time. In any case, I have prepared a new update with a bunch of changes, enjoy reading!

Crystal 1.11.2

Note: This may lead to some current solutions to break

This upgrade makes it so you can use the latest tools.

This also makes Crystal 1.11 an “officially” supported version.

This makes our list of “officially” supported versions: 1.7, 1.8, 1.9, 1.10, 1.11

With official means, we ensure that the version can solve all of the exercises and also that we will mention if some feature is not available for some of the versions. As detailed in the last operation Crystal 1.6 is no longer supported and the next operation will drop 1.7.


Test Runner overhual

The test runner has been completely refactored.

There have not been any real user-facing improvements.

Instead, this update mostly improves on maintainability and improving documentation.

The code base is now made of around 40-50 % fewer codes of lines.

This update also reduced the number of executables from 3 down to 2 which drastically improved build times.

This is intended to be the “final” version until Crystal releases a major version or exercism introduces v4 spec.

Analyzer improvements

The analyzer has received a big update through the usage of the new ameba version, 1.6. This brought several new comments to the code. As well as a todo comment that we had already implemented so that the method is not deprecated in favor of using the ameba version.

Due to some issues raised by the Crystal community, have we disabled the Naming/BlockParameterName rule.

There has been the addition of four new exercise-specific comments for the following exercises:

  • reverse-string
  • collatz-conjecture
  • castle-dinner

As well four exercises received comments about reusing. Which is the following:

  • castle-dinner
  • library-of-luton
  • password-lock
  • chess-game

This new update brings the analyzer to version 1.2.

The analyzer is also now running v1.3 of the representer.

Analyzer ci

The analyzer has received a brand-new CI. This ci is created since there have been a couple of issues raised due to some paths not being verified against the comments docs. This new ci will verify the paths before PRs are merged, which should reduce the number of errors around the analyzer. The ci is also written in Crystal.


The track has been heavily focused on only Linux and Mac. This has sorta been caused by Windows not being marked as a tier one platform but as the platform support has improved. Have I decided to take some time and work on improving the Windows experience. For students so does this only mean that we will start testing all the exercises against Windows. This is possible thanks to a new Powershell script.

But for contributors are there several new improvements. A lot of the scripts on the track are in bash, this is mostly due to technical reasons. Which makes them not fitting to be written in Crystal. This has meant that contributors on Windows couldn’t run crucial development scripts. I can now announce that all of the crucial scripts are now ported to PowerShell (bash versions still exist). This means that out of all our scripts only one script only available on unix. I hope that these improvements will make it easier for new contributors.

Test generator improvements

The biggest news is the fact mentioned above is that the generator script is now available in Powershell. But some other improvements have also happened. Mainly have the test generator receive its folder instead of being in the bin directory. There have also been a couple of smaller refactors. But another larger change is that tests have been added to test the application, there haven’t been any issues reported earlier, this is mostly done for safety for future development.


Approach is a document that deep dives into various ways to solve a certain exercise. This is meant for students to be able to get insights into other ways to solve a problem than how they solved it.

There are approaches for 3 exercises at the moment:

  • Leap
  • Raindrops
  • Reverse string

Writing approaches is something which requires a lot of time, thereby I would appreciate if somebody is willing to help out by writing some approaches, here are some links to issues which explains how to make them:

New concept

Added a new concept for blocks and procs, together with a new exercise called Task Handler. This new concept will lay the ground for the enumeration concepts coming in the next few months.

Practice exercises

One new practice exercise has been added which is List Ops, courtesy to @kahgoh for implementing the exercise.

Some exercises have recived major changes from problem spec:

  • leap-year
  • reverse-string
  • raindrops
  • roman-numerals

Some other changes include:

  • The exercise pop-count was renamed to eliuds-egg
  • Added an append to leap about not using built-in method
  • Various exercises have also been synced with problem spec (more than those mentioned above)
  • The exercise wellingtons-weather-station has received a new icon
  • The append of roman-numerlas changes from introduction append to instruction append.

It became so long, so had to split it into 2 parts:

New document generator

Concept doc handling has been an issue for quite a long time. This issue comes from it being 3 docs for a certain concept, their content is mostly shared but there is no system keeping in check that they are. This has many times led to new contributors opening a PR that only updates one of the docs. This in itself creates extra work for the maintainer and also increases the time until the PR can get merged.

To solve this I created a brand new tool called: Document Geneator, it goal is to reach the possibility of just having one doc and then gathering the data from that doc to create the other 2 documents. This is done by using templates and then filling those templates with data from the doc.

You may wonder how this differs from the configlet tool, configlet works with 2 docs while this one works with only 1. As well does this tool have as goal has to have more features.

This tool at the moment is quite experimental even though it has its production on the Crystal track. I plan to continue working on it, on making it more feature-rich. Which could include some breaking changes.

However, if some other track maintainer would like to try out this tool so does Crystal support building OS-specific executables which would mean Crystal wouldn’t be needed to use the application.


As outlined in a blog post last year, this year has the goal of improving contributions for the track.

There have been several improvements to improve on this, including: Improved Windows support and a new document generator.

There is still more work left but another big thing I have also started working on is adding more issues, outlining more clearly what needs help developing.

As of now does this include issues about creating new exercises, new approaches, and adding approaches to already existing approaches.

Here are some links to issues open for contributions:


  • Representer was buffed to v1.3, which updated crystal to 1.11.2
  • Analyzer 1.1.2 was released which fixed a bug (this was before the version mentioned above)
  • Test runner 2.0.1 was released which made exercises pass with errors.
  • Added a concept tree map in the misc folder.
  • Typo fixed in arys-amazing-lasgna, courtesy @spaenleh
  • Grammer fixes in bellebrook-basket-league and library-of-luton, courtesy @rjpgt
  • Fixes in classes concept, courtesy @Norbiox

What is coming?

The next version will focus on further improvements to the document generator and make it less unstable. Other changes will improve revisiting old concepts and do some further small-medium refactoring of tooling.


Amazing work! Thank you @Meatball :slight_smile:

Not only a very useful update, but an inspiring one too. Many thanks, @Meatball, for your dedication, and tremendous, on-going effort.

1 Like