exercism / concepts

The work-in-progress project for developing v3 tracks

This repository is now archived, and its content has been exploded into the various tracks and docs repos. It now acts as a holder for any content that hasn't been migrated, and any PRs that weren't merged. Please open those PRs against the relevant track repo. Thank you to everyone who contributed to this stage of our journey towards v3 💙

---

Note: This file, and the other docs in this repository, can be viewed on GitHub or as a website with easier navigation.

Exercism - v3

Welcome to the workspace for Exercism v3!

Exercism v3 is the third major iteration of Exercism, which we are aiming to launch during 2020. It aims to both add exciting new features and to fix some of the issues present in v2, especially those around being blocked while waiting for a mentor. You can read the WIP plan here.

A summary of the main features:

• Restructured tracks: We are restructuring tracks to build new pathways containing Concept Exercises. These exercises will teach the key concepts that someone needs to know when learning a language. Completing a Concept Exercise will unlock other Concept and Practice Exercises. Concept Exercises will have automated feedback and approval, with no delays waiting for a mentor.
• Approaches: We will be automatically grouping similar solutions to Practice Exercises into Approaches. These will be supported with community-sourced articles expounding each approach, discussing its pros, cons, and potential usages.
• In-browser coding: We will be adding the ability to solve exercises within the browser. The CLI will remain as a first-class citizen, but v3 will allow people to work their way through a track without having to install anything.
• Improved profiles: Profiles will be getting an upgrade - with contributions throughout the site reflected in them. Mentoring, writing exercises, contributing to tracks, and maintaining parts of Exercism will all feature on profiles. Over time, contributing more will also have tangible improvements to your experience, with bumps up mentor queues and access to early testing features.

We are busy working away on the product and development work to add all this functionality, but we need contributors to help get our language tracks into the necessary state for v3. Our biggest need right now is for the implementation of Concept Exercises, but there are also lots of other tasks that we will need help with too. Throughout the development of v3, track maintainers will be creating issues tagged with status/help-wanted. You can choose any issue and comment saying you want to work on it, and it will then be "assigned" to you.

To get started please explore the issues in the language you wish to contribute to:

(This list is sorted alphabetically.)

• Bash
• C
• C#
• C++
• Clojure
• CoffeeScript
• Common Lisp
• Dart
• Delphi
• Elixir
• Elm
• Emacs Lisp
• Erlang
• F#
• Factor
• Go
• Haskell
• J
• Java
• JavaScript
• Julia
• Kotlin
• Nim
• OCaml
• Perl 5
• Pharo Smalltalk
• PureScript
• Python
• R
• Racket
• Raku
• ReasonML
• Ruby
• Rust
• Scala
• Scheme
• Swift
• TypeScript
• x86-64 Assembly

If you are a Track Maintainer, please start here.

More information

• The features of v3: A deeper dive into the changes we're making to v3.
• Rationale for v3. An explanation about the rationale behind some of our our design decisions for v3.

FAQs

• What are concept exercise and how they are structured?
• How is this repository structured?

concepts's Issues

[C#] Extract Concepts from v2 exercise: grade-school

Extract the list of concepts required to solve the v2 C# exercise: grade-school. For each concept, describe why it is required to solve the exercise. Keep in mind that an exercise can have multiple approaches. The goal of this task is to help determine the total list of concepts that make up C#.

The list of concepts should be stored in the following document: languages/csharp/reference/exercise-concepts/grade-school.md. Use this link to create a PR to add this document.

[Go] Concepts of scrabble (v2)

Extract a list of Go concepts needed to solve the v2 scrabble exercise. Each concept should have a short info why it's needed.

Create a PR with the file languages/go/reference/exercise-concepts/scrabble.md.

[Docs] Repository Structure

https://github.com/exercism/v3/blob/master/docs/maintainers/repository-structure.md

Above document seems slightly outdated:

Each track has it's own directory containing a README.md that outlines the concepts that are necessary to learn to become fluent in those languages

The Readme now contains the bootstrapped "track progress" file.

The concepts are now in README.md.old -- at least on the Go track. Should we explain that in the above document as well? Rename to Concepts.md?

@ErikSchierboom: I can adjust the document if the points mentioned are ok with you?

[Go] Concepts of hamming (v2)

Extract a list of Go concepts needed to solve the v2 hamming exercise. Each concept should have a short info why it's needed.

Create a PR with the file languages/go/reference/exercise-concepts/hamming.md.

[Go] Concepts of parallel letter frequency (v2)

Extract a list of Go concepts needed to solve the v2 parallel letter frequency exercise. Each concept should have a short info why it's needed.

Create a PR with the file languages/go/reference/exercise-concepts/parallel-letter-frequency.md.

[F#] Extract Concepts from v2 exercise: book-store

Extract the list of concepts required to solve the v2 F# exercise: book-store. For each concept, describe why it is required to solve the exercise. Keep in mind that an exercise can have multiple approaches. The goal of this task is to help determine the total list of concepts that make up F#.

The list of concepts should be stored in the following document: languages/fsharp/reference/exercise-concepts/book-store.md. Use this link to create a PR to add this document.

[C#] Roadmap to Launch

This issue tracks the C# v3 roadmap. If you'd like to help, please read this entire document, and then check the "How can you help" section.

Concepts

The core focus of v3 tracks is on teaching the concepts that make up a language. As such, we've been compiling a list of concepts for the C# language.

Concept exercises

To teach concepts, we're developing concept exercises, which are designed specifically to teach concepts (usually one per exercise). Concept exercises should teach students what makes C# unique. As an example, a floating-point numbers exercise's focus is on teaching how to work with floating-point numbers in C#, and less about teaching what floating-point numbers are.

It is important to understand we never explain a specific type or syntax as a concept, but teach the more "abstract" concept around it, using the type(s) or syntax(is).

Besides teaching one or more concepts, a concept exercise can have concepts the student must be familiar with before being allowed to start with the concept exercise. This is referred to as a concept exercise's prerequisites.

The concept exercises for the C# track are a work-in-progress and can be found in /concept-exercises. Important types of concepts to target are things that only exist in object-oriented programming (for people coming from non-OOP languages), functions as first-class citizens (for people coming from non-functional languages), and C# specifics like:

• Reference- and value type semantics
• Extensions methods
• ...

Already implemented

These are the exercises that have currently been implemented, as well as the concepts they teach and their prerequisite concepts:

exercise	concepts	prerequisites
numbers	basic-numbers basic-type-conversion conditionals	-
numbers-floating-point	floating-point-numbers loops	basic-numbers basic-type-conversion conditionals
strings	basic-strings	-
enums	basic-enums	basic-strings
dates	basic-dates basic-time string-formatting	basic-numbers basic-strings
bitwise-operations	bitwise-operations advanced-enums	basic-enums

⚠ Note ⚠: The idea here is to use a concept name for the exercise/folder, but perhaps use some sort of "progression", so they will naturally become a sort of path to traverse. In this example, the numbers exercise only teaches basic number usage, and the numbers-floating-point exercise builds on that and digs deeper into floating-point numbers.

It's only important that it's reasonably easy to find the exercise. It's okay if the name isn't perfect. We will iterate on this.

To be implemented

These are some planned exercises that still need to be implemented. Note: this too is an incomplete list.

exercise	concepts	assigned to
arrays	basic-arrays iteration	-
chars	basic-chars iteration	-
lists	basic-lists generics	-
sets	basic-sets sameness	-
integers	integers arithmetic-overflow advanced-type-conversion	-
classes	classes state objects	-
inheritance	inheritance polymorphism	-
higher-order-functions	higher-order-functions anonymous-methods pipelines	-
pattern-matching	pattern-matching	-
recursion	recursion	-
extension-methods	extension-methods	-
asynchrony	tasks	-

Concept interpretation

Here is how the C# track has interpreted the following concept keywords. This should be synced across tracks.

concept	interpretation
basic-numbers	Know of the existence of the two most commonly used number types, int and double, and understand that the former represents whole numbers, and the latter floating-point numbers. Know of basic operators such as multiplication and comparison. Know where it's documented, or at least how to search for it.
basic-strings	Know of the existence of the string type. Know of some basic functions (like looking up a character at a position, or slicing the string). Know how to do basic string formatting. Know where it's documented, or at least how to search for it.
basic-dates	Know of the existence of the DateTime type. Know of the individual, date-related properties. Know how to access the current date. Know how to compare dates. Know how to convert a string to a DateTime and vice versa. Know where it's documented, or at least how to search for it
basic-enums	Know of the existence of the enum keyword. Know how to define enum members. Know how to convert a string to an enum and vice versa. Know where it's documented, or at least how to search for it
advanced-enums	Know how to define a "flags" enum. Know how to add, remove or check for flags.
basic-time	Know of the existence of the DateTime type. Know of the individual, time-related properties. Know where it's documented, or at least how to search for it.
basic-type-conversion	Know that it is sometimes possible to convert from one type to another type.
conditionals	Know of the existence of conditional execution statements (such as the if statement).
floating-point-numbers	Know of the existing of the three floating point types: double, float and decimal. Know when to use which type.
string-formatting	Know how to format a string. Know where it's documented, or at least how to search for it.
bitwise-operations	Know how to apply bitwise operations to numbers. Know where it's documented, or at least how to search for it.

This also indicates that for example basic-strings does not teach using custom formatting strings and that basic-numbers does not teach about checked/unchecked arithmetic.

Documentation

There are three folders containing documentation:

• /info: C# concepts (like namespaces).
• /keywords: C# keywords (like using).
• /types: C# core types (like string).

This documentation can be used both as a starting point when creating concept exercises, as well as being referred to from exercises.

How can you help?

Documentation

There are C#-specific documentation files in the /info, /keywords and /types folders. Some of the files in these folders will be empty or stubs, others will be missing. We'd love PR's to add this documentation. You can use the already filled-in ones to see what we're looking for.

To find which concepts are missing, compare the files in the /info folder with the concepts listed in the README. For the keywords, compare the files in the /keywords folder with the C# keywords list. Finally, for the types, compare the files in the /types folder with the types listed in the README.

There are also general documentation files missing, most notably missing concepts in the root /concepts folder.

Exercises

We need two types of exercises. The concept ones, as explained above -- you can choose to pick one from the "To be implemented" list above or suggest, in this issue, one that's not listed. The other ones are the practice ones, which are like the v2 exercises.

Analyzers

TBD

[F#] Extract Concepts from v2 exercise: meetup

Extract the list of concepts required to solve the v2 F# exercise: meetup. For each concept, describe why it is required to solve the exercise. Keep in mind that an exercise can have multiple approaches. The goal of this task is to help determine the total list of concepts that make up meetup.

The list of concepts should be stored in the following document: languages/fsharp/reference/exercise-concepts/meetup.md. Use this link to create a PR to add this document.

[Go] Status Update

@ErikSchierboom: I would like to update the check boxes on https://github.com/exercism/v3/tree/master/languages/go.

Just to make sure:

• Go Test Runner can be considered finished, right?
• Go Test Runner can also be considered deployed?
• Go Analyzer: finished and deployed? Or is this another analyzer this document is talking about? Or is support for all concept exercises a criteria? Another criteria?

[Go] How to implement a Go concept exercise

This document needs a first implementation. It should be targeted at non-maintainers that want to help out on a one-off basis.

As a start I suggest to look at C#'s implementation guide and adjust that to Go's needs. From there it can be improved as we as maintainers get a better understanding of the process ourselves.

As a base we can copy this: https://github.com/exercism/v3/blob/master/docs/maintainers/generic-how-to-implement-a-concept-exercise.md

[Docs] Giving credit and citing sources

This is a write-up of an AMA question on Slack, which itself was a follow-up question to a previous discussion. It's meant as a discussion starter.

@NobbZ, @Stargator, @iHiD, @ErikSchierboom, @SleeplessByte, @kotp thanks for engaging in the discussion around my question. Please edit the post and correct me if you feel that I've misrepresented one of your points in this write-up. Despite the topic, I chose to not cite everyone individually to keep it more concise, I hope that's okay with you.

---

Right now, the concept docs lack any kind of consistency when it comes to citing the sources they're based on. Some are direct quotes but lack any kind of source, others have an APA style citation, and some are original works not based on an existing source.

There seemed to be a consensus that if sources are used, they should be properly attributed. However, what "properly attributed" means is unclear. Therefore it would be useful to agree on a minimum standard.

Sidenote: This is primarily about the concept documents used "internally", not the docs exposed to students.

Why should sources be cited?

• Legal reasons (although the documents are for "internal" purposes, they're still publicly available).
• A way to thank the original creator for creating a wonderful resource.
• The documents are a source of truth and need to be verifiable.
• They can help understand the concept/problem better.
• The docs can also contain info that can be readily copy-pasted into exercise READMEs.

How should they be cited?

There was no consensus on this. The following ways were brought up:

• Link dump (a list of links used while creating the source)
• Only adding sources for direct quotes, otherwise adding links where one can find more but not directly citing non-quoted content.
• Deep-linking could be hard to maintain in the long run.
• Cite the original author, URL, date of creation/last modification (explicitely state if those are not available), publisher.
• Putting the citation in a comment.

This brings up further questions that need to be considered:

• Does every document need to have sources or are documents written purely from pre-existing knowledge okay, too?
• Are the citations purely for giving attribution or do they also serve as a way to verify the contents of the doc?
• Do we even want a citation guide to refer to, or do we leave it up to whomever submits and reviews the PR?

There are two "Repository Structure" headings

https://github.com/exercism/v3/blob/master/README.md#repository-structure-1

I don't know which heading is wrong or what it should be changed to.

[Docs] Methods concept has circular reference

The Methods concept https://github.com/exercism/v3/blob/master/reference/concepts/methods.md is defined as a function that is part of a class. It links to the function concept (as well as the class concept.

The Function concept however, is defined using "method": By "functions" we mean functions, methods and procedures.. This is a circular reference.

To me this is made more confusing by the rest of the function concept which covers what the concept is not.

Especially confusing is: We do not aim to teach: "functions" as the concept of self-contained pieces of functionality ... If this is not the definition of a function, I'm not sure what is 😄 (unless referring to the term "function" here in the non-programming sense, but that still doesn't help describe "method"... or "function").

[C#] Extract Concepts from v2 exercise: book-store

Extract the list of concepts required to solve the v2 C# exercise: book-store. For each concept, describe why it is required to solve the exercise. Keep in mind that an exercise can have multiple approaches. The goal of this task is to help determine the total list of concepts that make up C#.

The list of concepts should be stored in the following document: languages/csharp/reference/exercise-concepts/book-store.md. Use this link to create a PR to add this document.

Ask a question: V3

Should there be a link to the github page generated for this repository in the README? or at least in the description of the repository? https://exercism.github.io/v3 is built via actions, and seems to be pretty key to help people stay up to date on what is happening.

v3/concepts: files to write

Here is a list of concepts that don't currently exist but probably should. Feel free to add more/change/tick.

• member: https://en.wikipedia.org/wiki/Member_variable
• property: https://en.wikipedia.org/wiki/Property_%28programming%29
• field: https://en.wikipedia.org/wiki/Field_(computer_science)
• function overloading: https://en.wikipedia.org/wiki/Function_overloading
• optional parameters: https://en.wikipedia.org/wiki/Named_parameter#Optional_parameters
• mixins: https://en.wikipedia.org/wiki/Mixin
• reflection: https://en.wikipedia.org/wiki/Reflection_(computer_programming)
• attributes: https://en.wikipedia.org/wiki/Attribute_(computing)

[Rust] Extract Concepts from v2 exercise: poker

Extract the list of concepts required to solve the v2 Rust exercise: poker. For each concept, describe why it is required to solve the exercise. Keep in mind that an exercise can have multiple approaches.

The list of concepts should be stored in the following document: languages/rust/reference/exercise-concepts/poker.md. Use this link to create a PR to add this document.

It can be helpful to also include a sample solution in the document.

[C#] Extract Concepts from v2 exercise: nucleotide-count

Extract the list of concepts required to solve the v2 C# exercise: nucleotide-count. For each concept, describe why it is required to solve the exercise. Keep in mind that an exercise can have multiple approaches. The goal of this task is to help determine the total list of concepts that make up nucleotide-count.

The list of concepts should be stored in the following document: languages/csharp/reference/exercise-concepts/nucleotide-count.md. Use this link to create a PR to add this document.

[Rust] Bootstrap Rust track

Let's get this started!

[Java] Bootstrap Java track

It's time to start

[Go] Concepts of yacht (v2)

Extract a list of Go concepts needed to solve the v2 yacht exercise. Each concept should have a short info why it's needed.

Create a PR with the file languages/go/reference/exercise-concepts/yacht.md.

[C#] Add new Concept Exercise: arrays

This issue describes a new arrays exercise that should be added to the v3 C# track.

Goal

The goal of this exercise is to teach the student how the concept of collections is implemented in C#. We'll teach the student about collections by having the student work with one specific type of collection, namely the array. The students will learn to define arrays, iterate over array items, access items by index, and more.

Of the many available C# collection types, we chose to use the array collection type as the first collection type students will be taught for the following reasons:

• Arrays don't require the student to know about generics.
• Arrays are a common data type in many language.
• Arrays have a fixed length. No complexity in adding or removing elements.
• Arrays have a simple shorthand syntax. No need to understand how constructors work to define an array.

Learning objectives

• The existence of the Array type.
• Defining an array.
• Accessing elements in an array by index.
• Iterating over elements in an array.
• Basic array functions (like finding the index of an element in an array).

Out of scope

• Multi-dimensional/jagged arrays.
• Memory and performance characteristics of arrays.
• Enumerables.
• Iterators.
• LINQ.

Concepts

This Concepts Exercise's Concepts are:

• arrays: know of the existence of the Array type; know how to define an array; know how to access elements in an array by index; know how to iterate over elements in an array; know of some basic functions (like finding the index of an element in an array).
• foreach-loops: know how to iterate over a collection.

Any data types used in this exercise (e.g. strings) should also be added as prerequisites.

Prequisites

This Concept Exercise's prerequisites Concepts are:

• basics: define variables and methods.
• for-loops: know how to use a for loop.

Any data types used in this exercise (e.g. strings) should also be added as prerequisites.

Resources to refer to

Hints

• Arrays
• Single-dimensional arrays
• Usings foreach with arrays

After

• Collections
• Implicitly typed arrays

As this is an introductory exercise, we should take care not to link to very advanced resources, to prevent overwhelming the student.

Representer

This exercise does not require any specific representation logic to be added to the representer.

Analyzer

This exercise could benefit from having an analyzer that can comment on:

• Difference between for vs foreach loops.

Implementing

If you'd like to work on implementing this exercise, the first step is to let us know through a comment on this issue, to prevent multiple people from working on the same exercise. If you have any questions while implementing the exercise, please also post them as comments in this issue.

Implementing the exercise means creating the following files:

languages
└── csharp
    └── exercises
        └── concept
            └── arrays
                ├── .docs
                |   ├── after.md
                |   ├── hints.md
                |   ├── instructions.md
                |   └── introduction.md
                ├── .meta
                |   ├── design.md
                |   └── Example.cs
                ├── Arrays.csproj
                ├── Arrays.cs
                └── ArraysTests.cs

Step 1: add .docs/introduction.md

This file contains an introduction to the concept. It should be explicit about what the exercise teaches and maybe provide a brief introduction to the concepts, but not give away so much that the user doesn't have to do any work to solve the exercise.

Step 2: add .docs/instructions.md

This file contains instructions for the exercise. It should explicitly explain what the user needs to do (define a method with the signature X(...) that takes an A and returns a Z), and provide at least one example usage of that function. If there are multiple tasks within the exercise, it should provide an example of each.

Step 3: add .docs/hints.md

If the user gets stuck, we will allow them to click a button requesting a hint, which shows this file. We will softly discourage them using it. The file should contain both general and task-specific "hints". These hints should be enough to unblock almost any student.

Step 4: add .docs/after.md

Once the user completes the exercise they will be shown this file, which gives them any bonus information or further reading about the concept taught.

These files are also all described in the [concept exercises document][docs-concept-exercises].

Step 5: update languages/csharp/config.json

An entry should be added to the track's config.json file for the new concept exercise:

{
  ...
  "exercises": {
    "concept": [
      ...
      {
        "slug": "arrays",
        "uuid": "b6c532c9-1e89-4fbf-8f08-27f5befb5bb8",
        "concepts": ["arrays", "foreach-loops"],
        "prerequisites": ["for-loops"]
      }
    ]
  }
}

Step 6: adding track-specific files

These files are specific to the C# track:

• Arrays.csproj: the C# project file.
• ArraysTests.cs: the test suite.
• Arrays.cs. the stub implementation file, which is the starting point for students to work on the exercise.
• .meta/Example.cs: an example implementation that passes all the tests.

Check out the floating-point-numbers exercise for an example on what these files should look like.

Step 7: update the general concept document

Add the exercise to the concept's shared document's ## Implementations section (example).

Step 8: updating list of implemented exercises

• Add the exercise to the list of implemented exercises.

Step 9: add .meta/design.md:

This file contains information on the exercise's design, which includes things like its goal, its teaching goals, what not to teach, and more ([example][meta-design]). This information can be extracted from this GitHub issue.

Inspiration

When implementing this exericse, it can be very useful to look at already implemented C# exercises like the strings, dates or floating-point numbers exercises. You can also check the general array concept documentation to see if any other languages have already implemented an arrays exercise.

[Go] Bootstrap Go Track

Or is this already done?

[Rust] Extract Concepts from v2 exercise: parallel-letter-frequency

Extract the list of concepts required to solve the v2 Rust exercise: parallel-letter-frequency. For each concept, describe why it is required to solve the exercise. Keep in mind that an exercise can have multiple approaches.

The list of concepts should be stored in the following document: languages/rust/reference/exercise-concepts/parallel-letter-frequency.md. Use this link to create a PR to add this document.

It can be helpful to also include a sample solution in the document.

[F#] Extract Concepts from v2 exercise: protein-translation

Extract the list of concepts required to solve the v2 F# exercise: protein-translation. For each concept, describe why it is required to solve the exercise. Keep in mind that an exercise can have multiple approaches. The goal of this task is to help determine the total list of concepts that make up F#.

The list of concepts should be stored in the following document: languages/fsharp/reference/exercise-concepts/protein-translation.md. Use this link to create a PR to add this document.

Maintainers: Start here

@exercism/track-maintainers: The most valuable first step to take is to put together a bit of a Roadmap for your track from today until v3. @SleeplessByte has put together an fantastic example for JavaScript, which could serve well as a basis for how these could look for your track.

Please feel free to use this issue to discuss the best way to get started :)

[PureScript] Setup PureScript for V3

Can PureScript be created for v3. I'd like to help maintain it.

Ask a question: Hierarchical concepts

Should we implement some kind of hierarchical ontology for concepts?

Motivation: smaller concept can be grouped together and can be referred in more agile way.

For example (non-exhaustive list),

Collections
    - Modifying
        - Adding
        - Shuffling
    - Search
        - Searching element index
    - Fetching data
        - Fetching single element
        - Fetching multiple elements
        - Sub-collection
        - Windowing
    - Sorting
        - Asc
        - Desc
        - Random
    - Transformations
        - Mapping
        - Zipping
    - Filtering
    - Folding
    - Slicing

instead of big concept collections or collections-basic + collection-advanced.

This will increase number of concepts in general but they can be represented in a fine-granular way and will allow us to include link exercises with a particular aspect of concept.

What do you think?

[Go] Implement new Concept Exercise: strings

A concept exercise on working with strings.

Closely sticking to the C# concept exercise on this one: https://github.com/exercism/v3/tree/master/languages/csharp/exercises/concept/strings

[Elixir] Add Elixir issues link to README.md

Description

In response to the steps towards v3 for elixir, we need to add a link to elixir's v3 issues in the main v3 readme file

This would be a good PR to complete if it's one of your first in the exercism ecosystem.

Contributing

• fork the repo, in a branch make the changes needed to the README.md, submit a PR for the changes to the master.

Help

If you have any questions while adding the reference document, please post the questions as comments in this issue.

Ping: @nathanchere, @fireproofsocks, or anyone else. Please reference this issue in the PR

[Go] Concepts of two fer (v2)

Extract a list of Go concepts needed to solve the v2 two fer exercise. Each concept should have a short info why it's needed.

Create a PR with the file languages/go/reference/exercise-concepts/two-fer.md.

[Scala] Extract Concepts from v2 exercise: <Hamming>

Extract the list of concepts required to solve the v2 Scala exercise: Hamming. For each concept, describe why it is required to solve the exercise. Keep in mind that an exercise can have multiple approaches (you can find community solutions here: https://exercism.io/tracks/scala/exercises/hamming/solutions). The goal of this task is to help determine the total list of concepts that make up hamming.

The list of concepts should be stored in the following document: languages/scala/reference/exercise-concepts/hamming.md. Use this link to create a PR to add this document.

[C#] Extract Concepts from v2 exercise: bowling

Extract the list of concepts required to solve the v2 C# exercise: bowling. For each concept, describe why it is required to solve the exercise. Keep in mind that an exercise can have multiple approaches. The goal of this task is to help determine the total list of concepts that make up bowling.

The list of concepts should be stored in the following document: languages/csharp/reference/exercise-concepts/bowling.md. Use this link to create a PR to add this document.

[C#] Extract Concepts from v2 exercise: protein-translation

Extract the list of concepts required to solve the v2 C# exercise: protein-translation. For each concept, describe why it is required to solve the exercise. Keep in mind that an exercise can have multiple approaches. The goal of this task is to help determine the total list of concepts that make up C#.

The list of concepts should be stored in the following document: languages/csharp/reference/exercise-concepts/protein-translation.md. Use this link to create a PR to add this document.

Ask a question: Can we fix the link-checker in this repo?

The link-checker CI check is bumming me out.

• When it fails, I get 1800 lines of output, but the actual error isn't highlighted.

• When I scroll to the culprit on line 773 (there you are!), the failed link is this:

  FILE: ./languages/csharp/exercises/concept/dates/.docs/hints.md
  [✖] https://csharp.net-tutorials.com/data-types/working-with-dates-time/
  
  6 links checked.
  [✖] https://csharp.net-tutorials.com/data-types/working-with-dates-time/ → Status: 0
  

  which means to say, (a) this link works when I check it, so it's a flaky check, (b) this link is not in my pull request, so my pull request has failed because of a link placed in another part of the repo at another point in time.

Perhaps the link-check run during pull requests should be limited to the files being changed? Then periodic link-checking can report on existing links that are broken, so that I don't have to address C#-related links when pushing Haskell-related documentation that has no links.

Also, wrt. flakiness, one strategy we have at work is to run it twice and only report failure if it fails in both cases. Otherwise the amount of links added over time will make the link-check fail a linearly growing percentage of the time.

[Elixir] Need maintainers.md created/populated

In response to the steps towards v3 for elixir, we need a maintainers.md created in this repo at exercism/v3/languages/elixir/maintainers.md

This would be a good PR to complete if it's one of your first in the exercism ecosystem.

As it states in the readme, see the C# maintainers.md for the pattern to follow.

Ping: @nathanchere, @fireproofsocks, or anyone else. Please reference this issue in the PR

[C#] Extract Concepts from v2 exercise: robot-name

Extract the list of concepts required to solve the v2 C# exercise: robot-name. For each concept, describe why it is required to solve the exercise. Keep in mind that an exercise can have multiple approaches. The goal of this task is to help determine the total list of concepts that make up C#.

The list of concepts should be stored in the following document: languages/csharp/reference/exercise-concepts/robot-name;.md. Use this link to create a PR to add this document.

Ask a question: Limit CI workflow runs to languages

https://github.com/exercism/v3/actions?query=workflow%3A%22Julia+CI%22

Julia CI seems to run on each push. Is it possible to check if it was a push to a .../julia/exercises/**/*? I love the idea of adding JavaScript CI and TypeScript CI but don't want to waste everyone's time and GH resources.

---

Summary of the responses below.

You can restrict Actions workflows to only run when they affect files in a language directory by using the following trigger conditions:

on:
  push:
    paths:
    - '**.$EXT'
    - 'languages/$SLUG/**'
  pull_request:
    paths:
    - '**.$EXT'
    - 'languages/$SLUG/**'

Further notes on using Actions:

If you use any action in your workflow that requires access to the GitHub token or other secrets, use the commit hash of the release instead of the version tag. Version tags are mutable and a malicious actor could point them at whatever code they want, thus gaining access to this repo. Note that you should use commit hashes for all actions in the workflow, because they could manipulate the environment to inject their code even if the action itself doesn't have access to any secrets.

For example:

jobs:
  triage:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/labeler@04aa5dbc72538e0b9194c658a9ad6026b865d039 # 2.1.0
      with:
        repo-token: "${{ secrets.GITHUB_TOKEN }}"

instead of

    - uses: actions/[email protected]

Ask a question: Review-and-merge policy

(Note: I accidentally hit Ctrl+Enter in the edit window, which apparently submits the form.)

It seems that this is at least the third repository in my time at Exercism that sees a lot of cross-track activity. The other repositories that I'm comparing this repository to are website-copy that has drowned in pull-requests and problem-specifications that has drowned in disagreement.

With 20+ pull requests opened in the last 24 hours and 17 open right now, we are soon to decide which of our strategies will be picked. If neither seem satisfactory, now would be a good time to come up with an alternative.

So for example @tehsphinx submitted some typo fixes. I had no problem just approving and merging those, even though they were addressed to @ErikSchierboom. He'll see them and there's no conflict. But my own first pull request, #50, I must have somehow missed a formatting rule. Not sure it's really a rule as much as emergent behavior that @tehsphinx had noticed and I hadn't, so great synergy. But then @bergjohan submits #81 where ## Contributing Maintainers is removed. I thought "Huh, there's no precedence here. I think I'll just approve that, and do it myself in #50, and this must constitute emergent behavior." I merged it and @bergjohan eventually changed his mind, and so did I (keeping the headline and "Not yet." below it).

#54 is pretty clearly addressed from @ErikSchierboom to @iHiD, but as @tehsphinx points out, we also want to get it merged ASAP. So lots of trigger-ready people and no clear direction why it's not merged yet.

It'd be neat if we could just say "code owners approve and merge", but then I might need to approve my own pull requests. If that's where we're at, we will probably need to document some more formats. If not, we'll probably need to create some pull request policies. We have some ad-hoc rules on the Haskell track (exercism/haskell#752) for comparison. For example, a convention of writing under which circumstances something can be merged, provided either by the author of the pull request or the reviewer (conditional approval). Because the criteria may change after the original pull request message is made, it'd be nice to have a policy about when to merge/squash/rebase commits might be warranted.

[CI] Linkchecker output is huge and in case of failure not helpful

In #213 the dead-link checker failed (which I kind of expected), and out of curiosity I looked into the output.

The full log contained ~2000 lines of which about half are only empty lines.

There has been no summary at the end, except a single line in red "##[error]Process completed with exit code 123.".

Even though I knew the name of the file that failed, I was not able to search the page for the name of the file, nor parts of it. The built-in search of the browser will only search in the currently visible area of the log.

Also the files are not scanned in any obvious order (I'd assume some timestamp rather than lexicographically).

So there is currently no easy way to find out where the link checker failed, not even if the name of the failing file is known.

And even after finding the link, it does only tell us the problematic link target, but not where in that document the link target is set:

FILE: ./languages/erlang/docs/implementing-a-concept-exercise.md
[✖] ../exercises/concept/README.md

1 links checked.

ERROR: 1 dead links found!
[✖] ../exercises/concept/README.md → Status: 400

An error message like the following is usually more helpful, as "jump to line" is much easier in most editors than search and go:

ERROR: 1 dead links found!
./languages/erlang/docs/implementing-a-concept-exercise.md:35:22: ../exercises/concept/README.md → Status: 400

I could just copy paste this into my editor and it would move from any open file to exactly the location of the link definition. Regardless of the active file.

Though I think we can't easily change the output. Though a summary should be possible by slightly rewriting the current step.

---

edit

#153 might already improve the issue of discoverability during PRs, though in case of scheduled runs that cover all files, the situtation probably wont change.

[Haskell] Add new reference document: Concept Exercise Implementation Guide

This issue discusses forming Haskell's Concept Exercise Implementation Guide.

Description

Haskell track's Concept Exercise Implementation Guide should describe the guidelines for adding new concept exercises to Haskell track. This issue proposes a formulation where concept exercises are modelled after the CIS 194 Haskell course at Penn University as taught over the years.

The main design strategy asks the contributor to identify at what point in the CIS 194 course a particular concept exercise would fit in. A concept exercise can either be modelled after an existing homework exercise of the course, or it can be tailored to fit something that is deemed missing or would be useful as a bridge between two existing concepts.

• Before this issue is closed for completion, two checkmarks one checkmark can be added to Haskell track's v3 README: "Write a Concept Exercise implementation guide", "List out key Concepts for your language".

Resources to refer to

CIS 194 course page has two publicly available incarnations to consider:

https://www.seas.upenn.edu/~cis194/fall16/ (Joachim Breitner)
https://www.seas.upenn.edu/~cis194/spring13/ (Brent Yorgey)

Their variations should give ample room for contributors to disagree about particulars.

Contributing

To avoid merge conflicts, contributors are adviced to report in this issue before working on any of these:

• languages/haskell/docs/concepts.md: Extract key concepts from CIS 194 course material. The example given is C#'s concepts, but since the same taxonomy does not apply for Haskell, coming up with a different one is necessary here.
• languages/haskell/docs/implementing-a-concept-exercise.md: Expand on the formulation in the description of this issue.

Help

If you have any questions while adding the reference document, please post the questions as comments in this issue.

[Rust] Extract Concepts from v2 exercise: decimal

Extract the list of concepts required to solve the v2 Rust exercise: decimal. For each concept, describe why it is required to solve the exercise. Keep in mind that an exercise can have multiple approaches.

The list of concepts should be stored in the following document: languages/rust/reference/exercise-concepts/decimal.md. Use this link to create a PR to add this document.

It can be helpful to also include a sample solution in the document.

[C#] Extract Concepts from v2 exercise: change

Extract the list of concepts required to solve the v2 C# exercise: change. For each concept, describe why it is required to solve the exercise. Keep in mind that an exercise can have multiple approaches. The goal of this task is to help determine the total list of concepts that make up C#.

The list of concepts should be stored in the following document: languages/csharp/reference/exercise-concepts/change.md. Use this link to create a PR to add this document.

[CI] Need to check configuration

In #162 an invalid config.json sneaked in.

We need to set up blocking CI that will automatically deny changes that make the JSON syntactically invalid.

On top of that we could introduce a JSON schema against we also check for semantic validity of the document, similar to how it is done in the problem-specification repository already.

[Elixir] Roadmap to Launch

This issue is to track the Elixir v3 roadmap. If you intend to help with this track, please read this entire document, and find the section about "How can you help".

Modelled from @SleeplessByte's excellent javascript roadmap writeup.

---

This is a working tool to brainstorm the contents of the v3 elixir track by compiling a list of elixir specific concepts. The concepts can be found here.

Folder structure

Specifics for elixir concepts can be found in the /info folder. There are other special folders such as /keywords, which take the keyword, and explain what they do, as they are language-specific (mostly), and the [/types][types] folder which would be /classes in many other languages: it lists the built-in types available.

Concept exercises

The concept exercises in the Elixir track are a work-in-progress and can be found in /concept-exercises. Important types of concepts to target are things that only exist in dynamic and functional programming (for people coming from non-functional languages), actor model concurrency primitives, and elixir specifics:

• first-class functions
• higher-order functions
• pure functions
• recursion
• strict vs non-strict evaluation (lazy vs eager)
• referential transparency (immutable data)
• data representation (lists, tuples, maps, etc.)

It is important to understand we never explain a specific type or syntax as a concept, but teach the more "abstract" concept around it, using the type(s) or syntax(is).

A list of exercises that we must have is compiled below, and is not at all a complete list:

• "basic-lists"
• "recursion"
• ...

⚠ Note ⚠: The idea here is to use a concept name for the folder, but perhaps use some sort of "progression", so they will naturally become a sort of path to traverse. In this example, the numbers exercise only teaches basic number usage, and doesn't look into more advanced subjects. I would expect to see:

• numbers-advanced for mathy usage that is non-basic,
• numbers-irrational showing how to do irrational / complex / whatever numbers,
• numbers-precision which would explore binary representation and floating points,
• numbers-arbitrary-precision which would explore big integers and/or how to do that with decimals.

It's only important that it's reasonably easy to find the exercise. It's okay if the name isn't perfect. We will iterate on this.

Concept interpretation

This should be synced across tracks.

concept	interpretation
basic-numbers	Know of the existence of the number type and (for this language) see that it's whole numbers, and floating points. Know of basic operators such as multiplication. Know where it's documented, or at least how to search for it.
basic-strings	Know of the existence of the string type. Know of some basic functions (like looking up a character at a position, or slicing the string). Know where it's documented, or at least how to search for it.
basic-lists	Know of the list construct (array type in some other languages). Know of some basic functions and ways to use them.
basic-errors	Know how to create an error, how throw it and how to catch it
callbacks	Know how to use a function as a first-class citizen, that is, pass it into a function as a value, and call it somewhere inside that function. Know that you can pass in values and retrieve out return values.
recursion	Know how to call a function from itself
type-conversion	Know that there exist functions that can convert between "types" (objects of a prototype) and types (primitives).

This also indicates that for example basic-strings does not include knowing that Elixir strings are made up of UTF-8 codepoints. Knowledge about how strings differ from charlists may be covered in later basic-charlists or basic-binary.

How can you help?

This track

There are files in the /info, /keywords and [/types][types] folders which are either empty or stubs. They need to be written. You can use the already filled-in ones to see what we're looking for.

Globally

There are concepts missing.

Exercises

We need two types of exercises. The concept ones, as explained above -- you can chose to pick one from the list above or suggest, in this issue, one that's not listed. The other ones are the practise ones, which are like the v2 exercises.

Analyzers

TBD

[F#] Extract Concepts from v2 exercise: bob

Extract the list of concepts required to solve the v2 F# exercise: bob. For each concept, describe why it is required to solve the exercise. Keep in mind that an exercise can have multiple approaches. The goal of this task is to help determine the total list of concepts that make up bob.

The list of concepts should be stored in the following document: languages/fsharp/reference/exercise-concepts/bob.md. Use this link to create a PR to add this document.

[Clojure] Bootstrap Clojure track

Excited to help make this track the best it can be.

[Ruby] Extract Concepts from v2 exercise: nucleotide-count

Extract the list of concepts required to solve the v2 Ruby exercise: nucleotide-count. For each concept, describe why it is required to solve the exercise. Keep in mind that an exercise can have multiple approaches. The goal of this task is to help determine the total list of concepts that make up nucleotide-count.

The list of concepts should be stored in the following document: languages/ruby/reference/exercise-concepts/nucleotide-count.md. Use this link to create a PR to add this document.

[Julia] Roadmap to Launch

This issue is to track the Julia v3 roadmap. If you intend to help with this track, please read this entire document, and find the section about "How can you help".

---

I have been working on the Julia v3 track by compiling a list of Julia specific concepts, transition documents from various languages and starting writing exercises. The concepts can be found here.

The track README contains a summary of relevant results from the Julia User & Developer Survey June 2019. The learnings from the survey and the "What was it like to learn Julia?" issue can be helpful to find out what people struggle with, what concepts are important to most people, and therefore the track and exercise design.

Folder structure

Concept exercises

The concept exercises in the Julia track are a work-in-progress and can be found in /concept-exercises. Important types of concepts to target are things that only exist in Julia or are different to languages many people use before/instead of Julia.

It is important to understand we never explain a specific type or syntax as a concept, but teach the more "abstract" concept around it, using the type(s) or syntax(is).

Some listed concepts, like performance or type piracy, aren't typical language features, but rather they are concepts that people commonly struggle with when they are new to Julia, or features that are the reason why they use Julia. While these might be closer to "proficiency" rather than "fluency", they should be considered in order to teach good habits to write generic and performant code early on.

I personally found it easier to start by writing an exercise for one concept (in my case multiple dispatch) , and then working out which concepts are a prerequisite to solve it and which concepts can be introduced with that knowledge, than writing a long list of concepts first.

⚠ Note ⚠: The idea here is to use a concept name for the folder, but perhaps use some sort of "progression", so they will naturally become a sort of path to traverse. A WIP document with the progression path can be found here.

It's only important that it's reasonably easy to find the exercise. It's okay if the name isn't perfect. We will iterate on this.

How can you help?

This track

Writing concept exercises

Either take a concept from the readme or from the WIP progression document and implement or write it. You can also add rough outlines of exercises to the document if you have a vague idea of an exercise but are unsure about the details.

I don't know what the best way of writing new exercises is, but here's how I created the multiple dispatch exercise:

1. Find the concept the exercise is meant to teach/introduce
2. Make yourself clear what the student is meant to know after solving the exercise. I do this by coming up with short questions that the student should be able to answer afterwards.
3. Find an existing v2 exercise that can be adapted to teach this concept, check the concept document in this repo for exercises in other languages that could be adapted, find examples for this concept in talks, the Julia manual or other resources, or create something completely from scratch. In the case of multiple dispatch, I took an example from Stefan Karpinski's Juliacon talk about the concept.

Once I knew what the exercise is about, what the "story" is, and what a solution could look like, I implemented the example solution and narrowed it down as much as possible, similarly to creating an MWE when asking a question. I'm not going to list the steps of actually writing the exercise, because their order is quite variable depending on the exercise and concept. For example, it's also possible to start by writing a test suite or the instructions.

5. Think about how it fits into the progression. What are the prerequisite concepts? What concepts can be "unlocked" through implementing this exercise? This can also be done as the first step, but I found that it only became clear once I actually created the exercise. See also: progression.md

Writing concept documents

Many of the concept links don't lead anywhere. You can help out by writing short descriptions of what the concept is, both specifically to Julia and across languages.

Globally

There are concepts missing.

Exercises

We need two types of exercises. The concept ones, as explained above -- you can chose to pick one from the list above or suggest, in this issue, one that's not listed. The other ones are the practice ones, which are like the v2 exercises.

Analyzers

TBD

Priorities

Any help is appreciated! However, if you have to choose between different ways to contribute, I think the most useful right now is implementing a new concept exercise. Once we have a few of them, it will be much easier to iterate on the progression, think about missing concepts, and so on.

---

It's important to note that we're all new to this and there will be a lot of trial and error. Most new exercises or concept documents won't be perfect in their first version, so don't hesitate to contribute even if you feel unsure about whether or not something works or doesn't!

---

An easier view to keep track of all issues can be found in the Projects section of the repo: Concept Exercise Board, Concept Extraction Board

[Rust] Extract Concepts from v2 exercise: macros

Extract the list of concepts required to solve the v2 Rust exercise: macros. For each concept, describe why it is required to solve the exercise. Keep in mind that an exercise can have multiple approaches.

The list of concepts should be stored in the following document: languages/rust/reference/exercise-concepts/macros.md. Use this link to create a PR to add this document.

It can be helpful to also include a sample solution in the document.