[v3] Prepare for v3 #936

ErikSchierboom · 2021-01-29T13:48:42Z

This issue is part of the migration to v3. You can read full details about the various changes here.

This PR prepares the track for Exercism v3, which will be different in a number of ways from Exercism v2.

As having this PR merged is essential to prepare this track for Exercism v3, we'll automatically merge this PR one week after it was opened (if it hasn't been merged already).

In this PR, the following changes are made:

v2 file migration

Move the existing exercises in the exercises directory to the exercises/practice directory

v3 file migration

Copy the v3 languages/<slug>/concepts directory to the concepts directory
Copy the v3 languages/<slug>/exercises/concept directory to the exercises/concept directory
Copy the v3 languages/<slug>/reference directory to the reference directory
Copy the v3 languages/<slug>/docs directory to the docs directory

Notes

Any commits modifying the aforementioned directories (or any of their files) are included in the PR, except for:

The _sidebar.md files are not migrated
The README.md file at the v3 track's root is not migrated.
The maintainers.md file is not migrated.

config.json migration

The config.json file is updated to conform to the v3 spec.

Add a version property:

"version": 3

Add online editor settings:

"online_editor": {
  "indent_style": "space",
  "indent_size": 2
}

Rename the "exercises" property to "practice"
Create an "exercises" property and move the "practice" property to this property:

"exercises": {
  "practice": [
    ...
  ]
}

Remove the "core", "auto_approve", and "unlocked_by" properties from the practice exercises
Add the "name" property to the practice exercises and pre-populate this with a titlelized version of the "slug" property
Add the "prerequisites" property to the practice exercises and set it to an empty array
Add an empty "concept" array property to the "exercises" property

"exercises": {
  "concept": [],
  "practice": [
    ...
  ]
}

Move the "foregone" property to the "exercises" key:

"exercises": {
  ...
  "foregone": [...]
}

Add a top-level "concepts" key, which is an array:

"concepts": []

Add a top-level "tags" key, which is an array:

"tags": []

Add a top-level "key_features" key, which is an array:

"key_features": []

Add a top-level "status" key, which is an object containing properties with boolean values indicating if a v3 feature is implemented:

"status": {
  "concept_exercises": true,
  "test_runner": true,
  "representer": false,
  "analyzer": false
}

Add a top-level "slug" key, which is a string containing the track's slug:

"slug": "csharp"

Re-order the practice exercises using the following ordering:
1. Core exercises, retaining their existing ordering
2. Non-core exercises, ordered by the order of the core exercise that unlocks them, then by difficulty and then alphabetically.
3. Bonus exercises, ordered by difficulty then alphabetically.
Add the "status" key with a value of "deprecated" to practice exercises that have "deprecated" set to true. The deprecated field itself is removed:

{
  "slug": "octal",
  "name": "Octal",
  "uuid": "f29f9e56-c79b-4ae4-a0d0-29db78c677e4",
  "prerequisites": [],
  "difficulty": 0,
  "topics": ["integers"],
  "status": "deprecated"
}

Notes

Settings defined in the v3 config.json file will take precedence over their v2 config.json file's equivalent.

configlet

Update the fetch-configlet and fetch-configlet.ps1 files to the latest version of configlet, which can work with v3 tracks.

Continuous integration

Add a GitHub Actions workflow to verify the track using the configlet-CI GitHub Action, unless there already is a file named .github/workflows/configlet.md.
Add a dependabot configuration to automatically submit PRs for any new versions of external workflows used in this track's GitHub Action workflows.
Convert any Exercism GitHub Actions workflows being used to use main as their branch instead of master. See this issue.

Follow-up steps

We've created issues in this repo for the follow-up steps to get this track ready for v3.

Tracking

exercism/v3-launch#11

* [Docs] Move implementing-a-concept-exercise.md to reference folder * [Docs] Move reference documents to docs folder * [Docs] Update to student-facing docs * [Docs] Add new issue template Co-Authored-By: Jeremy Walker <[email protected]> Co-Authored-By: Victor Goff <[email protected]> Co-authored-by: Sascha Mann <[email protected]>

Haskell has no methods, so another example is used.

Expand on how to deal with ambiguity between the two versions of CIS 194 available online. Expand on how to deal with concepts outside of CIS 194. Some copy-paste bugs are fixed also.

This merges the existing [v2 track's directory structure][v2] with [v3 track's directory structure][v3] as outlined in the v3 repository. In particular, the layout of multiple example solutions is preserved until Haskell track contributors come to another conclusion than the current. This discussion is extracted into exercism#893. The ordering of the files in the ASCII drawing is incidentally made so that the track-specific files are listed first. [v2]: https://github.com/exercism/haskell#directory-structure [v3]: https://github.com/exercism/v3/blob/master/docs/maintainers/generic-how-to-implement-a-concept-exercise.md

[Docs] Add reference to required reading in implementing guide

[Docs] Add reference to Concept Exercise Anatomy video

* First version of cli.md * finish cli.md * start with debug.md * fix markdown * finish debug.md * Refine cli.md

[Docs] Cross-reference concept exercise file information

I was just reading and saw this typo Matches other languages' docs and the directory in this repo.

[Docs] Add description of concept documents Co-authored-by: Jeremy Walker <[email protected]>

* Rename example files to exemplar See exercism/docs#23 * [Docs] Correct .meta/example references to .meta/exemplar * [Docs] Use exemplar instead of example * [Docs] Update example name in file listings * [Julia] Convert to exemplar.jl * [elm] Rename .meta/Cook.elm to .meta/Examplar.elm * [elm] Rename .meta/Examplar.elm .meta/Exemplar.elm Co-authored-by: Matthieu Pizenberg <[email protected]>

…ig.json

sshine

Here is a summary for my own understanding of what appears to happen in this PR:

Changes to the CI scripts

Added GitHub Actions script to run Dependabot on GitHub Actions scripts.
Added GitHub Actions script to download and run configlet.
bin/fetch-configlet changed. Not sure if/how bin/fetch-configlet and .github/workflows/configlet.yml play together. The new one seems to share characteristics of https://github.com/exercism/github-actions/blob/main/configlet-ci/fetch-configlet

Changes to the documentation shown to users

New documents: cli.md, debug.md
It is unclear if/how these two files merge with the current documentation shown to users. Current documentation shown to users is more complete.

Additions to the documentation shown to contributors

"How to implement a Haskell concept exercise": Consider how much of this information should be put in the current README, and how much should be linked between the two documents.

Why does CI fail in this PR at the time of review?

"Check track configuration" fails at the step of "Fetching the repository", but I can't find that string anywhere:

  /usr/bin/git -c protocol.version=2 fetch --no-tags --prune --progress --no-recurse-submodules --depth=1 origin +refs/heads/master*:refs/remotes/origin/master* +refs/tags/master*:refs/tags/master*
  Error: The process '/usr/bin/git' failed with exit code 1

"Check exercises (lts-from-exercises)" fails with:

ls: cannot access 'exercises/*/stack.yaml': No such file or directory
Error: Must provide filename

This appears to trigger a bug on .github/workflows/tests.yml line 101 where

            resolver=$(yq read "$(ls -1 exercises/*/stack.yaml | head -1)" resolver)

no longer activates glob patterns in "$(ls ...)"

What must happen before this PR is merged?

I will leave this as an open question.

reference/implementing-a-concept-exercise.md

config.json

reference/implementing-a-concept-exercise.md

sshine · 2021-02-01T01:57:56Z

reference/implementing-a-concept-exercise.md

+                └── .meta
+                    ├── config.json
+                    └── design.md
+```


This directory structure describes the exercises/concept/ sub-directory of which there currently aren't any examples.

The directory exercises/practice/ under this PR has the directory structure presently described in the README.

These should be merged and put in one place.

Absolutely. I'll leave this to you (the track maintainers) to fix, as you best know the structure.

I've made a preliminary fix in d6ceb1c.

reference/implementing-a-concept-exercise.md

ErikSchierboom · 2021-02-02T09:29:07Z

bin/fetch-configlet changed. Not sure if/how bin/fetch-configlet and .github/workflows/configlet.yml play together. The new one seems to share characteristics of https://github.com/exercism/github-actions/blob/main/configlet-ci/fetch-configlet

They do share characteristics, but as we know which platform the GitHub Actions script runs on, we could simplify things a bit there.

"How to implement a Haskell concept exercise": Consider how much of this information should be put in the current README, and how much should be linked between the two documents.

I'll leave this for the Haskell maintainers to decide :)

New documents: cli.md, debug.md
It is unclear if/how these two files merge with the current documentation shown to users. Current documentation shown to > users is more complete.

We've not completely finalized this spec at the moment. You can ignore these documents for now.

/usr/bin/git -c protocol.version=2 fetch --no-tags --prune --progress --no-recurse-submodules --depth=1 origin >+refs/heads/master*:refs/remotes/origin/master* +refs/tags/master*:refs/tags/master*
Error: The process '/usr/bin/git' failed with exit code 1

It looks like it is pointing to master, but we've changed all the default branches to be named main instead.

What must happen before this PR is merged?

This PR is preferrable merged as soon as possible, as this will allow the track to be tested on our staging website. The idea is that tracks then do follow-up PRs to fix any open issues.

@iHiD

Before this commit, it appears that this document was a mixture between a generic template and my initial writings about how we might go about creating a framework for implementing concept exercises, i.e., not an actual description of any agreed-upon approach to writing concept exercises on the Haskell track. Removes references to CIS 194. Removes links to generic documents that don't seem useful. Particularly: Preserve YouTube link of @iHiD talking. :)

This commit mentions that there are now two types of exercises. This section contains two broken links: - The "Unimplemented exercises" tool that we link to has been repurposed into testing whether a track is in compliance with Exercism v3. That means we no longer have an online cross-reference tool to get a list of unimplemented exercises. This link is replaced by a statement to manually cross-reference. This is not ideal, but it is possible. - "documentation on porting an exercise" now gives a 404. This link is just removed.

ErikSchierboom

We are now merging these PRs automatically so that we can continue to script further bulk-PRs to help you. For many tracks this will break CI, but we consider this a reasonable tradeoff as all Exercism tracks are in a transitionary period between now and the launch of v3.

Should have been done with 2ef2c03, which was a part of #936 This commit is part of #1083

ErikSchierboom and others added 30 commits January 29, 2021 14:48

Replace examples of kebab-case and PascalCase

505a76f

Haskell has no methods, so another example is used.

Elaborate on exercise design, fix typos

ec4de07

Expand on how to deal with ambiguity between the two versions of CIS 194 available online. Expand on how to deal with concepts outside of CIS 194. Some copy-paste bugs are fixed also.

Make after.md required

0f9b8bf

Add reference to required reading in implementing guide

20188d6

[Docs] Add reference to required reading in implementing guide

Add reference to Concept Exercise Anatomy video

dc8817f

[Docs] Add reference to Concept Exercise Anatomy video

Shared docs CLI and Debug

9cfe778

* First version of cli.md * finish cli.md * start with debug.md * fix markdown * finish debug.md * Refine cli.md

Cross-reference concept exercise file information

293196f

[Docs] Cross-reference concept exercise file information

Docs: change case of haskell directory

8a6d47c

I was just reading and saw this typo Matches other languages' docs and the directory in this repo.

Add description of concept documents

dc16e64

[Docs] Add description of concept documents Co-authored-by: Jeremy Walker <[email protected]>

[v3] Move existing exercises to exercises/practice

9c95296

[v3] Add version property to config.json

a396e26

[v3] Add status to config.json

c5c3d11

[v3] Add slug to config.json

5c4039d

[v3] Add online_editor property to config.json

ae368cf

[v3] Add status for deprecated practice exercises in config.json

a246713

[v3] Re-order practice exercises in config.json

f04e486

[v3] Remove deprecated properties from practice exercises in config.json

fb07df2

[v3] Add name property to practice exercises in config.json

a5b7b77

[v3] Add (empty) prerequisites property to practice exercises in conf…

51403f7

…ig.json

[v3] Move exercises to practice exercises property in config.json

5c71ed7

[v3] Move foregone exercises to exercises property in config.json

4a5ae88

[v3] Add concept exercises to config.json

0ec8810

[v3] Add concepts to config.json

499ee26

[v3] Add key features to config.json

23a9fb2

[v3] Add tags to config.json

1b90d6b

[v3] Add configlet CI workflow

a3ed388

[v3] Update fetch-configlet script to work with configlet v3

ca6b14a

ErikSchierboom added 3 commits January 29, 2021 14:48

[v3] Add dependabot to keep GHA dependencies up-to-date

f61c7da

[v3] Convert relative v3 links to absolute links

94ce78d

[v3] Fix configlet CI workflow

22e0b2e

sshine reviewed Feb 1, 2021

View reviewed changes

sshine added 2 commits February 3, 2021 07:57

ErikSchierboom commented Feb 5, 2021

View reviewed changes

iHiD merged commit 1cbf639 into exercism:main Feb 5, 2021

This was referenced Feb 9, 2021

Unbreak CI after v3 merge #952

Closed

Decide whether the exercises in config.json should follow any specific order #790

Open

[v3] Configure online editor #937

Closed

sshine mentioned this pull request Feb 26, 2021

Unbreak CI after v3 merge (addresses #952) #958

Closed

ErikSchierboom added the x:size/tiny Tiny amount of work label Oct 27, 2021

petertseng pushed a commit that referenced this pull request Aug 14, 2022

README: move accumulate under practice

617e9c0

Should have been done with 2ef2c03, which was a part of #936 This commit is part of #1083

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[v3] Prepare for v3 #936

[v3] Prepare for v3 #936

ErikSchierboom commented Jan 29, 2021

sshine left a comment •

edited

Loading

sshine Feb 1, 2021

ErikSchierboom Feb 2, 2021

sshine Feb 3, 2021

ErikSchierboom commented Feb 2, 2021

ErikSchierboom left a comment

[v3] Prepare for v3 #936

[v3] Prepare for v3 #936

Conversation

ErikSchierboom commented Jan 29, 2021

v2 file migration

v3 file migration

Notes

config.json migration

Notes

configlet

Continuous integration

Follow-up steps

Tracking

sshine left a comment • edited Loading

Choose a reason for hiding this comment

Changes to the CI scripts

Changes to the documentation shown to users

Additions to the documentation shown to contributors

Why does CI fail in this PR at the time of review?

What must happen before this PR is merged?

sshine Feb 1, 2021

Choose a reason for hiding this comment

ErikSchierboom Feb 2, 2021

Choose a reason for hiding this comment

sshine Feb 3, 2021

Choose a reason for hiding this comment

ErikSchierboom commented Feb 2, 2021

ErikSchierboom left a comment

Choose a reason for hiding this comment

sshine left a comment •

edited

Loading