Suport iteration cadence reference

What does this MR do and why?

This MR ships the feature that allows user to assign iteration by iterations cadence. Related to #384885 (closed)

Walkthrough of the updated feature

Many teams can work together in a GitLab group or project. gitlab-org/gitlab group and gitlab project are good examples.

Each team such as groupproject management may have its own set of iterations. The grouping feature for iterations is called "iterations cadences" or "cadences" for short.

groupproject management can create a cadence to house its iterations. See the list of cadence in https://gitlab.com/groups/gitlab-org/-/cadences for gitlab-org.

When working with iterations, you may want to quickly assign an issue to the current or the next upcoming iteration of your team's cadence. For instance, I may want to type

/iteration [cadence:"Plan:Project Management"] --current

in a note to assign an issue to the current iteration.

This MR enhances the existing /iteration quick action to support such capabilities.

Here's an exhaustive list of the added capabilities:

quick action	explanation
/iteration [cadence:"Plan:Project Management"] --current	Assign the current iteration from the cadence titled "Plan:Project Management"
/iteration [cadence:"Plan:Project Management"] --next	Assign the next upcoming iteration from the cadence titled "Plan:Project Management"
/iteration [cadence:123123] --current	Assign the current iteration from the cadence whose ID is 123123
/iteration [cadence:123123] --next	Assign the next iteration from the cadence whose ID is 123123
/iteration --current	This only works if a group only has ONE iterations cadence and there is no need to identify or reference an iterations cadence. It assigns the current iteration.
/iteration --next	It assigns the next upcoming iteration (again, only works if your group has one iterations cadence.)

How to set up and validate locally

1. Replicate the following group/project hierarchy by creating groups/project as needed

- root-group (Group)
    - sub-group (Group)
        - project (Project)

2. Follow the demo video to create a new Iterations Cadence and Iterations.

   • Visit Iterations page for "root-group" (note that Iterations Cadences can be only created at the group-level.)

   • Ensure to create a manual iterations cadence for easier testing.

   • Create a current iteration whose start date is <= today and end date is > today.

   • Create an iteration that will be upcoming next after the current iteration ends

Screen_Recording_2024-01-05_at_18.00.04

3. Open a new issue in the project and experiment with the updated /iteration quick action

Screen_Recording_2024-01-05_at_18.06.45

4. Test unhappy paths

On unhappy paths, the commands should fail with the message "Failed to apply commands."

- Delete all iterations and use an empty iterations cadence.

- Reference an iterations cadence that does not exist.

- Add another iterations cadence to the root group then try the convenience methods `/iteration --current` or `/iteration --next`.

Implementation notes

Implementing the enhancement to /iteration quick action required 1) adding the support for iterations cadence reference and 2) updating the quick action processing logic.

Quick action processing logic

All quick actions are implemented using the quick action DSL. /iteration is defined in ee/lib/ee/gitlab/quick_actions/issue_actions.rb.

The code's been updated to extract iterations cadence reference as well as --next and --current options.

The tests for the feature have been added to ee/spec/services/quick_actions/interpret_service_spec.rb.

Iterations cadence reference

The quick action processing logic utilizes GitLab::ReferenceExtractor that can extract GL references from an arbitrary text. For GitLab::ReferenceExtractor to recognize iterations cadences, the following updates have been made.

• Add the regex pattern describing the reference pattern for iterations cadence [cadence:<ID> or <title>] to the model ee/app/models/iterations/cadence.rb

• Implement the needed Banzai filter and parser ee/lib/banzai/filter/references/iterations_cadence_reference_filter.rb and ee/lib/banzai/reference_parser/iterations_cadence_parser.rb.

• Add the implemented parsers to the banzai pipelines.

For a detailed guide on reference processing, refer to https://docs.gitlab.com/ee/development/reference_processing.html.

Database review

1. The iterations cadence finder (and the model) got updated with an extra scope to find records by title (exact match).

2. When references are parsed, a union query is used (ee/lib/banzai/filter/references/iterations_cadence_reference_filter.rb#parent_records)

This sample query analysis covers both changes:

https://console.postgres.ai/gitlab/gitlab-production-tunnel-pg12/sessions/25119/commands/79767