Skip to content

Commit ad6fd6a

Browse files
authored
CONTRIBUTING: Explain reasons for track dependencies on this repo (#1406)
History ======= When discussing creating a new exercise, there's the question of any timing dependencies between the problem-specifications repo and the track-specific repos. Recall that it was once required that the problem-specifications PR be merged first, because READMEs are generated; if the problem specification did not exist, the README generation would fail and the student experience would be negatively impacted. Since exercism/meta#15, READMEs are no longer generated but included in the track-specific repos, so the absolute dependency ("must not") no longer applies. Discussed in #1384 Change and motivation ===================== Change the "must not" to a suggestion. I've written down all reasons known to me that a contributor should wait to merge a track-specific PR. Knowing why a suggestion exists is necessary to understand when it is and is not okay to ignore the suggestion. Demonstration that this is safe =============================== I present empirical proof that there is no longer any dependency: I have arbitrarily selected an exercise that does not have a corresponding problem-specifications directory and does not have description.md nor metadata.yml in its .meta directory: https://github.com/exercism/ballerina/tree/master/exercises/hello-world-service To the existing tooling, this is indistinguishable from an exercise for which the track-specific PR was merged before the problem-specifications PR. I have personally confirmed that I can join the track, download this exercise, read the README, implement a solution, and submit this solution.
1 parent b9d47c6 commit ad6fd6a

File tree

1 file changed

+5
-2
lines changed

1 file changed

+5
-2
lines changed

CONTRIBUTING.md

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -234,8 +234,11 @@ A problem must have a unique slug. This slug is used as
234234

235235
* Do the same as when [porting an
236236
exercise](#porting-an-exercise-to-another-language-track).
237-
Reference the PR in problem-specifications if it hasn't been merged yet,
238-
this **must not** be merged until the exercism/problem-specifications PR is merged.
237+
Reference the PR in problem-specifications.
238+
It's suggested, but not required, to wait until the problem-specifications PR is merged before merging the track-specific PR, for the following reasons:
239+
* If changes are suggested to the problem-specifications PR, it is likely that they will be applicable to the track-specific PR as well.
240+
* Only applicable if the exercise needs a custom `title` in metadata.yml (as described in https://github.com/exercism/docs/blob/master/you-can-help/make-up-new-exercises.md#problem-specification): The title of the exercise as displayed on the website will use the default algorithm instead of the correct title until the problem-specifications PR is merged.
241+
* Only applicable to tracks that have specific tools that depend on exercises being present in problem-specifications (see the track-specific documentation for whether any such tools exist): Such tools may operate unexpectedly if the exercise does not yet exist in problem-specifications. Try checking out the branch on a local copy of problem-specifications or rerunning the tool after the problem-specifications PR is merged if applicable.
239242

240243
## Track Anatomy
241244

0 commit comments

Comments
 (0)