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

[petertseng]

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:

• No support for track-specific deletions. Just use the existing append functionality and have it say something like "Disregard the above text, actually do this instead"
  • My commentary: confusing to students.
• The track just modifies their copy of instructions.md appropriately.
  • My commentary: bad for maintainers. Then future changes in problem-specifications have to be manually reconciled. I cannot accept that.

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]

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]

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

[BethanyG]

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.