[v3] Update Practice Exercises to latest spec #133
Closed
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Practice Exercises in Exercism v3 will have a `.meta/config.json` file that contains exercise-specific information like the names of the solution, test and example file(s). The `.meta/config.json` file will also contain any source information as defined for the corresponding problem-specifications exercise (if any). See [the spec](https://github.com/exercism/docs/blob/main/anatomy/tracks/practice-exercises.md) for more information.
Practice Exercises in Exercism v3 will be structured differently. One such change is that there won't be a (generated) README.md file anymore. This file will be replaced by `.docs/instructions.md` and optionally a `.docs/introduction.md` files. These files are copies of the information defined for their corresponding problem-specifications exercise (if any). Exercism v3 will build the README.md file that is sent via the CLI from these files contents, along with some other files. See [this document](https://github.com/exercism/docs/blob/main/anatomy/tracks/presentation.md) for more information. To add track-specific contents to the instructions and/or introduction, exercises can define the (optional) `introduction.append.md` and `instructions.append.md` files. If present, the contents of these files will automatically be append to their corresponding file when generating the README.md See [the spec](https://github.com/exercism/docs/blob/main/anatomy/tracks/practice-exercises.md) for more information.
Practice Exercises in Exercism v3 will be structured differently. One such change is that there won't be a (generated) README.md file anymore. This file will be replaced by `.docs/instructions.md` and optionally a `.docs/introduction.md` files. These files are copies of the information defined for their corresponding problem-specifications exercise (if any). Exercism v3 will build the README.md file that is sent via the CLI from these files contents, along with some other files. See [this document](https://github.com/exercism/docs/blob/main/anatomy/tracks/presentation.md) for more information. See [the spec](https://github.com/exercism/docs/blob/main/anatomy/tracks/practice-exercises.md) for more information.
While working on adding prerequisites to the Practice Exercises, we found that we really need two keys for Practice Exercises: - practices: Concepts that the Practice Exercise is actively helping a student to practice. These show up in the UI as "Practice this Concept using in: TwoFer, Leap, etc` - prerequisites: The actual Concepts that should be taught in order for a student to be able to do that Exercise. There are lots of advantages to having the two keys instead of using one key for two purposes, not least that having them split out gives the maintainers a lot more control over the order a student should be exposed to exercises (via the prerequisites) and also where they encourage them to try concepts (via practices), which in reality are quite different things. The downside is that there will be a lot of duplication between the two and that that might be (or feel like) extra work for maintainers, but we feel free the net gain is worth this.
Practice Exercises in Exercism v3 will be structured differently. One such change is that there won't be a (generated) README.md file anymore. This file will be replaced by `.docs/instructions.md` and optionally a `.docs/introduction.md` files. These files are copies of the information defined for their corresponding problem-specifications exercise (if any). The `.docs/instructions.md` file is a copy of the `instructions.md` file of the problem-specifications exercise, or if that does not exists, its `description.md` file. The new [configlet](https://github.com/exercism/configlet) version will add support for doing this syncing automatically. See [the spec](https://github.com/exercism/docs/blob/main/anatomy/tracks/practice-exercises.md) for more information.
Source information for Practice Exercises will be stored in their `.meta/config.json` file, in the (optional) `source` and/or `source_url` properties. This commit adds the source information from the corresponding problem-specifications exercise to the `.meta/config.json` file. The new [configlet](https://github.com/exercism/configlet) version will add support for doing this syncing automatically. Exercism v3 will automatically include the source information in the README.md file that is sent via the CLI using the source properties in the `.meta/config.json` file. See [the spec](https://github.com/exercism/docs/blob/main/anatomy/tracks/practice-exercises.md) for more information.
All Markdown files should, from this point on, start with a level one heading. See exercism/configlet#150 (comment) for the rationale of these changes. The full specification can be found [here](https://github.com/exercism/docs/blob/main/contributing/standards/markdown.md).
ErikSchierboom
changed the title
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
We've made some changes to the v3 spec this week, most notably we've defined what the file structure looks like for Practice Exercises. See the spec for more information.
This PR applies changes to the track to conform to the latest spec. It applies the following changes:
Add practices field to Practice Exercises
While working on adding prerequisites to the Practice Exercises, we found that we really need two keys for Practice Exercises:
practices: Concepts that the Practice Exercise is actively helping a student to practice. These show up in the UI as "Practice this Concept using in: TwoFer, Leap, etc`prerequisites: The actual Concepts that should be taught in order for a student to be able to do that Exercise.There are lots of advantages to having the two keys instead of using one key for two purposes, not least that having them split out gives the maintainers a lot more control over the order a student should be exposed to exercises (via the prerequisites) and also where they encourage them to try concepts (via practices), which in reality are quite different things.
Remove README.md files
v3 Practice Exercises won't have a (generated) README.md file anymore.
This file will be replaced by
.docs/instructions.mdand optionally a.docs/introduction.mdfiles.These files are copies of the information defined for their corresponding problem-specifications exercise (if any).
Exercism v3 will build the README.md file that is sent via the CLI from these files contents, along with some other files.
See this document for more information.
This PR removes the
README.mdfiles.Create instruction from prob-specs descriptions
The
.docs/instructions.mdfile is a copy of theinstructions.mdfile of the problem-specifications exercise, or if that does not exists, itsdescription.mdfile.The new configlet version will add support for doing this syncing automatically.
This PR adds the
.docs/instructions.mdfile from the problem-specifications exercise'sdescription.mdfile.Move .meta/hints.md to .docs/instructions.append.md
As noted above, v3 Practice Exercises will have a
.docs/instructions.mdand optionally a.docs/introduction.mdfile.To add track-specific contents to the instructions and/or introduction, exercises can define the (optional)
introduction.append.mdandinstructions.append.mdfiles. If present, the contents of these files will automatically be append to their corresponding file when generating the README.mdThis PR renames any
.meta/hints.mdfiles to.docs/instructions.append.md.Create .meta/config.json files
Practice Exercises in Exercism v3 will have a
.meta/config.jsonfile that contains exercise-specific information like the names of the solution, test and example file(s).The
.meta/config.jsonfile will also contain any source information as defined for the corresponding problem-specifications exercise (if any).This PR adds the
.meta/config.jsonfile.Level one headings in Markdown files
All Markdown files should, from this point on, start with a level one heading.
See exercism/configlet#150 for the rationale of these changes.
The full specification can be found here.
This change is not strictly related to the Practice Exercises, but I've included it in this PR as there are file renames in this PR and having two separate PRs would lead to merge conflicts.