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
- Replicate the following group/project hierarchy by creating groups/project as needed
- root-group (Group)
- sub-group (Group)
- project (Project)
-
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
- Open a new issue in the project and experiment with the updated
/iteration
quick action
Screen_Recording_2024-01-05_at_18.06.45
- 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 modelee/app/models/iterations/cadence.rb
-
Implement the needed Banzai filter and parser
ee/lib/banzai/filter/references/iterations_cadence_reference_filter.rb
andee/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
-
The iterations cadence finder (and the model) got updated with an extra scope to find records by title (exact match).
-
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