all: Define required functionality

[ErikSchierboom]

configlet is a tool to help track maintainers with the maintenance of their track. It is mostly focused on the track's config.json file, but it also works on the config/maintainers.json file.

As v3 tracks will be different from v2 track in quite some ways, it is important to consider how configlet should work for v3 tracks. In this issue, we'll list the features we want from configlet for v3 tracks.

Feature: linting

The key feature of configlet is linting: checking if the files in the track's repository are adhering to the right format. If they are not, the track won't work properly, hence this being the key feature of configlet. There are several files to lint:

• config.json: the track's main configuration file: contains track metadata, exercises and concepts.
• config/maintainers.json: the track's list of maintainers.
• exercises/{concept|practice}/[exercise-slug]/.meta/config.json: exercise-specific metadata.
• exercises/{concept|practice}/[exercise-slug]/.docs/hints.md: exercise-specific hints.
• exercises/{concept|practice}/[exercise-slug]/.docs/instructions.md: exercise-specific instructions.
• exercises/{concept|practice}/[exercise-slug]/.docs/introduction.md: exercise-specific introduction.
• exercises/shared/.docs/cli.md: explains how to use the CLI to work with exercises.
• exercises/shared/.docs/debug.md: explains how to debug using the in-browser editor.
• concepts/[concept-slug]/about.md: concept-specific documentation.
• concepts/[concept-slug]/introduction.md: concept-specific introduction (pending agreement on Update concept introductions spec v3#2767).
• concepts/[concept-slug]/links.json: concept-specific links.

Note that the most important file to lint is the config.json, which is an absolute must.

I've made an initial attempt to define the linting rules we want configlet to implement.

Feature: generate documentation (pending agreement on exercism/v3#2767)

In v3, we won't be generating README files like we did with v2.

Concept Exercises have their documentation split up into several files. Combining the files into a single README is not the track's responsibility but the v3 website's.

In V2, exercises usually have their READMEs generated from a template, which combines the exercise's README as defined in the problem-specifications repo with some track-specific additions. These additions usually consist of two bits of information: how to run the tests and how to use the CLI. In v3, we'll have an option for this cross-exercise information to be defined in shared files which will then automatically be included. This obsoletes the existing templates and its corresponding functionality in configlet. Note that tracks can have exercises that are not based on a problem-specifications exercise, in which case the README is never generated.

That said, we are currently considering a change to the spec for exercises that allows for templating to be used to include concept introductions: exercism/v3#2767 If we decide we want to support this templating proposal, configlet must be able to do this. The templating in this case will be very simple though and likely not require a full-fledged templating language.

Feature: inspecting relation between exercises (optional)

With v3 the relation between exercises via concepts and prerequisites is essential. It would be really useful for configlet to have functionality to quickly inspect this relation between exercises. This could also help detect visually things like cycles (which the linting would catch) As an alternative, we could have a simple website where one could upload a config.json file and visually see the relations. This would mean one would have to be connected to the internet though.

Current features

The current configlet version (3.9.2) supports the following commands:

"fmt" command

The fmt command can format the config.json and config/maintainers.jons files. This will ensure that these files uses consistent formatting and ordering of its keys, as well as converting topics (which will be discontinued in v3) to their correct casing. The fmt command can also be run as a dry run, which will show the diff of changes to be applied.

"generate" command

The generate command generates the exercise READMEs based on the data specified in the problem-specifications repository.

"help" command

The help command outputs instructions on how to use configlet and its commands.

"lint" command

The lint command ensures that the track is configured correctly. This means checking for missing keys, invalid values, etc.

"tree" command

The order of core exercises in v2 determined in the progression for students using mentored mode. The tree command helps visualize this progression. In v3, the progression will be different, but still important.

"version" command

The version command outputs the current version.

"upgrade" command

The upgrade command allows the configlet binary to be updated to the latest version. Most tracks don't store the configlet binary in their repo but use the fetch configlet script to download it when needed.

"uuid" command

The uuid command can be useful to quickly generate a valid UUID, although there are also websites to do this.

Implement in v3?

Migrating to v3

As implementing the uuid command is probably quite simple, so it might be worth adding.

Command	Implement?	Rationale	to
fmt	Possibly	Not everyone likes the formatting that fmt will apply to the config.json file. The formatting is also functionally irrelevant, as the v3 website will work fine with the formatting not matching that of the ftm command. Some maintainers will really like this feature, others will ignore it. I think we can safely consider this to be not essential.
generate	Possibly	The current v2 README generation will be obsoleted. If there is agreement on exercism/v3#2767 though, we'd have a new, simpler generation functionality.
help	Yes	Knowing how to use the command is very helpful
lint	Yes	The most widely used and important feature
tree	Possibly	A tree display could be useful
upgrade	No	Most track use the fetch configlet script which will always download the latest version
uuid	Possibly	Could be useful and easy to implement.
version	Possibly	Could be useful and easy to implement

---

Any thoughts of feedback welcome and appreciated!

[iHiD]

(cc @exercism/track-maintainers)

[coriolinus]

• upgrade and version aren't necessary for CI actions, but they're convenient for people working on the tracks locally. Given that the features are already implemented, I would prefer to retain them.

• I like the idea of stripping out the README generation and making that the responsibility of the website. However, there's an important, if subtle, feature which should be retained: an exercise should not necessarily need to exist in the problem-specifications repo. I suspect that this was intended, but the text describing the generate command above implied otherwise.

[ErikSchierboom]

However, there's an important, if subtle, feature which should be retained: an exercise should not necessarily need to exist in the problem-specifications repo. I suspect that this was intended, but the text describing the generate command above implied otherwise.

True. I'll try and clarify this a bit.

[verdammelt]

I use the lint & fmt features and think they would be very good to keep. I rarely used uuid as i never remembered it existed in configlet and I just used other sources for uuids.

So 👍 for keeping configlet useful in v3.

[ErikSchierboom]

Partially documented at https://github.com/exercism/v3-docs/blob/master/anatomy/tracks/configlet/README.md

[iHiD]

@ErikSchierboom Move to new configlet repo?

[ErikSchierboom]

@iHiD Done

[SleeplessByte]

generate uuid lint is what I currently use.