From 5f3a6a19f23caa7d0dc097ae8e197be507c03d11 Mon Sep 17 00:00:00 2001 From: David Kennedy Date: Thu, 14 Feb 2013 12:51:00 +0000 Subject: [PATCH 1/3] Ignore RVM config if the user wants to use it RVM allows the user to select a specific Ruby for a specific project. It is common to put a .rvmrc config file in the root of a project to select the Ruby automatically when the user switches into that project. The Ruby Koans should ignore this file if present and not mistake it for a change to the Koans themselves. There are other ways of choosing a Ruby to use, and use of RVM is not mandated by the Koans so ignoring seems like the right solution. --- .gitignore | 1 + 1 file changed, 1 insertion(+) diff --git a/.gitignore b/.gitignore index ffb9a5a..81fb2a4 100644 --- a/.gitignore +++ b/.gitignore @@ -1,5 +1,6 @@ dist .project_env.rc .path_progress +.rvmrc *.rbc koans/* From eedfeb1022d3b102335a7846ef993b008fd33c5f Mon Sep 17 00:00:00 2001 From: David Kennedy Date: Thu, 14 Feb 2013 13:21:06 +0000 Subject: [PATCH 2/3] Explain how to use watchr in the README Support has been added for watchr, and this is very helpful while walking the path to enlightenment as it keeps the users focus on the koans and not on the repeated need to run rake after each edit. However, only an experienced Rubyist would know how to install and use watchr (or worse, they might just not notice the watchr config file). So let's add an optional section to the README explaining how to use watchr. --- README.rdoc | 56 +++++++++++++++++++++++++++++++++++++++-------------- 1 file changed, 42 insertions(+), 14 deletions(-) diff --git a/README.rdoc b/README.rdoc index 121228b..93e4bc8 100644 --- a/README.rdoc +++ b/README.rdoc @@ -8,9 +8,9 @@ and do great things in the language. == The Structure -The koans are broken out into areas by file, hashes are covered in about_hashes.rb, -modules are introduced in about_modules.rb, etc. They are presented in order in the -path_to_enlightenment.rb file. +The koans are broken out into areas by file, hashes are covered in about_hashes.rb, +modules are introduced in about_modules.rb, etc. They are presented in +order in the path_to_enlightenment.rb file. Each koan builds up your knowledge of Ruby and builds upon itself. It will stop at the first place you need to correct. @@ -23,8 +23,8 @@ make it work correctly. == Installing Ruby If you do not have Ruby setup, please visit http://ruby-lang.org/en/downloads/ for -operating specific instructions. In order to run this you need ruby and rake -installed. To check the installations simply type: +operating specific instructions. In order to run this you need ruby and +rake installed. To check the installations simply type: *nix platforms from any terminal window: @@ -36,10 +36,10 @@ Windows from the command prompt (cmd.exe) c:\ruby --version c:\rake --version -If you don't have rake installed, just run `gem install rake` +If you don't have rake installed, just run gem install rake Any response for Ruby with a version number greater than 1.8 is fine (should be -around 1.8.6 or more). Any version of rake will do. +around 1.8.6 or more). Any version of rake will do. == Generating the Koans @@ -69,12 +69,13 @@ Windows is the same thing === Red, Green, Refactor -In test-driven development the mantra has always been, red, green, refactor. Write a -failing test and run it (red), make the test pass (green), then refactor it (that is -look at the code and see if you can make it any better). In this case you will need -to run the koan and see it fail (red), make the test pass (green), then take a -moment and reflect upon the test to see what it is teaching you and improve the -code to better communicate its intent (refactor). +In test-driven development the mantra has always been red, green, refactor. +Write a failing test and run it (red), make the test pass (green), +then refactor it (that is look at the code and see if you can make it any better). +In this case you will need to run the koan and see it fail (red), make +the test pass (green), then take a moment and reflect upon the test to +see what it is teaching you and improve the code to better communicate its intent +(refactor). The very first time you run it you will see the following output: @@ -106,7 +107,7 @@ the first solution: path_to_enlightenment.rb:38:in `each_with_index' path_to_enlightenment.rb:38 -We then open up the about_asserts.rb file and look at the first test: +We then open up the about_asserts.rb file and look at the first test: # We shall contemplate truth by testing reality, via asserts. def test_assert_truth @@ -122,6 +123,33 @@ In this case the goal is for you to see that if you pass a value to the +assert+ method, it will either ensure it is +true+ and continue on, or fail if in fact the statement is +false+. +=== Running the Koans automatically + +This section is optional. + +Normally the path to enlightenment looks like this: + + cd ruby_koans + rake + # edit + rake + # edit + rake + # etc + +If you prefer, you can keep the koans running in the background so that after you +make a change in your editor, the koans will immediately run again. This will +hopefully keep your focus on learning Ruby instead of the command line. + +Install the Ruby gem (library) called +watchr+ and then ask it to +"watch" the koans for changes: + + cd ruby_koans + rake + # decide to run rake automatically from now on as you edit + gem install watchr + watchr ./koans/koans.watchr + == Inspiration A special thanks to Mike Clark and Ara Howard for inspiring this From f36a964fdd95b5b516b4869edac96491fc156529 Mon Sep 17 00:00:00 2001 From: David Kennedy Date: Thu, 14 Feb 2013 14:22:11 +0000 Subject: [PATCH 3/3] Explain how to use Watchr in the README The koans have support for Watchr now, and this is very helpful as you can focus on editing and not on re-running rake over and over. However, a user new to Ruby will not even know what Watchr is (I'd not used it before! I was using Guard) so they might miss this choice. There are some other minor edits for style and consistency. I explain that Koans are tests. We/You tidy up. Removed some excess wordage. Made some "your should do this" statements more imperative. Made mark up more consistent. --- README.rdoc | 51 ++++++++++++++++++++++++++------------------------- 1 file changed, 26 insertions(+), 25 deletions(-) diff --git a/README.rdoc b/README.rdoc index 93e4bc8..5034992 100644 --- a/README.rdoc +++ b/README.rdoc @@ -2,17 +2,17 @@ The Ruby Koans walk you along the path to enlightenment in order to learn Ruby. The goal is to learn the Ruby language, syntax, structure, and some common -functions and libraries. We also teach you culture. Testing is not just something we -pay lip service to, but something we live. It is essential in your quest to learn -and do great things in the language. +functions and libraries. We also teach you culture by basing the koans on tests. +Testing is not just something we pay lip service to, but something we +live. Testing is essential in your quest to learn and do great things in Ruby. == The Structure -The koans are broken out into areas by file, hashes are covered in about_hashes.rb, -modules are introduced in about_modules.rb, etc. They are presented in -order in the path_to_enlightenment.rb file. +The koans are broken out into areas by file, hashes are covered in +about_hashes.rb+, +modules are introduced in +about_modules.rb+, etc. They are presented in +order in the +path_to_enlightenment.rb+ file. -Each koan builds up your knowledge of Ruby and builds upon itself. It will stop at +Each koan builds up your knowledge of Ruby and builds upon itself. It will stop at the first place you need to correct. Some koans simply need to have the correct answer substituted for an incorrect one. @@ -23,23 +23,23 @@ make it work correctly. == Installing Ruby If you do not have Ruby setup, please visit http://ruby-lang.org/en/downloads/ for -operating specific instructions. In order to run this you need ruby and -rake installed. To check the installations simply type: +operating specific instructions. In order to run the koans you need +ruby+ and ++rake+ installed. To check your installations simply type: *nix platforms from any terminal window: [~] $ ruby --version [~] $ rake --version -Windows from the command prompt (cmd.exe) +Windows from the command prompt (+cmd.exe+) c:\ruby --version c:\rake --version -If you don't have rake installed, just run gem install rake +If you don't have +rake+ installed, just run +gem install rake+ Any response for Ruby with a version number greater than 1.8 is fine (should be -around 1.8.6 or more). Any version of rake will do. +around 1.8.6 or more). Any version of +rake+ will do. == Generating the Koans @@ -54,10 +54,10 @@ If you need to regenerate the koans, thus wiping your current `koans`, == The Path To Enlightenment -You can run the tests through rake or by calling the file itself (rake is the +You can run the tests through +rake+ or by calling the file itself (+rake+ is the recommended way to run them as we might build more functionality into this task). -*nix platforms, from the koans directory +*nix platforms, from the +ruby_koans+ directory [ruby_koans] $ rake # runs the default target :walk_the_path [ruby_koans] $ ruby path_to_enlightenment.rb # simply call the file directly @@ -71,13 +71,14 @@ Windows is the same thing In test-driven development the mantra has always been red, green, refactor. Write a failing test and run it (red), make the test pass (green), -then refactor it (that is look at the code and see if you can make it any better). -In this case you will need to run the koan and see it fail (red), make -the test pass (green), then take a moment and reflect upon the test to -see what it is teaching you and improve the code to better communicate its intent -(refactor). +then look at the code and consider if you can make it any better (refactor). -The very first time you run it you will see the following output: +While walking the path to Ruby enlightenment you will need to run the koan and +see it fail (red), make the test pass (green), then take a moment +and reflect upon the test to see what it is teaching you and improve the code to +better communicate its intent (refactor). + +The very first time you run the koans you will see the following output: [ ruby_koans ] $ rake (in /Users/person/dev/ruby_koans) @@ -99,7 +100,7 @@ The very first time you run it you will see the following output: mountains are merely mountains your path thus far [X_________________________________________________] 0/280 -You have come to your first stage. If you notice it is telling you where to look for +You have come to your first stage. Notice it is telling you where to look for the first solution: Please meditate on the following code: @@ -107,20 +108,20 @@ the first solution: path_to_enlightenment.rb:38:in `each_with_index' path_to_enlightenment.rb:38 -We then open up the about_asserts.rb file and look at the first test: +Open the +about_asserts.rb+ file and look at the first test: # We shall contemplate truth by testing reality, via asserts. def test_assert_truth assert false # This should be true end -We then change the +false+ to +true+ and run the test again. After you are +Change the +false+ to +true+ and re-run the test. After you are done, think about what you are learning. In this case, ignore everything except the method name (+test_assert_truth+) and the parts inside the method (everything before the +end+). In this case the goal is for you to see that if you pass a value to the +assert+ -method, it will either ensure it is +true+ and continue on, or fail if in fact +method, it will either ensure it is +true+ and continue on, or fail if the statement is +false+. === Running the Koans automatically @@ -139,7 +140,7 @@ Normally the path to enlightenment looks like this: If you prefer, you can keep the koans running in the background so that after you make a change in your editor, the koans will immediately run again. This will -hopefully keep your focus on learning Ruby instead of the command line. +hopefully keep your focus on learning Ruby instead of on the command line. Install the Ruby gem (library) called +watchr+ and then ask it to "watch" the koans for changes: