diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 1776ce369a..ccb705f719 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -29,10 +29,9 @@ Please keep the following in mind: exercise. - Each problem should have a test suite, an example solution, and a template - file for the real implementation. The example solution should be named - `example.exs`. + file for the real implementation. Read about [the anatomy of practice exercises][https://github.com/exercism/docs/blob/main/anatomy/tracks/practice-exercises.md] or [the anatomy of concept exercises][https://github.com/exercism/docs/blob/main/anatomy/tracks/concept-exercises.md], depending on to which type of exercise you want to contribute. -- Use typespecs in the example and template files as described [here](http://elixir-lang.org/getting-started/typespecs-and-behaviours.html). +- For practice exercises, use typespecs in the example and template files as described [here](http://elixir-lang.org/getting-started/typespecs-and-behaviours.html). - Each test file should have a `test_helper.exs` with code like the following at the top of the file. This allows the tests to be run on CI and configures diff --git a/README.md b/README.md index d14f162a2b..039a12f64f 100644 --- a/README.md +++ b/README.md @@ -14,7 +14,7 @@ installation instructions can be found at --- -> It is recommended to test BEFORE submitting a PR. It will test your submission, ensure +> It is recommended to test BEFORE submitting a PR. It will test your submission, ensure > that the repository builds as a whole, and help guard against unintentional, unrelated changes. --- @@ -44,11 +44,13 @@ cd exercises/$EXERCISE_NAME mix test ``` -### Testing the Build +### Dialyzer -TravisCI is used to test the build against different environments. +To run dialyzer on all exercises, run `./bin/dialyzer_check.sh`. It might take a really long time the first time you run it. It will also be run for you by Github Actions as part of the PR check. -TravisCI's current testing routine can be found in [.travis.yml](https://github.com/exercism/elixir/blob/master/.travis.yml) +### Code and document formatting + +To check formatting of all exercises and all documents, run `./bin/check_formatting.sh`. It will also be run for you by Github Actions as part of the PR check. ## Contributing Guide diff --git a/reference/implementing-a-concept-exercise.md b/reference/implementing-a-concept-exercise.md index bc6f580bcc..784b467451 100644 --- a/reference/implementing-a-concept-exercise.md +++ b/reference/implementing-a-concept-exercise.md @@ -6,11 +6,12 @@ This document describes how to implement a Concept Exercise for the Elixir track - [The features of v3][docs-features-of-v3]. - [Rationale for v3][docs-rationale-for-v3]. -- [What are concept exercise and how they are structured?][docs-concept-exercises] +- [What are concepts and how they are structured?][anatomy-of-a-concept] +- [What are concept exercise and how they are structured?][anatomy-of-a-concept-exercise] Please also watch the following video: -- [The Anatomy of a Concept Exercise][anatomy-of-a-concept-exercise]. +- [The Anatomy of a Concept Exercise][anatomy-of-a-concept-exercise-video]. As this document is generic, the following placeholders are used: @@ -23,35 +24,35 @@ As this document is generic, the following placeholders are used: - `$first-and-last-name`: your first and last name (e.g. `Tim Austin`) - `$git-email`: the email address you use for git (e.g. `tim@neenjaw.com`) -Before implementing the exercise, please make sure you have a good understanding of what the exercise should be teaching (and what not). This information can be found in the exercise's GitHub issue. Having done this, please read the [Elixir Concept exercises introduction][concept-exercises]. If you have come up with something completely new, create a new issue _first_ so we can discuss the Concept Exercise. +Before implementing the exercise, please make sure you have a good understanding of what the exercise should be teaching (and what not). This information can be found in the exercise's GitHub issue. If you have come up with something completely new, create a new issue _first_ so we can discuss the Concept Exercise. To implement a Concept Exercise, the following files must be added: ```text -languages -└── elixir - ├── concepts - | └── $concept-1 - | ├── about.md - | └── links.json - └── exercises - └── concept - └── $slug - ├── .docs - │ ├── instructions.md - │ ├── introduction.md - │ └── hints.md - ├── .meta - │ ├── config.json - │   ├── design.md - │ └── exemplar.ex - ├── lib - │   └── $elixir_slug.ex - ├── mix.exs - ├── mix.lock - └── test - ├── $elixir_slug_test.exs - └── test_helper.exs +elixir +├── concepts +| └── $concept-1 +| ├── about.md +| ├── introduction.md +| └── links.json +└── exercises + └── concept + └── $slug + ├── .docs + │ ├── instructions.md + │ ├── introduction.md + │ └── hints.md + ├── .meta + │ ├── config.json + │ ├── design.md + │ └── exemplar.ex + ├── lib + │ └── $elixir_slug.ex + ├── mix.exs + ├── mix.lock + └── test + ├── $elixir_slug_test.exs + └── test_helper.exs ``` ## Step 1: Add code files @@ -61,24 +62,20 @@ The configuration files may be copied from another exercise. But it would be rec Now create the following three files: - `lib/$elixir_slug.ex`. the stub implementation file, which is the starting point for students to work on the exercise. -- `test/$elixir_slug_test.ex`: the test suite. +- `test/$elixir_slug_test.exs`: the test suite. - `.meta/exemplar.ex`: an exemplar implementation that passes all the tests. ## Step 2: Add documentation files How to create the files common to all tracks is described in the [how to implement a concept exercise document][how-to-implement-a-concept-exercise]. -## Step 3: Update list of implemented exercises - -- Add the exercise to the [list of implemented exercises][implemented-exercises]. - -## Step 4: Add analyzer (optional) +## Step 3: Add analyzer (optional) Some exercises could benefit from having an exercise-specific [analyzer][analyzer]. If so, specify what analysis rules should be applied to this exercise and why. _Skip this step if you're not sure what to do._ -## Step 5: Add representation (optional) +## Step 4: Add representation (optional) Some exercises could benefit from having an custom representation as generated by the [Elixir representer][representer]. If so, specify what changes to the representation should be applied and why. @@ -94,12 +91,11 @@ If you have any questions regarding implementing the exercise, please post them [analyzer]: https://github.com/exercism/elixir-analyzer [representer]: https://github.com/exercism/elixir-representer -[concept-exercises]: ../exercises/concept/README.md [how-to-implement-a-concept-exercise]: https://github.com/exercism/v3/blob/main/docs/maintainers/generic-how-to-implement-a-concept-exercise.md -[docs-concept-exercises]: https://github.com/exercism/v3/blob/main/docs/concept-exercises.md [docs-rationale-for-v3]: https://github.com/exercism/v3/blob/main/docs/rationale-for-v3.md [docs-features-of-v3]: https://github.com/exercism/v3/blob/main/docs/features-of-v3.md -[anatomy-of-a-concept-exercise]: https://www.youtube.com/watch?v=gkbBqd7hPrA +[anatomy-of-a-concept]: https://github.com/exercism/docs/blob/main/anatomy/tracks/concepts.md +[anatomy-of-a-concept-exercise]: https://github.com/exercism/docs/blob/main/anatomy/tracks/concept-exercises.md +[anatomy-of-a-concept-exercise-video]: https://www.youtube.com/watch?v=gkbBqd7hPrA [reference]: https://github.com/exercism/v3/blob/main/reference/README.md -[config-json]: https://github.com/exercism/v3/blob/master/docs/concept-exercises.md#metaconfigjson -[implemented-exercises]: ../exercises/concept/README.md#implemented-exercises +[config-json]: https://github.com/exercism/docs/blob/main/anatomy/tracks/config-json.md