marisa's "blog"

Today we released Rustlings 2.0. There's some interesting things in this release:

• Exercises are now indexed by name, not by file name. This means that where previously you had to input a long path with rustlings run exercises/primitive_types/primitive_types1.rs, you can now shorten it to rustlings run primitive_types1
• rustlings watch will now require the user to delete a comment called // I AM NOT DONE to proceed, even when the exercise compiles or tests. Many of our exercises encourage the user to try out multiple different solutions, which was not possible to do before, since you had to move out of watch and manually verify the exercise using run. rustlings verify is also affected by this, but rustlings run is not.
• There is a new way to interact with hints. Hints are not at the end of the file anymore, instead, you can view the hint(s) for a given exercise using rustlings hint exerciseName. Multiple people were having problems with hints being visible due to their screen heights or their autoformatters not playing nice, which is why it was refactored.
• Rustlings now self-checks for the existence of rustc before running, in case you somehow installed Rustlings without having rustc.

A massive thanks to Roberto Vidal for pairing with me on some of these issues and helping push this out.

Significance of a breaking change

This release isn't all that special in terms of feature density. We haven't added or removed any exercises, but the reason we've decided to release a new major version is because we introduced what we believe are breaking changes.

Rust projects usually try to abide by a standard known as SemVer, which attempts to quantify the long headache of software versioning into something that makes sense in people's heads. The short version of it is:

• Bug fixes –> Increment Patch (0.0.1 to 0.0.2)
• Feature additions and enhancements that are backwards compatible –> Increment Minor (0.0.1 to 0.1.0)
• Features, Deletions, Enhancements that are backwards incompatible –> Increment Major (0.0.1 to 1.0.0)

The latter of those three cases includes breaking changes, which means changes that make the new API of your software incompatible with how it was used before.

The problem with our changes is that, say, refactoring the hint system (aka introducing the rustlings hint command) technically doesn't produce a breaking change, as we're only adding a feature to our API (the Rustlings CLI). What we're getting at is the limits of a technical specification such as SemVer, which fails to address the human-centered side of software.

Admittedly, and in defense of SemVer, dealing with humans is really hard, and I'm not criticizing for that, but for software like Rustlings, which thousands of people use for learning Rust, we can't purely rely on a technical spec for releases.

Releasing software for humans

How then are we going to solve this dilemma? It seems like we'll have to throw some existing conventions out of the window and make our own. What we came up with is more or less specifically aimed at Rustlings, and it's partly based off SemVer, and partly based off what our intuition tells us:

• Bug fixes –> Increment Patch
• Feature additions, or backwards incompatible changes that only affect a small part of the exercises (changing one exercise or changing one category of them) –> Increment Minor
• Backwards incompatible changes in the CLI source or changes that modify all exercises –> Increment Major

When I say “based off our intuition” here, what I mean is that we took into account how people using Rustlings will perceive these changes. The important thing to take into account is that the way most people use Rustlings is very limited – they download it, do a bunch of exercises, and then it likely sits on their hard drive untouched for a long time. This isn't a bad thing, and it does mean we can get away with introducing breaking changes on a smaller scale as long as it affects only a specific subsystem. Not many people are going to do an exercise, wait a year, update Rustlings, and then do the exact same exercise again.

Conclusion

So what's the actual takeaway from this? I guess it's that if you're designing software for teaching people, or just people that aren't software developers, consider thinking about their perspective when using your software before you blindly adhere to SemVer. Again, not saying SemVer is bad, but there have been some people that seem to believe adhering to SemVer is the best thing you can do in any situation, to which I disagree. I believe knowing who you're making software for is the best thing you can do in any situation.