exercism / problem-specifications

Shared metadata for exercism exercises.
MIT License
326 stars 541 forks source link

How should a track maintain its track-specific deletions from a problem's description? #2077

Open petertseng opened 2 years ago

petertseng commented 2 years ago

Recall that if a track wishes to have track-specific additions to a problem's description it can easily do so with .docs/instructions.append.md (some of you may know this file as HINTS.md).

I don't recall any similar mechanism for track-specific deletions from a problem's description. If there is one, please educate me. If there isn't, let's talk.

If you need a specific case where a track might want something like this, take a look at https://github.com/exercism/problem-specifications/blob/main/exercises/bowling/description.md, where it lists two specific functions roll and score. These functions don't make sense for a language that isn't object-oriented so instead such a language will just use one function score(rolls: array[int]) -> result[error, int] or similar. So they have to delete everything under the Requirements section.

Possibilities that I think are suboptimal:

Now, we might not need an organisation-wide solution to this if demand is low. If there's only one or two tracks that need this, they can just come up with their own tooling and share amongst themselves as needed.

I'm sort of already preparing for that possibility, I guess. My general idea is that I'd just keep a .diff file with the changes from problem-specifications's description.md. Then future syncs from problem-specifications will copy the description.md and apply the diff. Seems simple enough that I think I might just go ahead with this solution. But I'm just checking to see if there is any demand for something like this elsewhere.

glennj commented 2 years ago

This is probably more apropos for the configlet repository. Perhaps place a .keep.docs file in the exercise's .docs directory. That can inform configlet to not sync the exercise's docs.

kotp commented 2 years ago

If we are looking at file name, then .lock might be a good name for this.

BethanyG commented 2 years ago

I'd love a mechanism to track deletions in instructions. Right now, we are using the "confuse the student" route where we put in addendums that sometimes contradict or re-explain things. I'd rather be able to track both adding and removing bits.

a .config/l.ock/.keep docs in .docs/ feels like it it would be a fairly non-fussy way to do it. Maybe with the problem specs version (or a diff) also in the directory or noted in the .config? Just as an additional reminder that that particular instruction set has changed.