trackler 2.1.0.4 → 2.1.0.5

data/tracks/ruby/.github/ISSUE_TEMPLATE.md

@@ -39,5 +39,5 @@
 
 ## References and Closures
 
-<!--- refernces #000 --->
-<!--- closes #000 --->
+<!--- references #000 -->
+<!--- closes #000 -->

data/tracks/ruby/.github/PULL_REQUEST_TEMPLATE.md

@@ -1,12 +1,15 @@
-<!--- Provide a general summary of your changes in the Title above -->
+<!--- This template is meant to help develop good habits in creating PRs. -->
+<!--- Feel free to delete it if you don't find it useful. -->
 
-## Description
-<!--- Describe your changes in detail -->
+<!--- Provide a general summary of your changes in the Title above -->
 
-## Motivation and Context
+## Why?
 <!--- Why is this change required? What problem does it solve? -->
 <!--- If it fixes an open issue, please link to the issue here. -->
 
+## What?
+<!--- Describe your changes in detail -->
+
 ## How Has This Been Tested?
 <!--- Please describe in detail how you tested your changes. -->
 <!--- Include details of your testing environment, and the tests you ran to -->
@@ -17,20 +20,21 @@
 ## Types of changes
 <!--- What types of changes does your code introduce? Put an `x` in all the boxes that apply: -->
 - [ ] Bug fix (non-breaking change which fixes an issue)
-- [ ] New feature (non-breaking change which adds functionality)
-- [ ] Breaking change (fix or feature that would cause existing functionality to change)
+- [ ] Enhancement (non-breaking change which adds functionality)
+- [ ] Breaking change (fix or enhancement that would cause existing functionality to change)
+- [ ] Gardening (code and/or documentation cleanup)
 
 ## References and Closures
-
-<!--- refernces #000 -->
+<!--- not previously mentioned -->
+<!--- references #000 -->
 <!--- closes #000 -->
 
 ## Checklist:
 <!--- Go over all the following points, and put an `x` in all the boxes that apply. -->
 <!--- If you're unsure about any of these, don't hesitate to ask. We're here to help! -->
-- [ ] My change requires a change to the documentation.
+- [ ] I have read the **CONTRIBUTING** document.
 - [ ] My change relies on a pending issue/pull request
+- [ ] My change requires a change to the documentation.
 - [ ] I have updated the documentation accordingly.
-- [ ] I have read the **CONTRIBUTING** document.
 - [ ] I have added tests to cover my changes.
 - [ ] All new and existing tests passed.

data/tracks/ruby/.github/stale.yml

@@ -0,0 +1,21 @@
+# Configuration for probot-stale - https://github.com/probot/stale
+
+# Number of days of inactivity before an Issue or Pull Request becomes stale
+daysUntilStale: 60
+# Number of days of inactivity before a stale Issue or Pull Request is closed
+daysUntilClose: 7
+# Issues or Pull Requests with these labels will never be considered stale
+exemptLabels:
+  - pinned
+  - security
+# Label to use when marking as stale
+staleLabel: stale
+# Comment to post when marking as stale. Set to `false` to disable
+markComment: >
+  This issue has been automatically marked as stale because it has not had
+  recent activity. It will be closed if no further activity occurs. Thank you
+  for your contributions.
+# Comment to post when closing a stale Issue or Pull Request. Set to `false` to disable
+closeComment: false
+# Limit to only `issues` or `pulls`
+# only: issues

data/tracks/ruby/README.md

@@ -7,40 +7,27 @@ Exercism Exercises in Ruby
 
 ## Setup
 
-You'll need a recent (2.1+) version of Ruby, but that's it. Minitest
-ships
-with the language, so you're all set.
+You'll need a recent (2.1+) version of Ruby, but that's it. Minitest ships with
+the language, so you're all set.
 
-## Working on Test Suites
+## Anatomy of an Exercise
 
-Each problem should have a test suite and an example solution.
-The example solution should be named `example.rb`.
+The files for an exercise live in `exercises/<exercise_name>` (where
+`<exercise_name>` is the slug for the exercise, e.g. `clock` or
+`atbash-cipher`). An exercise has a test suite
+(`exercises/<exercise_name>/<exercise_name>_test.rb`) and an example solution
+(`exercises/<exercise_name>/example.rb`).
 
-**Some test suites are generated from shared inputs/outputs, see
-[Generated Test Suites](#generated-test-suites) below.** In short, if
-the problem directory contains an `example.tt` file, then it's a
-generated problem.
+**Most exercises can be generated from shared inputs/outputs, called canonical
+data (see [Generated Test Suites](#generated-test-suites) below).** To find out
+whether a test has canonical data, check
+the [x-common repo](https://github.com/exercism/x-common/tree/master/exercises).
 
-### Hard-coded Test Suites
+## Running the Tests
 
-Run the test with `ruby path/to/the_test.rb`.
-
-At the moment the Ruby problems `skip` all but the first test, in order
-to not overwhelm people with errors.
-
-If you want to temporarily disable the skips while working on a test
-suite, you can run the file with a shim that temporarily disables them:
-
-```sh
-ruby -I./lib -rdisable_skip exercise/exercise/filename_test.rb
-```
-
-It is simpler to use the `rake` tool which is available in the project
-root.  It will disable the skip calls for you automatically, it does the
-same thing as the above.
-
-If you would like to use the `rake` tool to run a single test while
-developing clock, for example, you can do something like this:
+Run the tests using `rake`, rather than `ruby path/to/the_test.rb`. `rake`
+knows to look for `example.rb` and to disable skips. Just tell `rake` the
+name of your problem and you are set:
 
 ```sh
 rake test:clock
@@ -52,8 +39,10 @@ the following:
 rake test:clock -- -p
 ```
 
-To show an example of running a limited number of tests, we will use the
-"hamming" exercise with a pattern of "identical" to run (currently) two tests:
+To run a subset of the tests, use a regular expression. For example, if tests
+exist taht are named identical_to_4_places, and identical, then we can run both
+tests with
+
 ```sh
 rake test:hamming -- -p -n="/identical/"
 ```
@@ -64,15 +53,20 @@ Note that flags which have an attached value, like above, must take the form
 
 ### Generated Test Suites
 
-If you find a `<problem_name>_cases.rb` file in `lib/`, then the test suite is
-generated from shared data, which can be found in the exercise definition in the [x-common][]
-repository.
+Generated test suites use the `bin/generator` cli.
+
+While many of the exercises which have canonical data already have generators,
+some do not. To find out whether an exercise has a generator, run
 
-Typically you will want to do one of the following:
+    bin/generate -h
+
+In addition to a usage message, the `-h` flag lists all exercises with a
+generator. If a generator is available for your exercise, you can
 
 * [Regenerate the test suite](#regenerating-an-exercise) based on updated canonical data
 * [Make changes to a generated exercise](#changing-a-generated-exercise)
-* [Implement a new generator](#implementing-a-generator)
+
+If not, you will need to [implement a new generator](#implementing-a-generator)
 
 Generated exercises depend on the [the shared metadata][x-common], which must be
 cloned to the same directory that contains your clone of the xruby repository:
@@ -83,52 +77,56 @@ tree -L 1 ~/code/exercism
 └── xruby
 ```
 
-#### Regenerating an Exercise
+#### Regenerating a Test Suite
 
-From within the xruby directory, run the following command, where $PROBLEM is the slug
-of the exercise, e.g. `clock` or `atbash-cipher`:
+From within the xruby directory, run the following command:
 
 ```
-bin/generate $PROBLEM
+bin/generate <exercise_name>
 ```
 
 #### Changing a Generated Exercise
 
-Do not edit `$PROBLEM/$PROBLEM_test.rb`. Any changes you make will be overwritten when
-the file is generated the next time.
+Do not edit `<exercise_name>/<exercise_name>_test.rb`. Any changes you make will
+be overwritten when the test suite is regenerated.
 
 There are two reasons why a test suite might change:
 
-1. the tests are wrong (an incorrect expectation, a missing edge case, etc)
+1. the tests need to change (an incorrect expectation, a missing edge case, etc)
 1. there might be issues with the style or boilerplate
 
 In the first case, the changes need to be made to the `canonical-data.json` file for
 the exercise, which lives in the x-common repository.
 
 ```
-../x-common/exercises/$PROBLEM/
+../x-common/exercises/<exercise_name>/
 ├── canonical-data.json
 ├── description.md
 └── metadata.yml
 ```
 
-This change will need to be submitted as a pull request to the x-common repository. This pull
-request needs to be merged before you can regenerate the exercise.
+This change will need to be submitted as a pull request to the x-common
+repository. This pull request needs to be merged before you can regenerate the
+exercise.
 
 Changes that don't have to do directly with the test inputs and outputs should
-be made to `lib/$PROBLEM_cases.rb`. Then you can regenerate the exercise with
-`bin/generate $PROBLEM`.
+be made to the exercise's test case generator, discussed
+in [implementing a new generator](#implementing-a-generator), next.  Then you
+can regenerate the exercise with `bin/generate <exercise_name>`.
 
 #### Implementing a Generator
 
-You will need to write code to produce the code that goes inside the test methods. Your
-code will live in `lib/$PROBLEM_cases.rb`.
+An exercise's test case generator class produces the code that goes inside
+the minitest `test_<whatever>` methods. An exercise's generator lives in
+`exercises/<exercise_name>/.meta/generator/<exercise_name>_cases.rb`.
 
-`lib/$PROBLEM_cases.rb` contains a derived class of `ExerciseCase` (in `lib/generator/exercise_cases.rb`)
-which wraps the JSON for a single test case. The default version looks something like this:
+The test case generator is a derived class of `ExerciseCase` (in
+`lib/generator/exercise_cases.rb`). `ExerciseCase` does most of the work of
+extracting the canonical data. The derived class wraps the JSON for a single
+test case. The default version looks something like this:
 
 ```
-class ProblemNameCase < ExerciseCase
+class <ExerciseName>Case < ExerciseCase
 
   def workload
     # Example workload:
@@ -138,31 +136,36 @@ class ProblemNameCase < ExerciseCase
 end
 ```
 
-Instead of `ProblemName` use the CamelCased name of the actual problem. This is important, since
-the generator script will infer the name of the class from the argument that is passed.
+where `<ExerciseName>` is the <exercise_name> slug in CamelCase. This is
+important, since the generator script will infer the name of the class from the
+<exercise_name> slug.
 
-This class must provide the methods used by `lib/generator/test_template.erb`. The base class provides methods
-for the default template for everything except `workload`.
+This class must provide the methods used by the test
+template. A
+[default template](https://github.com/exercism/xruby/blob/master/lib/generator/test_template.erb) that
+most exercises can (and do) use lives in `lib/generator/test_template.erb`. The
+base class provides methods for the default template for everything except
+`#workload`.
 
-`workload` generates the code for the body of a test, including the assertion
+`#workload` generates the code for the body of a test, including the assertion
 and any setup required. The base class provides a variety of assertion and
 helper methods. Beyond that, you can implement any helper methods that you need
-as private methods in your derived class. See below for more information about [the intention of workload](#workload-philosophy)
-
-If you really must add additional logic to the view template, you can use a custom
-template. Copy `lib/generator/test_template.erb` to your exercise directory, name it
-`exercise.tt`, and customize.
+as private methods in your derived class. See below for more information
+about [the intention of #workload](#workload-philosophy)
 
-You will not need to touch the top-level script, `bin/generate`.
+You don't have to do anything other than implement `#workload` to use the default
+template.
 
-The `bin/generate` command relies on some common logic implemented in `lib/generator.rb`.
-You won't need to touch that, either.
+If you really must add additional logic to the view template, you can use a
+custom template. Copy `lib/generator/test_template.erb` to
+`.meta/generator/test_template.erb` under your exercise directory and
+customize. You may need to create `.meta` and/or `.meta/generator`.
 
 
-### Workload philosophy.
+#### Workload philosophy.
 
 Prioritize educational value over expert comprehension and make sure that
-things are clear to people who may not be familiar with Minitest and even Ruby. 
+things are clear to people who may not be familiar with Minitest and even Ruby.
 
 Provide the information the student needs to derive the code to pass the test
 in a clear and consistent manner. Illustrate the purpose of the individual
@@ -215,18 +218,21 @@ appropriately.
 
 For more complete information, see [Rubocop](http://batsov.com/rubocop/).
 
-It is the responsibility of the Ruby test generator to interpret the $PROBLEM.json data in a stylistically correct manner, eg downcase the test method names.
+While `lib/generator/exercise_cases.rb` provides helper functions as discussed
+above, it remains the responsibility of an exercise's generator to interpret its
+canonical-data.json data in a stylistically correct manner, e.g. converting
+string indices to integer indices.
 
 ## READMEs
 
-Please do not add a README or README.md file to the problem directory. The
-READMEs are constructed using shared metadata, which lives in the
-[exercism/x-common](https://github.com/exercism/x-common) repository.
+Do not add a README or README.md file to the exercise's directory. The READMEs
+are constructed using shared metadata, which lives in the [x-common][] repo.
 
 ## Contributing Guide
 
-For an in-depth discussion of how exercism language tracks and problem sets
-work, please see the [contributing guide](https://github.com/exercism/x-api/blob/master/CONTRIBUTING.md#the-exercise-data)
+For an in-depth discussion of how exercism language tracks and exercises work,
+please see the
+[contributing guide](https://github.com/exercism/x-api/blob/master/CONTRIBUTING.md#the-exercise-data)
 
 ## License
 

data/tracks/ruby/lib/generator/files.rb

@@ -2,6 +2,10 @@ require 'pathname'
 
 module Generator
   module Files
+    def self.read(filename)
+      File.read(filename) if File.exist?(filename)
+    end
+
     class Readable
       attr_reader :filename, :repository_root
       def initialize(filename:, repository_root: nil)
@@ -10,7 +14,7 @@ module Generator
       end
 
       def to_s
-        File.read(filename) if File.exist?(filename)
+        Files.read(filename)
       end
 
       def abbreviated_commit_hash

data/tracks/ruby/lib/generator/files/generator_cases.rb

@@ -4,8 +4,8 @@ module Generator
       module_function
 
       def available(track_path)
-        generator_glob = File.join(track_path, 'lib', '*_cases.rb')
-        Dir[generator_glob].sort.map { |filename| exercise_name(filename) }
+        generator_glob = File.join(track_path, "{lib,exercises}", '**', '*_cases.rb')
+        Dir.glob(generator_glob, File::FNM_DOTMATCH).sort.map { |filename| exercise_name(filename) }
       end
 
       def filename(exercise_name)
@@ -20,9 +20,23 @@ module Generator
         %r{([^/]*)_cases\.rb$}.match(filename).captures[0].tr('_', '-')
       end
 
+      # temporary, when we've moved everything, move contents of cases_filename
+      # to this method
       def load_filename(track_path, exercise_name)
-        path = File.join(track_path, 'lib')
-        "%s/%s.rb" % [ path, filename(exercise_name) ]
+        File.exist?(cases_filename(track_path, exercise_name)) ?
+          cases_filename(track_path, exercise_name) :
+          legacy_cases_filename(track_path, exercise_name)
+      end
+
+      # this becomes load_filename
+      def cases_filename(track_path, exercise_name)
+        "%s.rb" % File.join(track_path, 'exercises', exercise_name, '.meta', 'generator',
+                            filename(exercise_name))
+      end
+
+      # this goes away
+      def legacy_cases_filename(track_path, exercise_name)
+        "%s.rb" % File.join(track_path, 'lib', filename(exercise_name))
       end
     end
   end