Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[v3] Update Practice Exercises to latest spec #459

Merged
merged 6 commits into from
Feb 12, 2021

Conversation

ErikSchierboom
Copy link
Member

This week we've defined what the file structure looks like for Practice Exercises. Please skim through this docs PR that gives an overview of the changes, and see the spec for more information.

This PR applies changes to the track to conform to the latest spec. Each change is made as a separate commit, to help with reviewing. When merging this PR, I would suggest to not squash this to preserve the individual commits.

As having this PR merged is essential to prepare this track for Exercism v3, we'll automatically merge this PR one week after it was opened (if it hasn't been merged already).

Here are the changes made:

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 in: TwoFer, Leap, etc`
  • prerequisites: The actual Concepts that should have been learnt by a student in order for them 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.

We have updated the docs with more details and explanation on this.

Remove README.md files

v3 Practice Exercises won't have 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 for more information.

This PR removes the README.md files.

Create instruction from prob-specs descriptions

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 version will add support for doing this syncing automatically.

This PR adds the .docs/instructions.md file from the problem-specifications exercise's description.md file.

Move .meta/hints.md to .docs/instructions.append.md

As noted above, v3 Practice Exercises will have a .docs/instructions.md and optionally a .docs/introduction.md file.

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

This PR renames any .meta/hints.md files to .docs/instructions.append.md.

Create .meta/config.json files

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).

This PR adds the .meta/config.json file.

The contents of this file are temporary, and we'll submit follow-up PRs to update their values:

  1. The authors and contributors will be inferred from the Exercise's git history.
  2. As the Exercise files for most tracks are very regular, we're working on a solution that will allow you to define the pattern in your tracks's config.json file, and then use configlet to generate the contents of the files property in the exercise's .meta/config.json file based on the track-defined pattern.

Tracking

exercism/v3-launch#16

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 in: TwoFer, Leap, etc`
- `prerequisites`: The actual Concepts that should have been learnt by a student in order for them 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.

We have updated [the docs](https://github.com/exercism/docs/blob/master/anatomy/tracks/practice-exercises.md#practices) with more details and explanation on 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.
Copy link
Member

@iHiD iHiD left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We are now merging this PR automatically so that we can continue to script further bulk-PRs to help you. Merging this PR will also help prepare your track for Exercism v3 and fix some configlet lint errors.

@iHiD iHiD merged commit 37cb9b1 into exercism:main Feb 12, 2021
@ErikSchierboom ErikSchierboom added the x:size/tiny Tiny amount of work label Oct 27, 2021
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
x:size/tiny Tiny amount of work
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants