Merge branch 'master' of github.com:bkaestner/codewars-rules

Author: bkaestner

pandoc.css

@@ -107,6 +107,9 @@ pre::after{
 pre.c:after{
     content:"C";
 }
+pre.bash:after{
+    content:"bash";
+}
 pre.cs:after{
     content:"C#";
 }
@@ -125,9 +128,7 @@ pre.python:after{
 pre.ruby:after{
     content:"Ruby";
 }
-pre.c:after{
-    content:"C";
-}
+
 code {
  /*   font-family: monospace; */
 }

publish.sh

@@ -3,6 +3,8 @@ set -x
 rev=$(git rev-parse --short HEAD)
 branch=$(git rev-parse --abbrev-ref HEAD)
 
+echo Previous branch was $branch
+
 # If we cannot checkout master, stop immediately
 git checkout master || exit 1
 
@@ -14,7 +16,7 @@ git checkout --orphan gh-pages || exit 1
 
 # Ignore all already added files, but stop if we would forget
 # changes.
-git rm --cached \* || git checkout $branch && exit 1
+git rm --cached \* || exit 1
 
 # Create the page
 make html
@@ -26,5 +28,4 @@ git commit -m "Publish GitHub pages, based on $rev"
 # Publish GH pages
 git push origin gh-pages -f
 
-# Go back to previous branch
-git checkout $branch -f
+echo Use 'git checkout $branch -f' to change back to the previous branch.

rules/0100-Writing-a-kata.md

@@ -288,6 +288,8 @@ provide reflection or similar means to check your preloaded code, which enables
 a user to cheat rather easily. Instead, put your solution into a local scope
 (see [Hide your solution](#hide-your-solution)).
 
+For more information about preloaded code, see [the next section](#the-preload-section).
+
 
 Provide helpers for tasks that are dull
 ---------------------------------------
@@ -334,7 +336,7 @@ It's bad for several reasons:
 
 - it doesn't return any helpful error message if the solution is wrong
 - it's not modular
-- it's not compatible to the CodeWars testing framework
+- it's not compatible to the Codewars testing framework
 
 Another variant, which uses Hspec and random tests could be written as
 

rules/0110-Intermezzo---The-Codewars-Platform.md

@@ -0,0 +1,113 @@
+Intermezzo: The Codewars platform
+=================================
+
+Now that you have read all those tips and tricks, you probably cannot
+wait to write your next kata, right?  However, before you jump in, you
+should learn a little bit about the Codewars platform, if you want to
+run random tests or use the "preload" section.
+
+
+## How Codewars works
+
+Whenever you write a kata, you have at least six input windows:
+
+1. the description (cannot be blank)
+2. the initial solution (cannot be blank)
+3. the solution (cannot be blank)
+4. the example test fixtures
+5. the test fixtures (cannot be blank)
+6. the preloaded code
+
+All of this is used by the [runner].  The runner is basically a `node`
+process, which calls the languages interpreter and either
+
+- creates a temporary dictionary structure containing all code
+  (Haskell, Java, CSharp or other module/file based languages)
+- or ___concatenates___ and passes the code to the interpreter via command
+  line argument (Ruby, JavaScript, CoffeeScript, Python).
+
+It then checks the output of the process for some fields, filters them,
+and shows the filtered text to the user.  If the fields indicate that
+the user has passed the tests, they will have passed the kata.
+
+This is the big difference between Codewars and other code running sites
+like SPOJ, Hackerrank and other.  There, you will have to read from STDIN,
+and give formatted answers to STDOUT.  You often don't learn details about
+your failed tests, only that you've failed them, since the tests are often
+only different `*.txt` files that get streamed into your file.
+
+Unfortunately, the _running_ parts of the Codewars runner are currently
+missing in the repository, but still available in its history.  They
+are lacking new content like transpilers though.
+
+In case of JavaScript, the code will get transformed via [`babel`][babel]
+_before_ it is passed to `node`.  All of this preprocessing is _not_
+counted into the users runtime.
+
+However, the important part is the concatenation in interpreted languages.
+That's the part where you have to look out, since it works like this:
+
+```bash
+$ cp python-framework run.py # add framework
+$ echo          "" >> run.py
+$ cat preload.py   >> run.py # add preloaded code
+$ echo          "" >> run.py
+$ cat solution.py  >> run.py # add user solution
+$ echo          "" >> run.py
+$ cat tests.py     >> run.py # add tests
+$ cat run.py | python -e -
+```
+
+The `echo ""` parts are there for newlines.  Either way, as you can see,
+all of your _and_ the user's code are in the same file.  This means that
+while you have access on everything the user has defined, declared and
+written, it also means that they have access to everything you have written.
+
+They can also change the test framework unless it's frozen.  Keep in mind
+that there's an asynchronous cheating test, that adds non-passing tests.
+For example if the user solution exits prematurely with a "passed" output,
+they will get a penalty.
+
+Note that there has been a [heated discussion][issue-214] about the tests
+in Ruby. @danielpclark discusses some of the issues in the thread, and its
+worth a read.
+
+Now to the other languages.  For Haskell, the runner will automatically
+create a temporary dictionary structure that matches the module names.
+This dictionary will reside in `/tmp/` and get run via `runhaskell`.
+The `hspec` framework has been replaced with another one that has some
+more features.  Java and CSharp get handled similarly.
+
+So remember: in interpreted languages, all your code and the user's code
+will reside in the same context, whereas in compiled languages all code
+will reside in the same directory.
+
+By the way, this is the reason you cannot use `process.argv` in Node,
+as it would give a user immediate access to the tests.
+
+ [issue-214]: https://github.com/Codewars/codewars.com/issues/214
+ [runner]: https://github.com/Codewars/codewars-runner
+ [babel]: http://babeljs.io/
+
+
+## The "preloaded" section {#the-preload-section}
+
+The preloaded section in the kata editor is meant for things that should
+be done first, before any other code (beside the import of the test framework)
+is being read, evaluated or executed (in interpreted languages).
+
+You want to provide some extra functions for the user?  Put them in the preloaded
+section.
+You want to disable features, like `Math.random` or `Math.abs`?  Do
+so in the preloaded section.
+You want to make sure that no one panders the testing framework?  Freeze it in
+the preloaded section.
+
+I think you get it. In interpreted languages, use the preloaded section for
+whatever helper you think the user might need, and for whatever security measures
+you want to enable. It's the first thing that gets read during the execution, so
+you're still in charge at that point.
+
+In Haskell, the preloaded section needs a module name and can be imported. It's
+handy for additional functions or data types, as disabling features is done there
+with `hidden`.

rules/0120-Tests.md

@@ -1,5 +1,4 @@
-Tested testing theories
-------------------------
+# Tested testing theories
 
 Tests are the bread and butter of Codewars. Without tests, you couldn't
 check whether the user has solved your kata, so they're very important. Yet
@@ -13,7 +12,7 @@ cannot change the tests in approved katas with more than 500 solutions.
  [#123]: https://github.com/Codewars/codewars.com/issues/123
 
 
-### Make your test descriptive
+## Make your test descriptive
 
 Let's have a look at the following test:
 
@@ -45,7 +44,7 @@ Test.assertEquals(fizzBuzz(15), 'FizzBuzz', "testing on 15")
 This tells the user immediately that their function failed on `15`.
 
 
-#### Group your tests
+### Group your tests
 
 Furthermore, you should group your tests with `describe` and `it`. After all,
 a tests _describes_ the behaviour of something, for example the behaviour
@@ -90,21 +89,47 @@ Test.describe('foo', function(){
 ```
 
 
-#### Make errors obvious
+### Make errors obvious
 
 Especially if you use random tests (see below), you want to make sure that the
 user knows _why_ the test failed. You could print the arguments. You could
 show a hint. Either way, a user shouldn't be left alone in face of an error.
 
-### Always test all corner cases of your input domain
+
+### Think of the HTML
+
+Keep in mind that every output will be interpreted as HTML.  If you want to
+use `<`, `>` or `&` in your error messages or description, make sure to
+escape it---unless you actually want to use HTML tags:
+
+Character | [HTML entity] | Mnemonic
+----------|---------------|-------------------------------------------
+ `<`      | `&lt;`        | **l**esser **t**han
+ `>`      | `&gt;`        | **g**reater **t**han
+ `&`      | `&amp;`       | **amp**ersand
+
+All other characters are usually safe to use in UTF8 encoded documents.
+
+  [HTML entity]: http://dev.w3.org/html5/html-author/charref
+
+
+## Always test all corner cases of your input domain
 
 If you ask the user to create a function that should work for
 `1 <= N <=  1,000,000`, make sure that their function works for *both* 1 and
 1,000,000. If you specified that "negative input should return a monkey",
 make sure that you actually test negative input.
 
 
-### Use random tests
+## Use the tools of your testing framework
+
+If possible, try to use multiple kinds of assertions, e.g. `assertEquals`
+and `assertNotEquals`, or `shouldSatisfy` and `shouldNotSatisfy`.  That
+way, a cheating user will have some more work to circumvent equality or
+predicate based tests.
+
+
+## Use random tests
 
 Whenever when you state a kata you also have to write a solution. This is
 great, as you can use exactly that function to check the users code
@@ -116,7 +141,7 @@ sufficient random input is most often harder than creating the kata itself.
 But it is worth every honour.
 
 
-### Use __more__ random tests
+## Use __more__ random tests
 
 While it's nice to have a random test which validates that the user returns
 the same as your hidden solution, there's no guarantee that your solution
@@ -152,7 +177,7 @@ Test.it('returns something valid', function(){
 ```
 
 
-### Hide your solution
+## Hide your solution
 
 If you use random tests, make sure to hide your solution. In Java or C#, this
 includes making your function `private`. Haskell doesn't allow mutual imports,
@@ -185,14 +210,14 @@ There are more creative ways to hide/store the function, but that's one way
 at least. Note that all dynamic languages on Codewars (Ruby, Python, CS, JS)
 support this kind of local scopes.
 
-### Always have some example tests
+## Always have some example tests
 
 Unless you're creating a puzzle where the user has to find *the answer*,
 present some example tests. Those tests should also contain the corner
 cases and some easy random tests, e.g. check that the user actually returns
 a number for arbitrary negative numbers.
 
-### Handle floating point values the right way
+## Handle floating point values the right way
 
 Whenever the user returns a floating point number, make sure that you take
 floating point behaviour into account. The user might not add the numbers
@@ -210,7 +235,7 @@ want to have something "almost exact" and `1e-7` if I want something
 For more information about floating-point arithmetic, read
 [What Every Computer Scientist Should Know About Floating-Point Arithmetic](https://docs.oracle.com/cd/E19957-01/806-3568/ncg_goldberg.html).
 
-#### An example of floating point dangers
+### An example of floating point dangers
 
 ```python
 def add_three(a,b,c):
@@ -223,7 +248,7 @@ print(add_three_reference(1e-12,1e-12,1) == add_three(1e-12,1e-12,1))
 # False
 ```
 
-#### Relative error testing
+### Relative error testing
 
 The following example shows one way to check floating point values in a more
 sane way:
@@ -250,14 +275,14 @@ def assertFuzzyEquals(actual, expected, msg=""):
 Most language sections contain their equivalent and use `expect` or a similar
 function of their test framework.
 
-#### Consider integral tests
+### Consider integral tests
 
 If your number is guaranteed to be an integral number, use `int`, `long`
 or your language's equivalent instead of floating point numbers. However, keep
 in mind that all values, either input, output, or intermediate should fit in
 this type, otherwise you might encounter overflow or underflow issues.
 
-### Fix broken tests early and fix them right
+## Fix broken tests early and fix them right
 
 While [#163](https://github.com/Codewars/codewars.com/issues/163) will give you
 the tools to fix a kata even late, you should take every reported test issue by
@@ -277,17 +302,17 @@ might get rejected.
 
 So what can you do?
 
-#### Change description to address the bug
+### Change description to address the bug
 You should definitely tell your users if your kata is broken. Especially if your
 tests have a defect in only one particular language. It's not the best you can
 do, but as long as #163 is still there, it might be the only thing you can do.
 
-#### Reject old solutions, they didn't follow the description
+### Reject old solutions, they didn't follow the description
 This is fine as long as there haven't been many solutions. If your kata has been
 solved by hundreds, it might seem a little bit unfair, but correct tests are
 a little bit more important.
 
-#### Experimental solutions
+### Experimental solutions
 There are also other alternatives:
 
 - check the time: if the kata solution is submitted after a certain point in

rules/0140-Collaborating.md

@@ -1,7 +1,6 @@
-Collaborative Codewars Catches
-------------------------------
+## Collaborative Codewars Catches
 
-The previous section mentioned some practices for your tests. However,
+The previous sections mentioned some practices for your tests. However,
 what if you don't know Haskell? Or Java? Or Ruby? You shouldn't provide
 tests for a language you don't know, as this will usually lead to bugs
 in your test cases (see section

rules/0260-JavaScript.md

@@ -1,7 +1,7 @@
 JavaScript / CoffeeScript
 -------------------------
 
-The JavaScript tests on CodeWars use a [custom] test framework. Any kata written
+The JavaScript tests on Codewars use a [custom] test framework. Any kata written
 in CoffeeScript will use the same framework, since CoffeeScript gets compiled
 to JavaScript.
 
@@ -11,7 +11,6 @@ you won't get the real source code if you use `.toString()`, but the result of
 the Babel compiler.
 
  [custom]: http://www.codewars.com/docs/js-slash-coffeescript-test-reference
- [Babel]: https://babeljs.io/
 
 
 ### Floating point tests