Explain difference of methods used for rules:changes and only/except changes

Problem to solve

!209919 (merged) removes the MR diff limit dependency for rules:changes and documents a 50,000 comparison cap. However, changes under the deprecated only/except syntax still rely on a different code path (lib/gitlab/ci/build/policy/changes.rb) and likely different behavior/limits. This inconsistency is confusing for users and complicates documentation and maintenance.

This means:

• Two user-facing ways to conditionally run jobs based on changed files behave differently:
  • rules:changes uses changed_paths and a documented 50,000-comparison cap.
  • only/except:changes appears to use a separate implementation that may still be tied to MR diff limits and/or different matching logic and limits.
• Docs must explain two sets of behavior for the “same” feature.
• Users migrating from only/except to rules can be surprised by behavior differences.
• Engineers will find two similar methods in the Pipeline model that have potentially unexpected differences in behavior

Background

The following discussion from !209919 (merged) should be addressed:

• @hfyngvason started a discussion: (+2 comments)

  Not blocking: Any idea why lib/gitlab/ci/build/policy/changes.rb wasn't part of the original feature flag?

Proposal

Add comments to the #changed_paths and the #modified_paths methods to help future users (as in developers using those methods) understand that one of them is subject to MR diff limits and the other isn't and why one would want to use one or the other.