Add exercise's version to package.yaml and remove redundant information
rbasso opened this issue Β· comments
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. #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) π
- Keep comments describing the divergences from
- 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. #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. #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.
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?
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
.
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.
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.
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
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. π
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!
I guess that my original objective with this PR is complete, so I'm closing it.
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.