Skip to content

Reorganize GLFM input and output file contents

Chad Woolleyrequested to merge
caw-glfm-reorg-input-files into master

What does this MR do and why?

Related: Tracking Issue: Implement GLFM scripts per the ... (#361241 - closed)

Refactor/rename GLFM input and output files as discussed and agreed in this thread: #375300 (comment 1131831270).

  • Remove glfm_specification/input/gitlab_flavored_markdown/glfm_intro.txt. All content for the GLFM official specification will come from glfm_specification/input/gitlab_flavored_markdown/glfm_official_specification.md
  • Rename glfm_specification/output to glfm_specification/output_spec, and glfm_specification/example_snapshots to glfm_specification/output_example_snapshots
  • glfm_specification/output_spec/spec.txt and glfm_specification/output_spec/spec.html only contain the contents of glfm_specification/input/gitlab_flavored_markdown/glfm_official_specification.md. They will NO LONGER include the GitHub Flavored Markdown or CommonMark specs.
  • Introduce glfm_specification/output_example_snapshots/snapshot_spec.md and glfm_specification/output_example_snapshots/snapshot_spec.html, which are a complete set of all examples, generated from glfm_specification/input/gitlab_flavored_markdown/glfm_official_specification.md, glfm_specification/input/gitlab_flavored_markdown/glfm_internal_extension.md, as well as the complete GitHub Flavored Markdown and CommonMark specs.
    • These snapshot_spec.* files will contain only header sections which contain snapshot examples. All prose header sections which do not contain any examples will be omitted.
  • Create/update all relevant documentation.

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

  1. In a clean recently-rebased repo, run scripts/glfm/update-specification.rb and ensure it works (i.e. there should be no changes to any files)
  2. In a clean recently-rebased repo, run scripts/glfm/update-example-snapshots.rb and ensure it works (i.e. there should be no changes to any files)
  3. [-] Verify that all spec_example_position numbers from glfm_specification/output_example_snapshots/examples_index.yml match up to the correct corresponding example in https://github.github.com/gfm/. (NOTE: This is not possible because the GFM HTML is out of date. See internal slack thread with more context.

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