Who/what shall be responsible for ensuring that README.md exists for each exercise? Configlet or individual tracks? #200

petertseng · 2017-10-12T19:43:22Z

Since exercism/meta#15, README.md is present in each track's individual exercise implementation.

First, the discussion will assume the premise that it is desirable that this README.md in fact be present.

We would like students to receive a README.md when they fetch an exercise.
We would like pages like http://exercism.io/exercises/c/hello-world/readme to have content.

Trackler is OK with the README.md being missing: See https://github.com/exercism/trackler/blob/master/lib/trackler/implementation.rb#L51. The README is assembled in the old fashion.

I was under the impression that Nextercism would not be OK with the README.md being missing. https://github.com/exercism/prototype/blob/master/app/models/exercise.rb#L37 uses a description from the database and I might assume that the database field is only populated via the README.md from the repo, and not the README assembled in the old fashion. I have no basis for this assumption so the chance of it being wrong is very high.

If it will be required to have the README.md, where shall it be checked?

configlet checks it.
Each track is responsible for adding a check to its own CI.
Each reviewer of a PR adding new exercise implementations must check that it is present.
Your suggestion here.
They aren't required. This has all been a big misunderstanding on my part.

Smarticles101 · 2017-10-13T01:16:45Z

I vote option 1.

I think it's a good idea for configlet to check for it because every track already uses configlet in the CI to check that the config.json is in order. Option 2 would cause more work to be done than necessary, and option 3 would cause even more work to be done and a missing readme could easily be overlooked by a maintainer.

ferhatelmas · 2017-10-13T07:06:45Z

Reasoning by @Smarticles101 seems very logical to me and I couldn't come up with a better suggestion as option 4 so I also vote for option 1.

ilya-khadykin · 2017-10-13T10:27:56Z

I guess this validation should be part of configlet lint command, so I'm in favor of Option 1

petertseng · 2017-10-13T23:13:32Z

And, what exercises are missing READMEs?

gems/trackler-2.2.1.45$ for d in tracks/*/exercises/*/; do if [ ! -f $d/README.md ]; then echo $d; fi; done
tracks/bash/exercises/error-handling/
tracks/cfml/exercises/acronym/
tracks/cfml/exercises/atbash-cipher/
tracks/cfml/exercises/bob/
tracks/cfml/exercises/diamond/
tracks/cfml/exercises/difference-of-squares/
tracks/cfml/exercises/flatten-array/
tracks/cfml/exercises/gigasecond/
tracks/cfml/exercises/grains/
tracks/cfml/exercises/hamming/
tracks/cfml/exercises/hello-world/
tracks/cfml/exercises/isogram/
tracks/cfml/exercises/largest-series-product/
tracks/cfml/exercises/luhn/
tracks/cfml/exercises/markdown/
tracks/cfml/exercises/nth-prime/
tracks/cfml/exercises/pangram/
tracks/cfml/exercises/pig-latin/
tracks/cfml/exercises/raindrops/
tracks/cfml/exercises/rna-transcription/
tracks/cfml/exercises/saddle-points/
tracks/cfml/exercises/scrabble-score/
tracks/cfml/exercises/secret-handshake/
tracks/cfml/exercises/space-age/
tracks/cfml/exercises/sum-of-multiples/
tracks/cfml/exercises/triangle/
tracks/cfml/exercises/word-count/
tracks/csharp/exercises/complex-numbers/
tracks/dart/exercises/raindrops/
tracks/elm/exercises/collatz-conjecture/
tracks/gnu-apl/exercises/leap/
tracks/haxe/exercises/leap/
tracks/php/exercises/collatz-conjecture/
tracks/php/exercises/flatten-array/
tracks/plsql/exercises/hello-world/
tracks/python/exercises/change/
tracks/python/exercises/two-bucket/
tracks/ruby/exercises/change/
tracks/ruby/exercises/rotational-cipher/
tracks/swift/exercises/rotational-cipher/

bdw429s · 2017-10-14T00:09:33Z

Yeah, I'll be honest-- I didn't include readmes in most of the CFML exercises because I didn't have anything to add or subtract from the default readme, which displays by default on the website. I figured less was more :) Having the readme delivered to the student tho is a worthy cause, so I'll go through and update all the CFML excercises to have the default readme.

bdw429s · 2017-10-14T00:20:39Z

@petertseng The CFML track now has default readmes on every exercise. Please update your list.

petertseng · 2017-10-14T00:31:06Z

Having the readme delivered to the student tho is a worthy cause

Luckily, the Trackler-backed Exercism would still have delivered the default READMEs, because https://github.com/exercism/trackler/blob/master/lib/trackler/implementation.rb#L40. So READMEs would only have been not-delivered for those using Nextercism.

Please update your list.

The list is automatically generated from me running the script on Trackler gem as it exists on my filesystem as delivered to me by RubyGems. I have no power to change the output of the script until Trackler changes.

Just kidding, I can grep.

gems/trackler-2.2.1.45$ for d in tracks/*/exercises/*/; do if [ ! -f $d/README.md ]; then echo $d; fi; done | grep -v cfml
tracks/bash/exercises/error-handling/
tracks/csharp/exercises/complex-numbers/
tracks/dart/exercises/raindrops/
tracks/elm/exercises/collatz-conjecture/
tracks/gnu-apl/exercises/leap/
tracks/haxe/exercises/leap/
tracks/php/exercises/collatz-conjecture/
tracks/php/exercises/flatten-array/
tracks/plsql/exercises/hello-world/
tracks/python/exercises/change/
tracks/python/exercises/two-bucket/
tracks/ruby/exercises/change/
tracks/ruby/exercises/rotational-cipher/
tracks/swift/exercises/rotational-cipher/

I'm just saying that's all I can do until Trackler is updated.

After exercism/meta#15, READMEs are to be generated and placed into each track's exercise implementation directory. My (unsubstantiated) assumption is that they will be required to be present after Nextercism, as we don't want to keep generating READMEs on the fly. If this assumption is correct, it seems necessary to check that READMEs are present on all exercises. With the attached fixture change and attached test changes: * The example test would fail without the attached code change. * The unit test in `lint_test.go` testing against `fixtures/numbers` actually does not fail, because there are other reasons for the track to be invalid, so the attached code change was not necessary. This points to the unit test being too coarse, but this is a discussion for another day. For now, the example test suffices. Closes exercism/discussions#200 Closes exercism/configlet#86

After exercism/meta#15, READMEs are to be generated and placed into each track's exercise implementation directory. My (unsubstantiated) assumption is that they will be required to be present after Nextercism, as we don't want to keep generating READMEs on the fly. If this assumption is correct, it seems necessary to check that READMEs are present on all exercises. With the attached fixture change and attached test changes: * The example test would fail without the attached code change. * The added TestMissingReadme would fail if the attached code change were incorrect. * The TestLintTrack against `fixtures/numbers` actually does not fail, because there are other reasons for the track to be invalid, so the attached code change was not necessary. This points to the unit test being too coarse, but this is a discussion for another day. For now, the other two tests suffice. Closes exercism/discussions#200 Closes exercism/configlet#86

petertseng · 2017-10-14T01:36:22Z

Looking at the current results of missing README.md:

Arbitrarily select the first exercise among active tracks (important because non-active tracks don't show on Nextercism!) from the list of those exercises missing READMEs.

Trackler-backed Exercism:

http://exercism.io/exercises/csharp/complex-numbers/readme has README content.
http://x.exercism.io/v2/exercises/csharp/complex-numbers contains README.md

Nextercism:

https://v2.exercism.io/my/solutions/29842182ac9a4b74b635da042d4ff482 (this happens to be my page for C# complex numbers, I wonder what happens if someone else visits this page?) has README content.
(I can't test nextercism download at this moment)

Oh. Well even without being able to download nextercism download, my hypothesis of "Nextercism requires READMEs" has already been invalidated. Maybe it will be re-validated in a later version of Nextercism, I have no idea.

Depends on whether https://github.com/exercism/prototype/blob/4d093ec7766b292f014205d1747015b90b6468c5/app/services/git/syncs_track.rb#L94 is meant to be temporary or permanent.

After exercism/meta#15, READMEs are to be generated and placed into each track's exercise implementation directory. My (unsubstantiated) assumption is that they will be required to be present after Nextercism, as we don't want to keep generating READMEs on the fly. If this assumption is correct, it seems necessary to check that READMEs are present on all exercises. With the attached fixture change and attached test changes: * The example test would fail without the attached code change. * The added TestMissingReadme would fail if the attached code change were incorrect. * The TestLintTrack against `fixtures/numbers` actually does not fail, because there are other reasons for the track to be invalid, so the attached code change was not necessary. This points to the unit test being too coarse, but this is a discussion for another day. For now, the other two tests suffice. Closes exercism/discussions#200 Closes exercism/configlet#86

After exercism/meta#15, READMEs are to be generated and placed into each track's exercise implementation directory. My (unsubstantiated) assumption is that they will be required to be present after Nextercism, as we don't want to keep generating READMEs on the fly. If this assumption is correct, it seems necessary to check that READMEs are present on all exercises. With the attached fixture change and attached test changes: * The added TestMissingReadme would fail if the attached code change were incorrect. * The added TestLintTrack case on missing-readmes would fail without the attached code change. Closes exercism/discussions#200 Closes exercism/configlet#86

kytrinyx · 2017-10-22T11:29:38Z

At the moment nextercism assumes that the README is present in the exercise, but doesn't require it.

Configlet has a command to generate READMEs, but at the moment it needs to be run manually by the contributor or maintainer. I intend to spec out a bot that will add/update READMEs when they're missing or things change, but I don't have a clear roadmap at the moment so can't promise an ETA.

I agree with the conclusion that configlet lint is the right place for this check (and see that you've all very capably kicked that off. Thank you.)

Stargator · 2017-12-06T18:03:23Z

@kytrinyx I agree configlet lint seems like the best place.

tleen mentioned this issue Oct 13, 2017

Lint: new excersices should have readme exercism/v2-configlet#86

Closed

bdw429s mentioned this issue Oct 14, 2017

create default readmes exercism/cfml#66

Merged

petertseng mentioned this issue Oct 14, 2017

lint: Check for README presence (and supporting commits) exercism/v2-configlet#98

Merged

ilya-khadykin mentioned this issue Oct 14, 2017

Add missing README.md files for change and two-bucket exercism/python#806

Merged

petertseng mentioned this issue Nov 4, 2017

READMEs: Import problem-specifications commits exercism/rust#354

Merged

rpottsoh closed this as completed in rpottsoh/configlet@def9684 Feb 4, 2018

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Who/what shall be responsible for ensuring that README.md exists for each exercise? Configlet or individual tracks? #200

Who/what shall be responsible for ensuring that README.md exists for each exercise? Configlet or individual tracks? #200

petertseng commented Oct 12, 2017 •

edited

Loading

Smarticles101 commented Oct 13, 2017

ferhatelmas commented Oct 13, 2017

ilya-khadykin commented Oct 13, 2017 •

edited

Loading

petertseng commented Oct 13, 2017

bdw429s commented Oct 14, 2017

bdw429s commented Oct 14, 2017

petertseng commented Oct 14, 2017

petertseng commented Oct 14, 2017

kytrinyx commented Oct 22, 2017

Stargator commented Dec 6, 2017

Who/what shall be responsible for ensuring that README.md exists for each exercise? Configlet or individual tracks? #200

Who/what shall be responsible for ensuring that README.md exists for each exercise? Configlet or individual tracks? #200

Comments

petertseng commented Oct 12, 2017 • edited Loading

Smarticles101 commented Oct 13, 2017

ferhatelmas commented Oct 13, 2017

ilya-khadykin commented Oct 13, 2017 • edited Loading

petertseng commented Oct 13, 2017

bdw429s commented Oct 14, 2017

bdw429s commented Oct 14, 2017

petertseng commented Oct 14, 2017

petertseng commented Oct 14, 2017

kytrinyx commented Oct 22, 2017

Stargator commented Dec 6, 2017

petertseng commented Oct 12, 2017 •

edited

Loading

ilya-khadykin commented Oct 13, 2017 •

edited

Loading