Support GFM References for PersonalSnippets

Matthew Macfarlanerequested to merge
mmacfarlane-master-patch-efa5 into master

Release notes item

Team members for review and approval: Engineer(s): @kivikakk | Tech Writer: @brendan777

Engineering Manager to merge when the feature is deployed and enabled: @armin.pasalic

Deprecations follow a different process.

Links

Key dates

Timeline DRI Action
Monday of milestone week or earlier PMs Draft all release post item content and submit for review
Thursday of milestone week or earlier TWs (required); PMM and PM Director/Group Manager (optional) Complete reviews of release post item content
Friday of milestone week or earlier TWs or EMs Merge content by 00:00 UTC (midnight)

Note

Not all EMs have Maintainer role, so the EM needs to rely on the TW in this case. If necessary, make the MR dependent on the code MR.

Draft your content as soon as possible to avoid missing the cutoff!

Reminder: Make sure any feature flags have been enabled or removed!

PM release post item checklist

Expand for Details

Please only mark a section as completed after you perform all individual checks!

  • Set yourself as the Assignee.
  • Why? – The benefit of this feature to the user is clearly explained
    • What is the problem we are solving for the user, and how is the situation improved?
    • Be specific about the problem, using examples so that the reader can recall the last time they had that problem.
    • Be specific about the solution, using examples so that the reader can quickly understand the improvement.
    • Describe the benefits in terms of outcomes like productivity, efficiency, velocity, communication.
    • Avoid feature language, like removing a limitation, that focuses on the product and not our users.
    • Avoid assumed knowledge, assume a customer or prospect will be linked this description without context.
  • Metadata follows guidelines:
    • title: Use seven words or fewer (excluding articles/prepositions), sentence case.
    • tier, offering, and stage: Check formatting and ordering. - Tiers, offerings, and status match the docs and features.yml
    • documentation_link: Uses a relative URL, no .md extension, links to accurate and updated docs Not every release item links to an exact match in the documentation. Just ensure the link seems appropriate.
    • work_item: Links to correct epic, issue, or MR.
    • categories: Required. Matches an existing term from categories.yml. If needed, add or update a category as described in the handbook.
    • level: If primary:
    • weight: Default 50. Only change if the release note must be listed above other items in the section. Smaller numbers are listed first, so change to a smaller number to move an item up in the list. Leave gaps for other items to be inserted above or below.
  • Content:
    • Make it clear whether the feature is new or an improvement to an existing feature.
    • Ensure all links are functional and have meaningful text for SEO (for example, use descriptive links instead of "click here").
    • Ensure that the text is fewer than 125 words.
  • Add Reviewers: When the above are complete, add the Tech Writer, PMM, and Group Manager or Director as Reviewers.
  • If this MR is a community contribution, consider nominating the contributor for MVP.
    • Check the #release-post channel in Slack for the most recent call for MVP Nominations.
    • (The MVP Nomination issue is generated around the 3rd of each month, so there is a period of time between the 18th-3rd when an open nomination issue may not yet exist.)

Review

When the above checklist is complete and the content is ready for review, it must be reviewed by Tech Writing. It can also be reviewed by Product Marketing, Product Design, and the Product Leader for this area.

Any maintainer can merge. As soon as the code is in the branch, the release notes should be updated.

Tip: Try using the Review App in this MR to see exactly how the release post item is rendered. When this MR is merged, you can view it on the release preview page.

Tech writer review

Expand for Details

After the technical writer from the corresponding group is added as a reviewer to this merge request, they perform their review.

Warning

Mark a section as complete after you perform all individual checks!

  • Metadata follows guidelines:
    • title: Uses seven words or fewer (excluding articles/prepositions), sentence case.
    • tier, offering, and stage: Check formatting and ordering. - Tiers, offerings, and status match the docs and features.yml
    • documentation_link: Uses a relative URL, no .md extension, links to accurate and updated docs
    • work_item: Links to correct epic, issue, or MR.
    • categories: Matches an existing term from categories.yml. If a category doesn't exist, the PM must add one.
    • level: If primary, matches an existing term in features.yml. If a feature doesn't exist, the PM must add one.
    • weight: Default 50. Only change if the release note must be listed above other items in the section. Smaller numbers are listed first, so change to a smaller number to move an item up in the list. Leave gaps for other items to be inserted above or below.
  • Content:
    • If possible, limit to 125 words or fewer.
    • Make text scannable. Use bullets or line breaks for multiple sentences.
    • Make sure feature name and capitalization is consistent across docs, release post, and features.yml.
    • Fix typos or grammar mistakes.
    • If possible, avoid acronyms.
    • Wrap code in code blocks.
    • Remove trailing spaces, double spaces, extra blank lines, or whitespace-only lines.

Notes:

  • If checklist items are incomplete, tell the PMs or other team members.
  • After all checklist items are done, approve the merge request, select your checkbox in the review checklist.

PMM review

PMM Review is Optional

Expand for Details

Please only mark this section as complete after you perform all individual checks! When your review is complete, please approve this MR.

  • PMM review
    • problem/solution: Does this describe the user pain points (problem) as well as how the new feature removes the pain points (solves the problem)?
      • short/pithy: Is this communicated clearly with the fewest words possible?
      • tone clarify: Is the language and sentence structure clear and grammatically correct?
      • technical clarity: Does the description of the feature make sense for various audiences, including folks who are not deeply familiar with GitLab?
    • Check/copyedit all your content blocks
    • Check/copyedit features.yml

EM release post item checklist

Expand for Details
  • When this MR is assigned to you:
    • Confirm the feature is in the release. Use a dependent MR if the release notes are dependent on the feature being merged.
      • Be aware that merging code to master does not guarantee that the feature will be in the release (source).
      • If in doubt, confirm the feature commits are in the x-y-stable-ee branch (for example, 13-12-stable-ee).
      • Changes merged into master 1+ day prior to x-y-stable-ee branch being created will likely be included in the release and release notes for those features can be merged, unless there are incident blocking pipelines or a broken master.
      • You can also use the chatops command /chatops run release check [MR_URL] [RELEASE] to check if the MR will be included in the release.
      • Note: For any MRs merged close to the cutoff date, the results are not definitive until the stable branch is cut.
    • If the feature is behind a feature flag, ensure it is enabled by default.

Merge request reports