ref: clarify keys with examples

.github/workflows/lint.yml

@@ -1,12 +1,12 @@
 ---
 name: Yaml Lint
-on: [push]
+on: [push, pull_request]
 jobs:
   lintAllTheThings:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v1
       - name: yaml-lint
-        uses: ibiqlik/action-yamllint@master
+        uses: ibiqlik/action-yamllint@v1
         with:
           file_or_dir: ref.yml

coq-action.yml.mustache

@@ -16,7 +16,7 @@ jobs:
       matrix:
         coq_version:
 {{# tested_coq_opam_versions }}
-          - {{ version }}
+          - '{{ version }}'
 {{/ tested_coq_opam_versions }}
         ocaml_version: ['minimal']
       fail-fast: false

coq.opam.mustache

@@ -18,9 +18,7 @@ depends: [
 {{# supported_ocaml_versions }}
   "ocaml" {{& opam }}
 {{/ supported_ocaml_versions }}
-{{# supported_coq_versions }}
-  "coq" {{& opam }}
-{{/ supported_coq_versions }}
+  "coq" {{& supported_coq_versions.opam }}
 {{# dependencies }}
 {{# opam }}
   "{{ name }}" {{& version }}

extracted.opam.mustache

@@ -16,9 +16,7 @@ depends: [
 {{# extracted_supported_ocaml_versions }}
   "ocaml" {{& opam }}
 {{/ extracted_supported_ocaml_versions }}
-{{# supported_coq_versions }}
-  "coq" {{& opam }}
-{{/ supported_coq_versions }}
+  "coq" {{& supported_coq_versions.opam }}
 {{# dependencies }}
 {{# opam }}
   "{{ name }}" {{& version }}

ref.yml

@@ -1,7 +1,9 @@
 ---
-keys:
+fields:
   - fullname:
       required: true
+      description: >
+        Possibly space separated and capitalized name.
       used:
         - README.md
         - index.md
@@ -29,6 +31,8 @@ keys:
         - README.md
   - action:
       type: bool
+      description: >
+        Set to true to use the GitHub Action template.
       used:
         - README.md
   - circleci:
@@ -37,6 +41,8 @@ keys:
         - README.md
   - community:
       type: bool
+      description: >
+        Set to true if the project is part of coq-community.
       used:
         - README.md
         - index.md
@@ -61,6 +67,7 @@ keys:
         - coq.opam
   - authors:
       required: true
+      type: list
       item_fields:
         - name:
             required: true
@@ -71,6 +78,9 @@ keys:
               - extracted.opam
         - initial:
             type: bool
+            description: >
+              Initial authors are highlighted as such in the README.
+              This is especially relevant for coq-community projects.
             used:
               - README.md
               - index.md
@@ -80,6 +90,7 @@ keys:
               - coq.opam
               - extracted.opam
   - maintainers:
+      type: list
       item_fields:
         - name:
             required: true
@@ -99,6 +110,9 @@ keys:
               - index.md
         - identifier:
             required: true
+            description: >
+              Should be an SPDX identifier.
+              List available at: https://spdx.org/licenses/
             used:
               - coq.opam
               - extracted.opam
@@ -116,7 +130,13 @@ keys:
             used:
               - README.md
         - opam:
-            required: true
+            required: false
+            description: >
+              Version formula including curly brackets:
+              https://opam.ocaml.org/doc/Manual.html#Common-file-format
+              Quote the string, otherwise confuse the parser.
+            examples:
+              - '{ >= "8.10" }'
             used:
               - coq.opam
               - extracted.opam
@@ -136,6 +156,7 @@ keys:
       used:
         - default.nix
   - dependencies:
+      type: list
       item_fields:
         - description:
             required: true
@@ -152,10 +173,13 @@ keys:
               - extracted.opam
         - nix:
             required: true
+            description: >
+              The list of Coq packages in nixpkgs can be seen here:
+              https://github.com/NixOS/nixpkgs/blob/nixpkgs-unstable/pkgs/top-level/coq-packages.nix
+              Casing matters and might differ from the opam name.  The
+              leading coq- is present only if it is really an integral
+              part of the package name.
             used:
-              - README.md
-              - coq.opam
-              - extracted.opam
               - default.nix
   - categories:
       required: false
@@ -173,6 +197,9 @@ keys:
         - coq.opam
   - date:
       required: false
+      description: >
+        This can be used to regenerate an opam file with a release
+        date, for inclusion in the opam-coq-archive.
       used:
         - coq.opam
   - namespace:
@@ -181,6 +208,7 @@ keys:
         - README.md
         - coq.opam
   - publications:
+      type: list
       item_fields:
         - pub_title:
             required: true
@@ -193,6 +221,9 @@ keys:
         - index.md
   - build:
       required: false
+      description: >
+        The installation and build instructions, if the default ones
+        do not suit your project.
       used:
         - README.md
   - extracted:
@@ -230,6 +261,7 @@ keys:
                     - extracted.opam
         - extracted_dependencies:
             required: false
+            type: list
             item_fields:
               - description:
                   requied: true
@@ -245,13 +277,23 @@ keys:
             used:
               - extracted.opam
         - extracted_tested_coq_opam_versions:
+            type: list
             item_fields:
               - version:
                   required: true
+                  description: >
+                    Docker tag supported by coqorg/coq:
+                    https://github.com/coq-community/docker-coq/wiki#supported-tags
+                    Quote the strings, otherwise '8.10' becomes '8.1'.
+                  examples:
+                    - '8.11'
+                    - 'dev'
             used:
               - .travis.yml
   - documentation:
       required: false
+      description: >
+        The part of the README that is not auto-generated.
       used:
         - README.md
   - opam-file-maintainer:
@@ -266,15 +308,38 @@ keys:
         - coq.opam
         - .travis.yml
   - tested_coq_nix_versions:
+      type: list
       item_fields:
         - version_or_url:
             required: true
+            description: >
+              This can be a version number of a version packaged in
+              nixpkgs (example: 8.5, 8.11).  Cf. the coqPackages_8_XX
+              attributes defined at the end of this file:
+              https://github.com/NixOS/nixpkgs/blob/nixpkgs-unstable/pkgs/top-level/coq-packages.nix
+              (Quote the version number, otherwise '8.10' becomes '8.1'.)
+
+              Or this can be a URL, to test your project with a
+              version of Coq under development.  Typically this is
+              https://github.com/coq/coq-on-cachix/tarball/master but
+              'master' may be replaced by any valid reference like one
+              of the branches available at
+              https://github.com/coq/coq-on-cachix/branches or a valid
+              commit hash.
       used:
         - .travis.yml
   - tested_coq_opam_versions:
+      type: list
       item_fields:
         - version:
             required: true
+            description: >
+              Docker tag supported by coqorg/coq:
+              https://github.com/coq-community/docker-coq/wiki#supported-tags
+              Quote the strings, otherwise '8.10' becomes '8.1'.
+            examples:
+              - '8.11'
+              - 'dev'
       used:
         - .travis.yml
         - coq-action.yml