Shared metadata for exercism exercises.
Shell
Latest commit 089f3e9 Jan 17, 2017 @petertseng petertseng committed on GitHub CONTRIBUTING: remind about adding to config.json (#495)
In various tracks, I sometimes see contributors forget to do this, and
perhaps one cause is that the requirement isn't mentioned here (various
tracks link to this document to explain how to port an exercise to their
track).

Luckily, this gets caught by configlet (assuming the track is running
Travis CI and hasn't removed configlet), but it would be good to let
contributors to know of this up front.

Decision: This text explcitly mentions the `"exercises"` key, rather
than the deprecated `"problems"` key.

The following procedure:

    gem install trackler --ignore-dependencies
    # substitute your Ruby version for $RUBY_VERSION
    grep -L exercises ~/.gem/ruby/$RUBY_VERSION/gems/trackler-2.0.6.10/tracks/*/config.json

says that only two tracks lack the `exercises` key: Ceylon and PL/SQL

* a PR exercism/xplsql#16 is open for PL/SQL
* a PR exercism/xceylon#8 has already been
  merged in Ceylon and will go out in the next Trackler update.

Therefore, it almost certainly safe to use the `exercises` key!

One weakness is that this text doesn't explicitly mention the `slug` or
`difficulty` or `topics` keys for each entry in the `exercises` array.
This weakness is currently mitigated by the fact that active languages
should have many examples to go off of. The only time where there are no
examples will be when starting a brand-new track.

README.md

x-Common

Shared metadata for Exercism exercises. The doc/ subdirectory contains all documentation that is not specific to a language track.

Contributing Guide

Please see the contributing guide

Problem metadata

Each problem's data lives in a directory under exercises/

exercises/
├── accumulate
│   ├── description.md
│   └── metadata.yml
├── ...
├── minesweeper
│   ├── canonical-data.json
│   ├── description.md
│   └── metadata.yml
├── ...
└── zipper
    ├── description.md
    └── metadata.yml

There are three metadata files:

  • description.md - the basic problem description
  • metadata.yml - additional information about the problem, such as where it came from
  • canonical-data.json (optional) - standardized test inputs and outputs that can be used to implement the problem

Test Data Format (canonical-data.json)

This data can be incorporated into test programs manually or extracted by a program. The file contains a single JSON object with a key for documentation and keys for various tests that may be meaningful for a problem.

The documentation uses the key "#" with a list of strings as the value. These strings document how the problem readme (description.md) is generally interpreted in test programs across different languages. In addition to a mainstream implementation path, this information can also document significant variations.

Each test case has the the following keys:

  • description: which will be used to name each generated test
  • 'variable names': one or more variable names with values which will be passed to the solution method
  • expected: the expected result (this would be -1 when we expect an exception)
  • msg: a nice message for the failing case

Automated Tests

The only thing that we're testing at the moment, is whether or not canonical-data.json is valid json.

If you want to run this before you commit, you will need to install jq. Then run the script with:

bin/jsonlint

License

The MIT License (MIT)

Copyright (c) 2014 Katrina Owen, _@kytrinyx.com