CONTRIBUTING: Explain reasons for track dependencies on this repo #1406
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
petertseng
commented
Nov 24, 2018
CONTRIBUTING.md
Outdated
| Reference the PR in problem-specifications. | ||
| 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: | ||
| * If changes are suggested to the problem-specifications PR, it's highly likely that they will be applicable to the track-specific PR as well. | ||
| * 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. |
petertseng
commented
Nov 24, 2018
CONTRIBUTING.md
Outdated
| 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: | ||
| * If changes are suggested to the problem-specifications PR, it's highly likely that they will be applicable to the track-specific PR as well. | ||
| * 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. | ||
| * 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 unpredictably if the exercise does not exist in problem-specifications yet. 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. |
There was a problem hiding this comment.
as you can see, it is my attempt to make the #1384 general. I definitely think track-specific tools deserve a mention, though exactly what the tools are has to be documented by the individual tracks.
rpottsoh
reviewed
Nov 25, 2018
|
I'm still reviewing... I'll post a comment when I am done. |
rpottsoh
reviewed
Nov 25, 2018
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.
rpottsoh
approved these changes
Nov 25, 2018
|
It is likely that I will merge this in 52 hours, at which 72 hours will have passed since I submitted this PR. |
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.
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.