Add exercise's version to package.yaml and remove redundant information

[rbasso]

Rationale

As discussed earlier, it may be a good idea to have the exercise's implementation version in the package.yaml files. There are a few reasons to do that:

• It will allow us to version the exercises.
• It will be displayed to the users when running the tests.
• It will allow us to check it against the canonical-data.json versions, signaling when there is new test data. Ensuring we are up to date with x-common #416

How would it look like?

exercises/leap/package.yaml

name: leap
version: 1.0.0.1
...

Running the tests would give something like this:

leap-1.0.0.1: test (suite: test)


year not divisible by 4: common year
year divisible by 4, not divisible by 100: leap year
year divisible by 100, not divisible by 400: common year
year divisible by 400: leap year

Finished in 0.0001 seconds
4 examples, 0 failures

Suggested changes

• Add the version to the main package.yaml of each exercise:

  • All exercises must have a four-digits version: MAJOR.MINOR.PATCH.SERIAL

  • Exercises based on a non-versioned canonical-data.json should use version 0.9.0.1. If there is a comment containing the date from the data file used as a reference, it should be added to the YAML file, to ease transition, like this:

    name: all-your-base
    version: 0.9.0.1 # 2016-06-29

  • Exercises based on a versioned canonical-data.json should use its version plus a serial number, without any comment.

  • Exercises not following a canonical-data.json should use 0.1.0 plus a serial number, without any comment.

  • The serial number must start at 1 and always increase a unit when changed, regardless of the changes in the other version numbers.

  • The package.yaml files in the example solutions should not be versioned, because it would be too hard to keep them synchronized.

• Remove redundant data from the test suites:
  • Keep comments describing the divergences from x-common.
  • Remove references to the canonical-data.json files and version.
  • Remove the test group containing the name of the exercise, if existent, because this information is already displayed with the version when running the test suite. (edit: as pointed out by @petertseng, this change doesn't belong here) 👍
• Update the documentation to include the new versioning system.

Should we do it?

This will take time and demand some work, so we shouldn't start unless the @exercism/haskell maintainers agree with it.

So... Objections? Comments?

Edit: Approved!

---

Progress

• Check if we have a consensus about it.
• Add the versions to the package.yaml files and remove them from the test suite.
• Open an issue to update the documentation
• Open issues for the unsolved items in the Future work section

Future work

Other ideas and problems with the exercises discovered in the process.

• Fix/remove change group name. change: Remove test groups not matching x-common #539

• Remove the test group containing the name of the exercise, if existent, because this information is already displayed with the version when running the test suite. all: Remove test group with the exercise's name #540

• Write a app/script to check for newer test data versions. I have a proof-of-concept in Haskell mostly ready, but I think we should wait until we finish this issue.

  Update: We already have two programs to solve that.

[abo64]

I like it.

One question: Why do you want the serial number to increase regardless of the other version numbers and not reset it when the latter change?

[rbasso]

Using a serial we get a x-common-independent versioning for the Haskell exercises for free. If in the future x-common changes or removes its versioning, we'll be able to extract a local version easily.

It also solves the following question:

What happens if an exercise decides to not follow x-common anymore?

Without the serial, it could happen that two distinct versions would share exactly the same number, e.g.: 0.1.0.1 -> 2.3.5.1 -> 0.1.0.1.

[petertseng]

I like all the suggestions.

Exercises based on a non-versioned canonical-data.json

Was confused at this since all current JSON files have a version, but figured out that it means a JSON file from before that time. Understood 👍 .

Remove the test group containing the name of the exercise, if existent, because this information is already displayed with the version when running the test suite.

Sure, though feel free to do that as a separate round of changes, or at least put in separate commit (I think there will be a lot of whitespace change that happens as a result), since the change can be made independently of adding versions.

[rbasso]

I have updated the description a little restricting the scope of this issue, @petertseng.

Considering that this work has some economies of scale, I'll assign it to myself and I expect to finish it in a few days.

[petertseng]

As I revealed in #524 , I do have a small script to compare versions, but it's not written in Haskell so I'll defer to the upcoming code that is in Haskell. But until it comes feel free to take a look at https://github.com/petertseng/x-common/blob/up-to-date/up-to-date/haskell.rb

[rbasso]

My Haskell draft is in this link, but it is far from being production quality at the moment. I'm working on it, like if it where an exercise. 😄

Feel free to add you ruby script if you want too. 👍

[rbasso]

My updated version of the program to check for newer exercise data is in https://github.com/rbasso/xhaskell-check-versions.

It certainly is not as short, flexible and maintainable as @petertseng's solution, but it is now a working, type-safe, over-engineered laser cannon to shoot a dead fly. 😆

It was fun to write it, but I prefer the ruby script!

[rbasso]

I guess that my original objective with this PR is complete, so I'm closing it.

[petertseng]

Updates to this version policy:

The 0.9.0 will no longer be used since all canonical-data.json have a version, and it's enforced in the schema that they all will have versions henceforth. Only remaining 0.9.0 is in deprecated exercise binary, which won't be updated, but no new version should need to use 0.9.0.

I will finally document this.