Convert GLFM examples from old GM approach
What does this MR do and why?
Related: Tracking Issue: Implement GLFM scripts per the ... (#361241 - closed)
Moves all GitLab Flavored Markdown Examples from old "Golden Master" based approach to the new snapshot-based approach.
Examples were moved from:
spec/fixtures/markdown/markdown_golden_master_examples.yml
ee/spec/fixtures/markdown/markdown_golden_master_examples.yml
...into:
glfm_specification/input/gitlab_flavored_markdown/glfm_internal_extensions.md
References
See the GLFM Specification Guide development documentation for much more context on all of this work: https://docs.gitlab.com/ee/development/gitlab_flavored_markdown/specification_guide
How to set up and validate locally
As long as CI is green, it should be ok, but you can do the following:
- Run
scripts/glfm/run-snapshot-tests.sh
and ensure all the specs it runs work.- Note: It appears this didn't trigger the relevant backend and frontend tests to run in the CI pipeline. This has been captured in a follow up task here: #361241 (closed)
- For now, pipeline:run-all-jest and pipeline:run-all-rspec have been added to ensure tests are passing.
- Run
scripts/glfm/update-specification.rb
andscripts/glfm/update-example-snapshots.rb
and ensure there are no changes to any generated GLFM files - Ensure there are no occurrences of
Error - check implementation
inglfm_specification/output_example_snapshots/html.yml
or other output files.- Note: These should really probably fail the script. Added a follow-up task to implement this here: #361241 (closed)
Helper script
I wrote the following script (but did not commit) to help with the conversion. Pasting here for future reference:
scripts/glfm/migrate-from-golden-master.rb
:
#!/usr/bin/env ruby
# frozen_string_literal: true
require_relative '../lib/glfm/migrate_from_golden_master'
Glfm::MigrateFromGoldenMaster.new.process
scripts/lib/glfm/migrate_from_golden_master.rb
:
# frozen_string_literal: true
require 'yaml'
module Glfm
class MigrateFromGoldenMaster
def process
gm_examples_path = Pathname.new(
File.expand_path("../../../spec/fixtures/markdown/markdown_golden_master_examples.yml", __dir__)
)
ee_gm_examples_path = Pathname.new(
File.expand_path("../../../ee/spec/fixtures/markdown/markdown_golden_master_examples.yml", __dir__)
)
rendered_html_hash = YAML.safe_load(File.open(gm_examples_path), symbolize_names: true, aliases: true)
ee_rendered_html_hash = YAML.safe_load(File.open(ee_gm_examples_path), symbolize_names: true, aliases: true)
print_examples(rendered_html_hash)
print_examples(ee_rendered_html_hash)
end
private
def print_examples(rendered_html_hash)
rendered_html_hash.each do |example|
name = example.fetch(:name)
markdown = example[:markdown]
html = example[:html]
puts <<~MARKDOWN
### #{name}
```````````````````````````````` example gitlab
#{markdown}
.
TODO: Write canonical HTML for this example
````````````````````````````````
MARKDOWN
end
end
end
end
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.