github.com/exercism/configlet@v3.9.3-0.20200318193232-c70be6269e71+incompatible/README.md (about)

     1  # Configlet
     2  
     3  A tool for managing Exercism language track repositories.
     4  
     5  ## Lint
     6  
     7  Exercism makes certain assumptions about language tracks. The configlet `lint` command makes it simple to verify up-front that the changes to a track's configuration, as well as changes and additions to the exercises will play nicely with the website.
     8  
     9  `configlet lint` checks for the following configuration issues:
    10  
    11  1. `config.json` contents that are invalid according to [the specification](https://github.com/exercism/problem-specifications/blob/master/CONTRIBUTING.md#track-configuration-file).
    12  1. Inconsistencies between the lists of track slugs in `config.json` and the corresponding implementation files:
    13      * Slugs referenced in `config.json` that have no corresponding implementation.
    14      * Slugs referenced in `config.json` whose implementation is missing an example solution.
    15      * Implementations for slugs that are not referenced in `config.json`.
    16      * Implementations for slugs that have been declared as foregone in `config.json`.
    17  
    18  ## Format
    19  
    20  Inspired by Go's [`gofmt`](https://blog.golang.org/go-fmt-your-code) tool, configlet's `fmt` command will consistently format a track's configuration files.
    21  
    22  `configlet fmt` formats according to the following rules:
    23  
    24  1. The JSON files, `config.json` and `maintainers.json` will be indented by 2 spaces.
    25  1. In the `config.json` file:
    26      * Exercises will have their list of topics sorted alphabetically.
    27      * Topics names will be normalised to be lowercase and contain underscores in place of spaces.
    28  
    29  ## Generate
    30  
    31  The configlet `generate` command may be used to generate README's for all exercises on the track, as a whole or individually. The overall purpose of this command is to utilize common [`problem-specifications`](https://github.com/exercism/problem-specifications) data in generating a *template-based* README for each exercise, while at the same time permitting overrides of this data on a track exercise basis.
    32  
    33  Using this command for README generation allows for some conveniences:
    34  
    35  1. The use of a track specific README template file.
    36  1. The automatic inclusion of information from the `problem-specifications` repository.
    37  1. Allow overrides of that `problem-specification` data on a per-exercise basis.
    38  1. The ability to insert language specific exercise information ("hints") to an exercise README.
    39  1. Full customization of a README template per exercise (if necessary).
    40  
    41  `generate` looks for specific files in the track root's `config/` directory and in each exercise's `.meta/` directory. It will then use these files, if present, and the `problem-specifications` data to generate an exercise's README.
    42  
    43  Much of the utility of this command comes from the ability to *locally override* README templates and exercise information.
    44  
    45  (When working with READMEs you may find [a local renderer for GitHub Markdown](https://github.com/joeyespo/grip) helpful to preview your work before committing.)
    46  
    47  ### The README Template
    48  
    49  The template file used as the basis for README generation lives in a track root's `config/` directory as [`config/exercise_readme.go.tmpl`](https://github.com/exercism/lua/blob/master/config/exercise_readme.go.tmpl). This template file may be overridden for an exercise by placing the overriding template in the exercises `.meta/readme.go.tmpl`.
    50  
    51  As configlet is written in the [Go language](https://golang.org/) this README template file is in the [Go template format](https://golang.org/pkg/text/template/).
    52  
    53  There are a number of template variable substitutions you may place in the template file:
    54  
    55  #### .Spec.Description
    56  
    57  This variable is sourced from an exercise's [`description.md`](https://github.com/exercism/problem-specifications/blob/master/exercises/hamming/description.md) file in the `problem-specifications` repo. You may override this variable's contents for an exercise by adding a `.meta/description.md` file in that track exercise's directory.
    58  
    59  #### .Spec.Credits
    60  
    61  The credits are a description of the source of an exercise with an optional hyperlink to that source. This information originates from the [`metadata.yml`](https://github.com/exercism/problem-specifications/blob/master/exercises/hamming/metadata.yml) located in the exercise's `problem-specifications` entry. You may override this information for an exercise by adding a `.meta/metadata.yml` file in that track exercise's directory.
    62  
    63  #### .Spec.Name
    64  
    65  This variable is a readable version of the exercise's slug in [title case](https://golang.org/pkg/strings/#Title). There are alternative formats of the name available. These formats may be useful if you need to [reference the exercise name](https://github.com/exercism/groovy/blob/1ffee8ea0df4492b349e367ac9ba88f1124bc038/config/exercise_readme.go.tmpl#L13) in regards to tooling.
    66  
    67  | Variable            | Contents
    68  | --------            | --------
    69  | .Spec.Slug          | difference-of-squares
    70  | .Spec.Name          | Difference Of Squares
    71  | .Spec.MixedCaseName | DifferenceOfSquares
    72  | .Spec.SnakeCaseName | difference\_of\_squares
    73  
    74  #### .TrackInsert
    75  
    76  Language tracks will most likely have some unique information common to every exercise in the track (testing, environment configuration, etc...). This may be placed in a track's `config/exercise-readme-insert.md` file the contents of which will then be available in this template variable.
    77  
    78  #### .Hints
    79  
    80  Exercises may have information specific to that exercise's implementation in the track language (for example, the introduction of a specific language concept). In this case placing a [`.meta/hints.md`](https://github.com/exercism/go/blob/nextercism/exercises/leap/.meta/hints.md) in that track exercise's directory will make those contents available in this template variable.
    81  
    82  ## Tree
    83  
    84  The track configuration file can be hard to review. The `tree` command can help with the process of setting up your configuration file. It will:
    85  
    86  1. Display the core track exercises and unlocked exercises as a tree.
    87  1. List out the bonus exercises separately.
    88  1. Issue warnings if expected elements from the configuration are missing.
    89  1. Optionally show the difficulty of the exercises via the `--with-difficulty` option.
    90  
    91  ## Upgrade
    92  
    93  The configlet `upgrade` command downloads and installs the latest released version of configlet. Running the upgrade command on an already up-to-date version of configlet will exit with no change to the system. The version command `configlet version -l` can be used to check for the latest available version.
    94  
    95  
    96  ## UUID
    97  
    98  Exercises in each track config.json file must have a [UUID](https://en.wikipedia.org/wiki/Universally_unique_identifier). You may request a randomly generated exercise UUID from configlet using:
    99  
   100  ```bash
   101  $ configlet uuid
   102  78aa565f-632d-47c0-a190-5144c91d0e33
   103  ```
   104  
   105  ### Usage
   106  
   107  ```bash
   108  $ configlet [command] <path/to/track>
   109  ```
   110  
   111  If you have [installed the configlet binary](https://github.com/exercism/configlet/releases/latest)
   112  and are at the root of an exercism language track, then you can run the following:
   113  
   114  ```bash
   115  $ configlet [command] .
   116  ```
   117