Skip to content

Implement GLFM `update-example-snapshots.rb` script

Chad Woolley requested to merge caw-glfm-spec-impl into master

What does this MR do and why?

Important note: Read the GLFM specification developers guide - it contains detailed documentation on the code and files involved in this MR.

Implements initial iteration of Gitlab Flavored Markdown Specification update-example-snapshots.rb script as described in the guide: https://docs.gitlab.com/ee/development/gitlab_flavored_markdown/specification_guide/index.html#update-example-snapshotsrb-script (NOTE: I just noticed that I am missing glfm_specification/input/gitlab_flavored_markdown/glfm_example_status.yml as an input file in this flowchart, this is being fixed in a separate docs MR - Update GLFM docs to fix flowchart (!86528 - merged))

The purpose and format of the input and output files are described in the developer guide too, with examples:

NOTE: Here is an MR which expands and adds separate headings for the various input and output files: !86604 (merged)

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.

Wow, isn't this MR big?

Yes. But it's still a minimal cohesive initial implementation of the logic for the script. Other functionality will be added in follow-on MRs (see epic).

We could break up this initial implementation into multiple MRs, but IMO that would make it harder to understand the overall goal of the script, and how it all works together.

Also, even though the line count is high, much of that is the generated files in spec/fixtures/glfm/example_snapshots; there's less than ~500 lines of non-comment, non-spec new code.

Relevant discussions and decisions

IMPORTANT: See the Relevant discussions and decisions section on MR !85640 for background info on the approach used in this script.

How to set up and validate locally

  1. Execute scripts/glfm/update-example-snapshots.rb
  2. Review all files in spec/fixtures/glfm/example_snapshots 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