Implement GLFM `update-specification.rb` script
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
- Why is there a new top-level directory
glfm_specification
? Isn't there a better place?- This was determined to be the most appropriate location for these files, see details in this discussion thread: !84220 (comment 909139831)
- Why are there dashes instead of underscores in the
scripts/lib/glfm/update_specification.rb
filename?- This is explained in the GLFM Specification Guide developer docs, in a note under the
Scripts
section - See also this discussion thread, which touches on this topic: !84220 (comment 912062980)
- This is explained in the GLFM Specification Guide developer docs, in a note under the
- Why is the generated file
glfm_specification/output/spec.txt
committed to source control?- 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
- Execute
scripts/glfm/update-specification.rb
- 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.
-
I have evaluated the MR acceptance checklist for this MR.
Edited by Chad Woolley