Document the project metadata format

[palmskog]

Meta-issue

As per coq-community/manifesto#47, we need to document the various metadata items that we use in our templates, such as email for authors entries. One source of documentation is our examples, but they do not cover all cases.

We can either write regular documentation, or use some machine-readable format, such as JSON Schema or Dhall, both suggested in coq-community/manifesto#47. My vote is for JSON Schema.

This is connected to the problem of converting description files in old projects to the new (meta.yml) format.

[erikmd]

Two comments:

1. as the recommended format for metadata files in https://github.com/coq-community/templates is YAML, if you decide to stick to a machine-readable specification, this choice should ideally make it possible to validate meta.yml files (like XML Schema Definitions can validate the contents of a XML file). Even if YAML is not a subset of JSON syntax and conversely, it seems there are some popular projects that provide one of these two features (validating JSON, YAML or both), e.g.:

   • https://github.com/epoberezkin/ajv (some ajv examples can be found in this project by ZEIT, Inc.)
   • https://json-schema-everywhere.github.io/yaml, https://github.com/json-schema-everywhere/pajv
   • https://github.com/nickcmaynard/jsonschemalint
   • https://github.com/paazmaya/yaml-validator
   • https://github.com/nodeca/js-yaml

2. another idea would be to add a meta.yml file in the coq-community templates repo, and in order to ensure that that file stays in sync with the .mustache files, setup a CI test that would e.g. run mustache to test that processing the file doesn't raise any error… But this idea 2. is not incompatible with item 1. above (as the CI could run some YAML validation test)

All in all, I guess the main requirements involved are easiness for the coq-community maintainers to write their first meta.yml file (to this aim a meta.yml example might be more practical than a full-blown documentation… but maybe a sample meta.yml might directly be generated from a JSON Schema spec?), and easiness for the templates admins to maintain the .yml doc/spec/template…

[Zimmi48]

Wasn't this issue fixed by the introduction of ref.yml (as opposed to the other documentation issue #65)?