Document practice exercise files

[ErikSchierboom]

In this PR, we're documenting the documents that make up a practice exercise. The old v2 style of practice exercise documents will be replaced with a newer style that closely mimics the concept exercises structure. These changes will allow us to deliver a customised experienced to the user depending on whether they are using the CLI or the Online Editor. Here is a short summary of the changes:

• The README.md document of practice exercises will be removed. It will be replaced with a .meta/instructions.md document, with optional .meta/introduction.md and .meta/hints.md documents.
• Practice exercises will support hints through the .docs/hints.md document, but only general hints (we don't have tasks for practice exercises).
• The description.md document of Problem Specification exercises will be removed. It will be replaced with an instructions.md document, and optionally an introduction.md document. The goal here is to separate the introduction from the instructions, which can help in adding language-specific additions (more on that later).
• The .meta/instructions.md and (optional) .meta/introduction.md documents of a practice exercise should be direct copies of the corresponding Problem Specifications exercise's files. configlet will support automatically syncing the contents of these files.
• The existing .meta/hints.md document will be replaced by .docs/instructions.append.md and/or .docs/introduction.append.md. The contents of these files will automatically be appended to the instructions and/or introduction.
• Practice exercises will get a .meta/config.json file, which is almost identical to the concept exercise version, except for the forked_from property which does not apply to practice exercises.
• .meta/config.json files will have two new, optional properties: source and source_url. These replace the existing source.md document for concept exercises (which was only used a couple of times). For practice exercises, configlet will automatically sync these values to the values defined in the practice exercise's metadata.yml file.
• The exercises/shared/docs directory will have three files: debug.md (explaining the in-browser "debug: options), help.md (track-specific help information, like a link to a gitter channel) and tests.md (how to run the tests).
• Exercises can overwrite the shared docs by creating identically named files in their .docs directory (this should be an exceptional use case).
• There will be two Exercism-wide files: cli.md (how to use the CLI) and help.md (for Exercism-specific help instructions)
• Practice Exercise example files should be moved to the .meta directory.

I've documented the practice exercise files, added documentation on the shared files (both track- and Exercism-specific) and added a document showing how the various files all interact and what the end result is (WIP).

[ErikSchierboom]

I've now made it explicit per file if the file is required or optional

[ErikSchierboom]

Introducing these headings allows linking to a specific type of file.

[ErikSchierboom]

These files were missing from the list

[ErikSchierboom]

I've added this field to make it explicit if the field is required without having to consider any of the other text in this document.

[iHiD]

That's a great decision.

[ErikSchierboom]

This file will be replaced by two new fields in the .meta/config.json file. There were only a couple of usages of this file, so migrating should not be an issue.

[ErikSchierboom]

These are the new fields to describe the source of an exercise. They match the names used in prob-specs metadata: https://github.com/exercism/problem-specifications/blob/main/exercises/zebra-puzzle/metadata.yml

[ErikSchierboom]

This refers back to the new files key in the .meta/config.json file.

[ErikSchierboom]

I added this for consistency with concept exercises and because it can be used to document certain design decisions.

[ErikSchierboom]

The goal of this document is to help explain how documents end up being presented to the student.

[iHiD]

I think we'll need a clearer name for this, but I can't think of one off hand.

[BethanyG]

Is display or student_display any clearer?

[ErikSchierboom]

🤷

[ErikSchierboom]

I'm gonna merge this PR and we can come up with a better name later.

[coriolinus]

• The README.md document of practice exercises will be removed.

Love it! Syncing the README has been a continuous pain point for new contributors to Rust.

• The ... documents of a practice exercise should be direct copies of the corresponding Problem Specifications exercise's files. configlet will support automatically syncing the contents of these files.

It's not clear to me what benefit there is in requiring synchronization for these files. Obviously for exercises which do not exist in the problem specifications, we need to provide exercise-specific files, but for exercises which should stay synced with the specifications, I feel that a rule like "Omitting these files will cause the website renderer to automatically fetch the appropriate one from the problem-specifications repo" would be better for usability.

• Practice exercises will get a .meta/config.json file

Really not a fan of this being mandatory; it feels a lot like busywork, especially when backfilling large numbers of practice exercises.

authors and contributors can largely be extracted from git log. files is a pattern which can be set at the track-level config.json level and will be largely duplicated per exercise. (It also doesn't appear to be able to handle additional files which aren't example, test, or solution, but pre-implemented modules for the student's benefit. Ex: rust/exercises/practice/doubly-linked-list/src/pre_implemented.rs.)

[angelikatyborska]

I beg you not to do this for practice exercises 😭 we would need to go through git history for 100 exercises to figure out for each who authored them.

[iHiD]

Agree. How about we make it optional. I do want it there so people can have that credit, but the work involved to go back through old exercises does feel prohibitive for it being required.

[ErikSchierboom]

I beg you not to do this for practice exercises 😭 we would need to go through git history for 100 exercises to figure out for each who authored them.

It sounds like I should be able to do this via a script, right?

[angelikatyborska]

I don't know. How would you do it? Would you choose a single file from an exercise and find the author of the commit that adds that file? Which file would it be? Would it be guaranteed to detect renaming and moving the file around? We changed all the paths in all the exercises once when migrating from Elixir scripts to mix projects. I need to use my IDE's git plugin to correctly track changes to a file, GitHub for example doesn't understand moving files 🙄. And would that really mean that is the real author of the exercise?

Let's take queen-attack for example. This is the commit where it was authored by dalexj: exercism/elixir@5648c33 None of the files exists anymore under the same path as they were created. And its README seems to have been created later, by Katrina exercism/elixir@400cfe5 When you ask GitHub for the history of the file directory, it only shows the v3 big bang commit: https://github.com/exercism/elixir/commits/fb333fcb94501082b0d174c949d85bc15bfdbc5c/exercises/practice/queen-attack

[ErikSchierboom]

Actually, I think we must do this via a script. There are so many practice exercises implemented and it would be fantastic to attribute them to users.

[ErikSchierboom]

@angelikatyborska That is due to GitHub not using the --follow command for the log. See the following console output for the log of the exercises/practice/wordy/README.md file in the Elixir repo.

Without --follow:

erik@VELPIE:~/elixir$ git log exercises/practice/wordy/README.md
commit fb333fcb94501082b0d174c949d85bc15bfdbc5c
Author: Erik Schierboom <erik_schierboom@hotmail.com>
Date:   Fri Jan 29 14:37:47 2021 +0100

    [v3] Move existing exercises to exercises/practice

With --follow:

commit fb333fcb94501082b0d174c949d85bc15bfdbc5c
Author: Erik Schierboom <erik_schierboom@hotmail.com>
Date:   Fri Jan 29 14:37:47 2021 +0100

    [v3] Move existing exercises to exercises/practice

commit 7de06dd889c4be1f0bb47f2cadf723ad38e7a201
Author: Cohen Carlisle <cohencarlisle+github@pm.me>
Date:   Sun Jul 28 20:43:09 2019 -0400

    fix old test docs in readmes

commit 432813834b2c09a4a2ed8cf31d36a77b3e3f9ba1
Author: Devon Estes <devon.c.estes@gmail.com>
Date:   Wed Aug 15 11:34:36 2018 +0200

    Run configlet to update READMEs of exercises

....

[iHiD]

It's not clear to me what benefit there is in requiring synchronization for these files. Obviously for exercises which do not exist in the problem specifications, we need to provide exercise-specific files, but for exercises which should stay synced with the specifications, I feel that a rule like "Omitting these files will cause the website renderer to automatically fetch the appropriate one from the problem-specifications repo" would be better for usability.

The fundamental reason is that track repos are "live", whereas problem-specs is not. When a track repo is updated the website syncs it immediately. It is effectively automatically deployed. Problem-specs is instead a reference repo. Tracks may be out of date with it (in fact, most tracks are out of date with prob-specs). Further, it is important that tracks have the ability to keep their content out of sync with problem-specs until they deliberately choose to update, else their tests etc might become out of sync with the docs in problem-specs.

I think it is also harder to work on an Exercise in a language if some of the files that comprise it live in another repo. Having to have problem-specs open next to it seems to be to be a harder and more complicated way of doing things, than using CI to copy things to the right places, but I appreciate that maybe this is a preference rather than a solid rule.

Really not a fan of this being mandatory; it feels a lot like busywork, especially when backfilling large numbers of practice exercises.

Understood. We do need it for the files though. We discussed this lot during the v3 process and decided that we want to hardcode this everywhere. This allows us to do things like letting students do exercism submit without having to specify filenames on the CLI and know that the are only uploading the file they intend (as opposed to others they might have created inadvertently, etc). We will also need it for the source (or we'd have to copy that over in some other way)

For existing tracks/exercises we should be able to automatically script this, and I know that Julia has already added the automatic generation of this file to their Concept Exercises based off centralised track-data via CI, so a similar thing might be possible for Practice Exercises in general moving forward. (e.g. You could have a regexp pattern that you run your exercise against to determine the correct values for the files).