CONTRIBUTING: remind about adding to config.json #495
Conversation
|
The exercises are typically added in order of difficulty. You might want to add a note about that. |
| @@ -337,6 +337,10 @@ The exercise should consist of, at minimum: | |||
| * A test suite | |||
| * A reference solution that passes the test (see [#reference-solution](#reference-solution)) | |||
|
|
|||
| You will need to add the exercise to `"exercises"` section of the `config.json` file in the track. | |||
| The order in which the exercises are listed there is the order in which they are fetched by default by `exercism fetch`. | |||
| Typically, exercises are ordered by difficulty, unless there is a particular reason to do otherwise. | |||
There was a problem hiding this comment.
I am hoping this sentence doesn't conflict with any track that may wish to specify a different ordering? I think it is true that in the steady state all tracks want to order their exercises by difficulty, but I seem to remember some track that requested its contributors put new exercises at the end of the track temporarily, and they'll move them to the right spot later after seeing how difficult it seems for students. But alas, I didn't note down what track that was and I do not seem to be able to find it...
There was a problem hiding this comment.
xruby puts new exercises at the end.
The reasoning being that new exercises may have weird errors or ambiguities, and it is better that these are encountered first by the (presumably more experienced) programmers who are working on the later problems, in the hope they will raise GitHub issues for them. Once they have a few successful solutions they can be moved to a more appropriate place in the order.
There was a problem hiding this comment.
It also isolates the discussion about where a particular problem fits in the order.
There was a problem hiding this comment.
Given this, it may not be safe for this document to make a blanket prescription on exercise ordering. I am considering three choices:
- Delete this line; do not replace.
- Delete this line; replace with "Please check with the track to which you are submitting an exercise for guidance on how to order the exercises".
- Append the above "Please check"... sentence to this line.
There was a problem hiding this comment.
☑️ 2 3
It's a good idea to document the typical ordering here.
There was a problem hiding this comment.
tentatively applying choice 3, since I also think it seems good to document what's typical, and since I think the main concern is with any tracks that wish to do differently, and if you like 3 I'll hope any others will as well.
| You will need to add the exercise to `"exercises"` section of the `config.json` file in the track. | ||
| The order in which the exercises are listed there is the order in which they are fetched by default by `exercism fetch`. | ||
| Typically, exercises are ordered by difficulty, unless there is a particular reason to do otherwise. | ||
| Please check with track to which you are submitting an exercise to see if they have any additional guidance on how to order their exercises. |
There was a problem hiding this comment.
Hmm. Now next question. Does this sentence seem redundant with the below "Each language track might have additional requirements"? Should I leave it as-is?
Or, I could combine them. "Each language might have additional guidance on how to order their exercises or additional requirements on new exercise files; check the README in the repository for the track"
There was a problem hiding this comment.
I honestly should have just done it when I asked since my personal opinion was "yes, it's redundant, I should combine them". Done now.
In various tracks, I sometimes see contributors forget to do this, and
perhaps one cause is that the requirement isn't mentioned here (various
tracks link to this document to explain how to port an exercise to their
track).
Luckily, this gets caught by configlet (assuming the track is running
Travis CI and hasn't removed configlet), but it would be good to let
contributors to know of this up front.
Decision: This text explcitly mentions the `"exercises"` key, rather
than the deprecated `"problems"` key.
The following procedure:
gem install trackler --ignore-dependencies
# substitute your Ruby version for $RUBY_VERSION
grep -L exercises ~/.gem/ruby/$RUBY_VERSION/gems/trackler-2.0.6.10/tracks/*/config.json
says that only two tracks lack the `exercises` key: Ceylon and PL/SQL
* a PR exercism/plsql#16 is open for PL/SQL
* a PR exercism/ceylon#8 has already been
merged in Ceylon and will go out in the next Trackler update.
Therefore, it almost certainly safe to use the `exercises` key!
One weakness is that this text doesn't explicitly mention the `slug` or
`difficulty` or `topics` keys for each entry in the `exercises` array.
This weakness is currently mitigated by the fact that active languages
should have many examples to go off of. The only time where there are no
examples will be when starting a brand-new track.
In various tracks, I sometimes see contributors forget to do this, and
perhaps one cause is that the requirement isn't mentioned here (various
tracks link to this document to explain how to port an exercise to their
track).
Luckily, this gets caught by configlet (assuming the track is running
Travis CI and hasn't removed configlet), but it would be good to let
contributors to know of this up front.
Decision: This text explcitly mentions the
"exercises"key, ratherthan the deprecated
"problems"key.The following procedure:
says that only two tracks lack the
exerciseskey: Ceylon and PL/SQLmerged in Ceylon and will go out in the next Trackler update.
Therefore, it almost certainly safe to use the
exerciseskey!One weakness is that this text doesn't explicitly mention the
slugordifficultyortopicskeys for each entry in theexercisesarray.This weakness is currently mitigated by the fact that active languages
should have many examples to go off of. The only time where there are no
examples will be when starting a brand-new track.