Add deprecation announcement for Dependendcy Scanning upgrade to GitLab SBOM Vulnerability Scanner

Be sure to link this MR to the relevant deprecation issue(s).

• Deprecation Issue: #501308

This MR adds 3 announcements:

• one global announcement for the main change and the list of all related side effects
• a dedicated announcement for "Dependency Scanning for JavaScript vendored libraries"
• a dedicated announcement for "Resolve a Vulnerability for Dependency Scanning on Yarn projects"

The justification for additional dedicated announcement has been discussed here and here:

If there is no relevant deprecation issue, hit pause and:

• Review the process for deprecating and removing features.
• Connect with the Product Manager DRI.

Deprecation announcements can and should be created and merged into Docs at any time, to optimize user awareness and planning. We encourage confirmed deprecations to be merged as soon as the required reviews are complete, even if weeks ahead of the target milestone's release post. For the announcement to be included in a specific release post and that release's documentation packages, this MR must be reviewed/merged per the due dates below:

10 days (Monday) before the Release Date: Assign this MR to these team members as Reviewer and for Approval (optional unless noted as required):

• Product Marketing: @PMM
• Product Designer(s): @ProductDesigners
• Product Group Manager or Director: @PM - Required
• Engineering Manager: @EM - Required
• Technical writer: @TW - Required

By 11:59 AM PDT 8 days (Wednesday) before the Release Date: EM/PM assigns this MR to the TW reviewer for final review and merge: @EM/PM

By 11:59 PM PDT 6 days (Friday) before the Release Date: TW Reviewer updates Docs by merging this MR to master: @TW

---

Please review:

• The definitions of "Deprecation", "End of Support", and "Removal".
• The guidelines for deprecations.
• The process for creating a deprecation announcement.

They are frequently updated, and everyone should make sure they are aware of the current standards (PM, PMM, EM, and TW).

EM/PM release post item checklist

• Set yourself as the Assignee, meaning you are the DRI.
• For breaking changes:
  • Add the breaking change label to the MR.
  • If the breaking change affects GitLab.com, add window with a value of 1, 2, or 3. The value represents the planned release window for GitLab.com, typically in the three weeks before the major release date. You should intentionally plan this window ahead of time. If you're not sure, ask @swiskow.
• Confirm this MR is labeled release post itemdeprecation
• Follow the process to create a deprecation YAML file.
• [] Add reviewers by the 10th.
• Add scoped devops:: and group:: labels as necessary.
• [] Add the appropriate milestone to this MR.
• If the changes modify log format(addition/deletion/modification) of product feature, tag @gitlab-com/gl-security/engineering-and-research/security-logging team over the GitLab issue/MR.
• When ready to be merged (and no later than the 15th) @mention the TW for final review and merge.

Reviewers

When the content is ready for review, it must be reviewed by a Technical Writer and Engineering Manager, but can also be reviewed by Product Marketing, Product Design, and the Product Leaders for this area. Please use the reviewers feature for all reviews. Reviewers will then approve the MR and remove themselves from Reviewers when their review is complete.

• (Recommended) PMM
• (Optional) Product Designer
• (Optional) Group Manager or Director
• Required review and approval: Technical Writer designated to the corresponding DevOps stage/group.

Tech writer review

After being added as a Reviewer to this merge request, the TW performs their review according to the criteria described below.

Review deprecation MRs with a similar process as regular docs MRs. Add suggestions as needed, @ message the PM to inform them the first review is complete, and remove yourself as a reviewer if it's not ready for merge yet.

Expand for Details

• Title:
  • Length limit: 7 words (not including articles or prepositions).
  • Capitalization: ensure the title is sentence cased.
• Consistency:
  • Ensure that all resources (docs, deprecation, etc.) refer to the feature with the same term / feature name.
• Content:
  • Make sure the deprecation is accurate based on your understanding. Look for typos or grammar mistakes. Work with PM and PMM to ensure a consistent GitLab style and tone for messaging, based on other features and deprecations.
  • Review use of whitespace and bullet lists. Will the deprecation item be easily scannable when published? Consider adding line breaks or breaking content into bullets if you have more than a few sentences.
  • Make sure there aren't acronyms readers may not understand per our Writing style guidelines.
• Links:
  • All links must be full URLs, as the deprecation YAML files are used in two different projects. Do not use relative links. The generated doc is an exception to the relative link rule and currently uses absolute links only.
  • Make sure all links and anchors are correct. Do not link to the H1 (top) anchor on a docs page.
• Code. Make sure any included code is wrapped in code blocks.
• Capitalization. Make sure to capitalize feature names. Stay consistent with the Documentation Style Guidance on Capitalization.
• Blank spaces. Remove unnecessary spaces (end of line spaces, double spaces, extra blank lines, and lines with only spaces).

When the PM indicates it is ready for merge and all issues have been addressed, start the merge process.

Technical writer merge process

The deprecations doc's .md file must be updated before this MR is merged:

1. Check out the MR's branch (in the gitlab-org/gitlab project).
2. From the command line (in the branch), run bin/rake gitlab:docs:compile_deprecations. If you want to double check that it worked, you can run bin/rake gitlab:docs:check_deprecations to verify that the doc is up to date.
3. Commit the updated file and push the changes.
4. Set the merge request to auto-merge, or if the pipeline is already complete, merge.

If you have trouble running the Rake task, check the troubleshooting steps.

changed milestone to %17.9

added Category:Software Composition Analysis DS-deprecationDocumentation Deliverable Enterprise Edition GitLab Ultimate SCA:Dependency Scanning Technical Writing backend breaking change deprecation devopsapplication security testing groupcomposition analysis maintenanceremoval priority1 release post release post item release post itemdeprecation sectionsec typemaintenance workflowin dev labels

assigned to @gonzoyumo

removed workflowin dev label

@gonzoyumo thanks for adding the breaking change label!

This merge request introduces breaking changes. Learn more about breaking changes.

It's important to identify how the breaking change was introduced. To estimate the impact, try to assess the following:

• Are there existing users depending on this feature?
  • Are self-managed customers affected?
  • To verify and quantify usage, use Grafana or Kibana.
  • If you're not sure about how to query the data, contact the infrastructure team on their Slack channel, #infrastructure-lounge
• Was sufficient time given to communicate the change?
• Changes in the permissions, the API schema, and the API response might affect existing 3rd party integrations.
  • Reach out to the Support team or Technical Account Managers and ask about the possible impact of this change.

This message was generated automatically. Improve it or delete it.

added pipelinetier-3 pipeline:run-e2e-omnibus-once labels

added documentation label

	1 Warning
	553ddb73: Commits that change 30 or more lines across at least 3 files should describe these changes in the commit body. For more information, take a look at our Commit message guidelines.

	1 Message
	This merge request adds or changes documentation files and requires Technical Writing review. The review should happen before merge, but can be post-merge if the merge request is time sensitive.

Documentation review

The following files require a review from a technical writer:

• doc/update/breaking_windows.md (Link to current live version)
• doc/update/deprecations.md (Link to current live version)

The review does not need to block merging this merge request. See the:

• Metadata for the *.md files that you've changed. The first few lines of each *.md file identify the stage and group most closely associated with your docs change.
• The Technical Writer assigned for that stage and group.
• Documentation workflows for information on when to assign a merge request for review.

If needed, you can retry the danger-review job that generated this comment.

Generated by Danger

added 1 commit

• 3896ab7f - Add deprecation announcements for DS build support and Gemnasium

Compare with previous version

added 1 commit

• e041d321 - Add deprecation announcements for DS build support and Gemnasium

Compare with previous version

@tkopel @johncrowley I've started this announcement but the MR template is a bit prescriptive on the DRI being either the group's EM or PM. Who's taking it from here?

Also, before starting to ping people for approvals, I have a couple of open topics we should address. I've start dedicated threads for them, could you please take a look?

Grouped announcements

As we've discussed in the issue, I've grouped all related changes in the same announcement.

Though, to increase visibility, I've also added dedicated removal items for Resolve a Vulnerability for Dependency Scanning on Yarn projects and Dependency Scanning for JavaScript vendored libraries.

I was not sure the other side effects require a dedicated item too, but I'd welcome feedback on this.

Removal vs End of support

I've written the announcements considering a removal in 18.0. Though, I wonder if we could consider switching to the "end of support" approach instead, and consider a removal in 19.0 (or 20.0) to better align with the new guidance of minimizing impact of breaking changes.

The rationale is that we have to keep maintaining the Gemnasium analyzer images working for the next 2 years (until we release GitLab 20.0), to keep providing it for Self Managed instances of GitLab 16 and 17. This means users will technically still have the ability to use the deprecated Gemnasium analyzer past the delivery of 18.0 in May 2025, granted the compatibility with GitLab 18.x doesn't break. Though, the end of support statement clearly stipulates we don't have to provide support or fixes and we no longer have to test it internally with GitLab 18.0.

How we exactly offer this can take different forms, here are two options off the top of my head:

1. keeping the old Gemnasium jobs definition in the CI template, and use the LEGACY_DEPENDENCY_SCANNING env var to revert the behavior (like we're doing for the .latest template). This provides great UX as a customer could set that variable at the instance or group level and thus minimize the manual work when upgrading to 18.0.
2. suggesting users to copy/paste the old CI job definitions in their own CI configuration or template.

We can further investigate this approach if desired. I believe this could provide a comfortable safety net for customers who are relying on the security report artifacts and can't afford to adjust their workflow in 18.0. Even for us, this options could come handy if we're facing a problem that is hard to solve with the new implementation.

Impact score

I did not fill in the impact score yet in the deprecation announcement yaml files. I've had a look at the impact calculator but I believe there is room for interpretation on some of the criteria. I'm happy to assist on this assessment if necessary.

mentioned in epic gitlab-org#15875

assigned to @tkopel

mentioned in merge request !175029 (merged)