Skip to content
Snippets Groups Projects

Update GLFM docs for official specification vs internal extensions

Merged Chad Woolley requested to merge caw-glfm-split-official-vs-extensions into master

What does this MR do and why?

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

Updates documentation to distinguish between the GLFM official specification and GLFM internal extensions. This is a follow-up to plans outlined in these threads:

Summary of changes:

  1. glfm_canonical_examples.txt is being deprecated and replaced with glfm_official_specification_examples.md and glfm_internal_extension_examples.md.
    1. See the updated diagram here: https://gitlab.com/gitlab-org/gitlab/-/blob/caw-glfm-split-official-vs-extensions/doc/development/gitlab_flavored_markdown/specification_guide/index.md#update-specificationrb-script
  2. The examples in glfm_internal_extension_examples.md will no longer allow canonical HTML to be included in the markdown examples - the HTML section will be blank (glfm_official_specification_examples.md will still require canonical HTML in all examples). The reasoning is explained in detail in the doc changes, but the summary is that...:
    1. There's no use for it, because none of the automated scripts or testing use it
    2. ...which means in addition to being useless, it's prone to becoming outdated or incorrect as the actual implementation changes
    3. It has already caused confusion in situations where we are forced to unnecessarily write it for examples where it may not make sense.

NOTE: The changes described in this documentation have not yet been implemented. The plan is to first get feedback on the direction described here, iterating on any changes in terminology/approach as necessary, then implement once we have a consensus.

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

Loading
Loading

Activity

Filter activity
  • Approvals
  • Assignees & reviewers
  • Comments (from bots)
  • Comments (from users)
  • Commits & branches
  • Edits
  • Labels
  • Lock status
  • Mentions
  • Merge request status
  • Tracking
  • Loading
  • Loading
  • Loading
  • Loading
  • Loading
  • Loading
  • Loading
  • Loading
  • Loading
  • Loading
Please register or sign in to reply
Loading