all: Define required functionality

`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 https://github.com/exercism/v3/issues/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](https://github.com/exercism/v3/issues/2771) we want `configlet` to implement.

## Feature: generate documentation (pending agreement on https://github.com/exercism/v3/issues/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](https://github.com/exercism/v3/blob/master/docs/concept-exercises.md#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: https://github.com/exercism/v3/issues/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](https://www.uuidgenerator.net/version4).

#### 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 https://github.com/exercism/v3/issues/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!