Rustlings 2.0 and human-centered versioning
Today we released [Rustlings
2.0](
https://github.com/rust-lang/rustlings/releases/tag/2.0.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](
https://github.com/jrvidal) 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](
https://semver.org/), 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.
tags: rustlings, oss
