README: Add README related .meta/ file description #846
Conversation
General overhaul of the file structure section of the README. Added the .meta/ files related to the README generation. More explanation of the .meta files relationship to the problem-specifications repo. Some more detail of the role of the `meta/gen.go` file.
There was a problem hiding this comment.
The changes look good.
One other item. Since gen/gen.go already has been updated to reference problem-specifications/canonical-data.json it seems the "## Generating test cases" section needs x-common changed to be problem-specifications. You may already have that in the works.
|
Good catch, it is outdated across the README! |
There was a problem hiding this comment.
This is a really necessary update to the README @tleen, thanks for clarifying this stuff. I've just got some readability suggestions.
README.md
Outdated
| Let's walk through the `leap` exercise to see what is included in an exercise | ||
| implementation. Navigate into the *leap* directory, you'll see there are a | ||
| number of files there. | ||
| Let's walk through the an imaginary `exercise-slug` exercise to see what is included in an exercise |
There was a problem hiding this comment.
Let's walk through the an imaginary
Though I think using exercise-slug confuses the issue, as it's assumed readers will know what it means, it's like assuming everyone knows what foo and bar are all about. Perhaps something like
Let's walk through an example, non-existent, exercise, which we'll call fizzbuzz to see what could be included in it's implementation.
Or something along those lines?
README.md
Outdated
| * **example.go** - This is a reference solution for the exercise. This file is | ||
| ignored by the `exercism fetch` command. See [ignored files](#ignored-files) for | ||
| details on which files are ignored. | ||
| This list of files *can vary* across exercises. Not all exercise |
There was a problem hiding this comment.
s/Not all exercise/Not all exercises
README.md
Outdated
| ignored by the `exercism fetch` command. See [ignored files](#ignored-files) for | ||
| details on which files are ignored. | ||
| This list of files *can vary* across exercises. Not all exercise | ||
| utilize all of the available files, but they are available for use |
There was a problem hiding this comment.
s/utilize all of the available files, but they are available for use/utilize all of these files, but they are available for use
README.md
Outdated
| all tracks. However, should local track-specific modifications or | ||
| enhancements be made with respect to the global problem specifications | ||
| they may be performed by the presence of specifically named files in | ||
| an exercises `.meta/` directory. |
There was a problem hiding this comment.
These paragraphs are a little unclear.
Not all exercises use all of these files. Exercises originate their test data from the Exercism problem-specification repository. This repository collects common information for all exercises across all tracks.
However, should track-specific documentation need to be included with the exercise, files in an exercise's .meta/ directory can be used.
README.md
Outdated
|
|
||
| * **leap.go** - This is a *stub file*, and will only be present in some exercises. | ||
| So let's quickly run through each potential file and briefly describe |
There was a problem hiding this comment.
I think the use of the word potential is unnecessary here.
README.md
Outdated
|
|
||
| * **leap.go** - This is a *stub file*, and will only be present in some exercises. | ||
| So let's quickly run through each potential file and briefly describe | ||
| what and why it is. |
There was a problem hiding this comment.
I think this can be replaced with it; briefly describe what and why it is. -> briefly describe it.
README.md
Outdated
| represent test data sourced from the problem-specifications repository. | ||
|
|
||
| * **example.go** - This is an [example solution](#example-solutions) for | ||
| the exercise. It is used in integration testing and to provide a |
There was a problem hiding this comment.
It is used in integration testing - is it?
Maybe: It is used ensure the test suite is correct, and to provide a reference solution to the exercise.
There was a problem hiding this comment.
Yep it is used to make sure the test suite passes the Travis build.
README.md
Outdated
| * **.meta/gen.go** - This file, unique within the `.meta` directory, | ||
| generates the *cases_test.go* file, and will only be present in some | ||
| exercises should they have problem-specification test data and this | ||
| generator is present to to utilize it. See [generating test cases](#generating-test-cases) |
There was a problem hiding this comment.
This could be split for readability:
and will only be present in some
exercises should they have problem-specification test data. This
generator is present to to utilize it.
README.md
Outdated
| for more information. | ||
|
|
||
| * **.meta/hints.md** - This is another README related file, it should | ||
| used for the inclusion of any track specific information beyond what |
There was a problem hiding this comment.
s/it should used for the inclusion/it should be used for the inclusion
General overhaul of the file structure section of the README. Added
the .meta/ files related to the README generation. More explanation of
the .meta files relationship to the problem-specifications repo. Some
more detail of the role of the
meta/gen.gofile.