Formalize JEP Front Matter

[bollwyvl]

#53 adds a website publishing pipeline (:tada:), and can turn YAML front matter into richer display, better SEO, automation, etc.

Presently, rendering can probably never fail, and values would just be ignored or hidden.

However, these kinds of metadata are extremely useful, and not just for publishing, especially if we can make some claims about them.

Proposed is a jep-XXXX-jep-front-matter.md that could use its own front matter to validate itself and all other current and proposed JEPs.

Out of scope would be actually using this in CI, though it would be a pretty short CI action:

• install jsonschema and pyyaml (or ajv and js-yaml)
• parse as yaml the proposed JEP
• for each other *.md
  • parse the YAML
  • validate with the proposed JEP
    • show nice, human errors

Notional JEP

---
title: JEP Front Matter Schema
description: Describes a prescriptive structure for valid JEP metadata
authors:
  - @bollwyvl
type: P - Process
issue-number: 54
pr-number: <proposal-pull-request-number>  # TBD
date-started: 2020-06-15

# This document provides as Front Matter a JSON Schema which validates
# Jupyter Extension Proposal (JEP) Front Matter
title: Jupyter Extension Proposal (JEP) Front Matter
description: minimum JEP information for automated reviewing and publishing
$id: https://github.com/jupyter/extension-propsals/master/XX-jep-frontmatter-schema/jep-frontmatter-schema.md
$schema: http://json-schema.org/draft-07/schema#
type: object
additionalProperties: true

required:
  - authors
  - date-started
  - issue-number
  - pr-number
  - title
  - type

properties:
  authors:
    type: array
    items:
      type: string
    minItems: 1

  title:
    type: string

  description:
    type: text
    maxLength: 144

  issue-number:
    type: number
    minValue: 1

  pr-number:
    type: number
    minValue: 1

  date-started:
    type: string
    format: date

  type:
    description: see https://www.python.org/dev/peps/#pep-types-key
    type: string
    enum:
      - S - Standards Track
      - I - Informational
      - P - Process
---

# Summary

...

[choldgraf]

+1 from me, I'd be fine starting with the fields that are listed here.

[bollwyvl]

Thoughts on standalone JEP, or putting it into #29?

[choldgraf]

I think it's in the spirit of #29, and I believe the key/vals that you've listed are semantically-similar to the ones that were added to that PR. If we can keep the key/vals to a minimal set, it should be easier to extend moving forward as well. @captainsafia do you think that choosing some key/val metadata to validate is within-scope of #29?

[bollwyvl]

Among the many issue from the above untested schema:

• type has a constrained meaning in JSON Schema
  • perhaps jep-type?
• an constrained (e.g. tweetable), plain-text description might be good to have, so that a table can provide slightly more information than just a number and a title
  • also declared in JSON schema, which is a good sign
• the title should probably also have at least some length constraint

[choldgraf]

re: type, could it be "category"?

re: description, could we max it at N characters (maybe even 255?)

re: title, I agree