[Haskell] Concept exercise implementation guide

[ghost]

No description provided.

[ghost]

#55

[sshine]

Thanks for pushing on this.

• The current Haskell track repo uses Hpack, which means it distributes a package.yaml rather than a <NAME>.cabal file. Doing this we expect students to run stack test which then builds the .cabal file.

  This pull request appears to propose that we instead only distribute a .cabal file. While we could do that, perhaps this choice should be made in the Haskell track issue tracker so that pros and cons can be weighed.

• The current Haskell track repo has the property that every exercise directory is a project. This means that you can enter it and type stack test. For this property to hold with the proposed directory structure, the files stack.yaml and the project file (package.yaml or <NAME>.cabal) must be present in the exercise's root.

• The current Haskell track repo names the example solution file the same as the exercise, but places it in a separate directory. This means that the files examples/success-{foo, bar}/{package.yaml, src/<NAME>.hs} exist: Multiple sample solutions can exist, and the track repo's CI suite can test the examples by copying files.

  This pull request appears to propose that we instead name the example solution Example.hs. The drawback associated with naming it this is that we cannot re-use the test suite on the example solution, since the test suite contains a line like import <NAME> (...) which must be replaced with import Example (...) during CI.

  Another consequence of having only Example.hs is that we can only have one example solution per exercise, where the current track repo's directory structure allow both multiple examples in the form of success-foo, success-bar (example: bob), but also negative examples in the form of fail-erp, fail-derp (example: robot-name). We could consider simplifying this so that an exercise only allows for one (successful) example solution, but perhaps this choice should also be made in the Haskell track issue tracker so that pros and cons can be weighed.

If we move stack.yaml and package.yaml (or <NAME>.cabal) into the exercise directory to make it a project directory, and we decide to allow only one example per exercise and move the example into its own directory to also make it a project directory (although running the tests would necessitate copying files), and if there is no apparent need for an exercise-specific config.json (again, please enlighten me) (I was enlightened by @ErikSchierboom), then the directory structure might look like:

languages
└── Haskell
    └── concept
        └── <SLUG>
            ├── package.yaml
            ├── stack.yaml
            ├── src
            │   └── <NAME>.hs
            ├── test
            │   └── Tests.hs
            ├── .docs
            │   ├── after.md (optional)
            │   ├── hints.md
            │   ├── instructions.md
            │   └── introductions.md
            ├── .meta
            │   └── config.json (optional)
            └── example
                ├── package.yaml
                └── src
                    └── <NAME>.hs

That is, I can no longer find a need for the .meta directory, since hints are now located in .docs.

We use .meta in the current track repo for one other thing but I can only see that we have a single instance of that feature in use, so it may be something we wish to deprecate zero other things (as of exercism/haskell#891).

Let me know what you think about my proposed changes to the directory structure, and let me know which of the structural changes compared to the current track repo you wish to discuss on the Haskell issue tracker. In particular, I am fond of simplifying the examples to one-per-exercise.

[sshine]

I'm going to create some issues on the Haskell issue tracker discussing these, but I won't have time to create them until Thursday evening. Feel free to respond here and I might be able to get back before then.

[ghost]

Would be a good idea to merge for now, and then go back and edit it once you've reached a conclusion in the issue tracker on the Haskell track?

[sshine]

Yes, we can get back to the details.

I've left two comments on the last iteration that you can choose to react on.

[sshine]

What does the file .meta/<SLUG>.hs do?

This was not apparent between the previous review and the current.

[ghost]

It's the example solution. I'll add a note.

[ghost]

Or should it be <NAME>.hs?

[sshine]

If it's the example solution and the example solution should be compatible with the test suite without modifying the test suite, then yes, it should be <NAME>.hs. But as I also wrote in my first review, example solutions may draw on additional dependencies which necessitates that they have their own package.yaml. At this point we're probably better suited with, at minimum, a separate example/{package.yaml, src/<NAME>.hs} directory structure.

I don't think it's immediately clear that the difference between src/<NAME>.hs and .meta/<NAME>.hs is that one is the stub and the other is the example. Other tracks get away with naming the file [Ee]xample.*. Maybe we could, too, but it's not apparent to me how we can easily overcome the difficulties associated with testing under CI.

Whatever you pick for this pull request, we'll put it up for vote later.

Adding a note sounds good.

[sshine]

I've created exercism/haskell#892 and exercism/haskell#893 that address the loose ends between our current track and the present pull request's implicit choices. Feel free to merge this pull request and we can submit revisions that adjust it to our current defaults or whatever outcome a discussion might have.

[ErikSchierboom]

@sshine Cool, thanks! I've merged the PR.