Skip to content

Implement GLFM `update-specification.rb` script

Chad Woolley requested to merge caw-glfm-update-specification-script into master

What does this MR do and why?

Resolves #360212 (closed)

Implements Gitlab Flavored Markdown Specification update-specification.rb script as described in the guide: https://docs.gitlab.com/ee/development/gitlab_flavored_markdown/specification_guide/index.html#update-specificationrb-script

The approach and implementation of this and related GLFM scripts have been discussed at length in Add GitLab-Flavored Markdown (GLFM) Specificati... (!84220 - merged). Please review the comments on that MR for more details.

Relevant discussions and decisions

  1. Why is there a new top-level directory glfm_specification? Isn't there a better place?
    1. This was determined to be the most appropriate location for these files, see details in this discussion thread: !84220 (comment 909139831)
  2. Why are there dashes instead of underscores in the scripts/lib/glfm/update_specification.rb filename?
    1. This is explained in the GLFM Specification Guide developer docs, in a note under the Scripts section
    2. See also this discussion thread, which touches on this topic: !84220 (comment 912062980)
  3. Why is the generated file glfm_specification/output/spec.txt committed to source control?
    1. This file represents the official canonical specification for GitLab Flavored Markdown (GLFM). Even though it is generated based on other inputs, it should be committed just like the corresponding GHM (GitHub Flavored Markdown) and CommonMark specifications.

How to set up and validate locally

  1. Execute scripts/glfm/update-specification.rb
  2. Review glfm_specification/output/spec.txt for correctness

MR acceptance checklist

This checklist encourages us to confirm any changes have been analyzed to reduce risks in quality, performance, reliability, security, and maintainability.

Edited by Chad Woolley

Merge request reports