Implementation/COMMS-1046: Labels in the work package schema and labels-by-workspace API by akabiru · Pull Request #25552 · opf/openproject

akabiru · 2026-09-23T20:57:04Z

https://community.openproject.org/wp/COMMS-1046

Adds labels to the work package schema behind the work_package_labels flag, linking its allowed values to a new GET /api/v3/workspaces/:id/labels that orders labels by relevance for the workspace: labels already used there first, then the most used overall, then by name.

Label assignments now take part in the work package cache checksum, so a labels-only change is no longer served stale, and exports print label names while the flag hides the attribute from form configuration and exports when off. Nested collection endpoints also honour offset and pageSize, which they silently ignored before.

AI involvement

Collaborative – AI generated a substantial part of the code; I reviewed and understand every line.

github-actions · 2026-09-24T14:06:30Z

Warning

Flaky specs

rspec ./spec/features/notifications/navigation_spec.rb[1:1:1]
rspec ./spec/features/roles/report_spec.rb[1:2]
rspec ./spec/features/roles/report_spec.rb[1:3]

🤖 Ask Copilot to investigate

Copy the prompt below into a new comment on this PR to delegate the investigation to GitHub Copilot. It will look into the flakiness and open a separate pull request with you as reviewer.

@copilot The following spec(s) are flaky in CI (first seen on PR #25552, linked for reference only):

- `rspec ./spec/features/notifications/navigation_spec.rb[1:1:1]`
- `rspec ./spec/features/roles/report_spec.rb[1:2]`
- `rspec ./spec/features/roles/report_spec.rb[1:3]`

Treat this as a standalone task, unrelated to PR #25552. Create a new branch from origin/dev and open a new pull request targeting dev — do not stack it on PR #25552 or reuse that branch.

Follow the playbook in docs/development/testing/handling-flaky-tests/README.md to find the root cause and fix the underlying race — do not skip, delete, or weaken the spec to make it pass; disabling is a last resort per the playbook, and only with a bug ticket. Verify the fix by running the spec(s) repeatedly (e.g. `script/bulk_run_rspec --run-count 10`).

If you cannot reproduce the flake or are not confident in a fix after reasonable investigation, do not fabricate a change or skip the spec to force CI green. Instead, leave the pull request in draft and document what you tried, the suspected cause, and any leads in its description, then assign @akabiru to take over.

Once the fix is verified, title the PR after the spec(s) it fixes, and use the PR description to explain the root cause, how the change resolves it, and the before/after results. Label the PR `flaky-spec`, assign @akabiru, and request a review from @akabiru.
On every commit, set @akabiru as the sole co-author with a `Co-authored-by:` trailer (use their GitHub no-reply email so it links to their account), so it is traceable who dispatched the fix.

akabiru · 2026-09-24T15:23:58Z

+  scope :ordered_by_relevance_for, ->(project) {
+    used_in_project = Labeling
+                        .where(labelable_type: WorkPackage.name)
+                        .where("labelings.label_id = labels.id")
+                        .joins("INNER JOIN work_packages ON work_packages.id = labelings.labelable_id")
+                        .where(work_packages: { project_id: project })
+                        .arel
+                        .exists
+
+    reorder(used_in_project.desc)
+      .order(Arel.sql("#{USAGE_COUNT_SQL} DESC"))
+      .order("LOWER(labels.name) ASC")


🤖 Benchmark: Label.ordered_by_relevance_for

The labels dropdown calls this endpoint with pageSize=-1 (clamped to apiv3_max_page_size, 1000 by default) and re-queries with a name ~ filter on each keystroke, so I benchmarked the exact SQL the index endpoint runs at three data sizes. Data was bulk-inserted with a skewed labeling distribution, the target project holding ~1-2% of work packages. Timings are server-side query times in ms (median / p95 over 19 warm runs).

Scenario (labels / labelings / WPs) Unfiltered Filtered total count Alphabetical baseline

Small (100 / 10k / 5k) 4.7 / 68.7 0.7 / 1.9 0.3 1.9

Medium (1k / 100k / 50k) 97.2 / 114.5 1.2 / 2.6 0.3 31.6

Large (10k / 1M / 500k) 627.5 / 841.8 5.0 / 5.9 0.6 274.2

Where the time goes. The "used in this project" EXISTS is cheap: Postgres turns it into a hashed subplan that runs once (loops=1). The cost is the correlated usage_count subquery, which runs once per label (loops=10000, ~1M buffer hits at the large size). The name filter is applied before those subqueries are evaluated, so the per-keystroke filtered path stays in single-digit ms even at the large size. Only the first, unfiltered open of the dropdown gets slow, and only on instances with thousands of labels and ~1M labelings.

Alternatives tried (large size only):

Rewrite Unfiltered Filtered

EXISTS as a CTE ~623 not run

usage_count via one GROUP BY ~227 not run

Both combined ~90 ~87

The combined rewrite returns the same order and brings the unfiltered open under 100ms, but it makes every filtered keystroke ~17x slower (5ms to 87ms), because aggregating over all labelings is a fixed cost the name filter can't reduce.

Decision: keeping the current query. The keystroke path is fast at every size, and the slow case is a first open on very large instances. If that becomes a real problem, the GROUP BY rewrite can be applied to the unfiltered request only.

Nice. This gives confidence. Thanks for making it.

Labels are global and unbounded, so allowed values are linked to a project-scoped endpoint rather than embedded. The flag joins the schema cache dependencies so toggling it does not serve stale schemas.

The work package labels dropdown needs labels already used in the current workspace first, then the most used ones, so the schema points at this endpoint instead of the global listing.

Assigning labels does not touch the work package row, so without this the cached JSON representation kept serving the previous labels.

The form attribute list is derived from the schema representer's static definitions, where show_if never runs, so exports and the type form configuration listed labels with the flag off and printed the raw association with it on.

Nothing reads usage_count from ordered_by_relevance_for, and plain SQL strings read easier than the Arel expressions here.

The shared index endpoint already handles offset and pageSize; reorder lets the relevance ordering replace the query's default name order on merge.

New nested resources only get workspace-scoped path helpers; the projects route remains an undocumented alias.

brunopagno

Nice job. This looks really good 👍

Approving, as it can go through, but left a comment in case you want to think about naming shenanigans 😁

Cheers 🎉 🎉 🎉

brunopagno · 2026-09-30T07:29:08Z

+  scope :ordered_by_relevance_for, ->(project) {
+    used_in_project = Labeling
+                        .where(labelable_type: WorkPackage.name)
+                        .where("labelings.label_id = labels.id")
+                        .joins("INNER JOIN work_packages ON work_packages.id = labelings.labelable_id")
+                        .where(work_packages: { project_id: project })
+                        .arel
+                        .exists
+
+    reorder(used_in_project.desc)
+      .order(Arel.sql("#{USAGE_COUNT_SQL} DESC"))
+      .order("LOWER(labels.name) ASC")


Nice. This gives confidence. Thanks for making it.

brunopagno · 2026-09-30T07:38:26Z

+    select("labels.*, #{USAGE_COUNT_SQL} AS usage_count")
+  }
+
+  scope :ordered_by_relevance_for, ->(project) {


🟢 I am debating this with myself, but I feel there's something a bit off

relevance is ambiguous, it can mean anything and it does not explain what the sorting is doing

reading the code explains it, but it takes a minute to parse everything

the product solution is not really tested and might change in the future

For me either add an explanation comment...

# Sorts first by locality (labels already used in the current project come first) # then by frequency (most used first).

... or make the scope name overexplain itself

scope :ordered_by_locality_and_usage_for, -> (project) {

but if this changes in the future we need to change the method signature 👀

akabiru added this pull request to stack #25555 September 23, 2026 20:57

akabiru changed the title ~~implementation/comms 1046 labels schema and workspace listing~~ Implementation/COMMS-1046: Labels in the work package schema and labels-by-workspace API Sep 23, 2026

akabiru self-assigned this Sep 23, 2026

This was referenced Sep 23, 2026

Implementation/COMMS-1047: Label creation API with case-insensitive dedupe #25553

Open

Feature/COMMS-1004: Labels for work package show page #25551

Closed

akabiru added the ai: Collaborative 💻 AI generated a substantial part of the code; A human reviewed and understands every line. label Sep 23, 2026

akabiru added this to the 18.0.x milestone Sep 23, 2026

akabiru force-pushed the implementation/comms-1046-labels-schema-and-workspace-listing branch from 5e5d36c to 69115b2 Compare September 24, 2026 06:13

github-actions Bot removed the ai: Collaborative 💻 AI generated a substantial part of the code; A human reviewed and understands every line. label Sep 24, 2026

akabiru force-pushed the implementation/comms-1046-labels-schema-and-workspace-listing branch 2 times, most recently from af7e6a5 to 934a475 Compare September 24, 2026 13:39

akabiru added the ai: Collaborative 💻 AI generated a substantial part of the code; A human reviewed and understands every line. label Sep 24, 2026

github-actions Bot removed the ai: Collaborative 💻 AI generated a substantial part of the code; A human reviewed and understands every line. label Sep 24, 2026

akabiru added the ai: Collaborative 💻 AI generated a substantial part of the code; A human reviewed and understands every line. label Sep 24, 2026

github-actions Bot removed the ai: Collaborative 💻 AI generated a substantial part of the code; A human reviewed and understands every line. label Sep 24, 2026

akabiru marked this pull request as ready for review September 24, 2026 14:42

akabiru added the ai: Collaborative 💻 AI generated a substantial part of the code; A human reviewed and understands every line. label Sep 24, 2026

github-actions Bot removed the ai: Collaborative 💻 AI generated a substantial part of the code; A human reviewed and understands every line. label Sep 24, 2026

akabiru requested a review from a team September 24, 2026 14:43

akabiru commented Sep 24, 2026

View reviewed changes

akabiru added the ai: Collaborative 💻 AI generated a substantial part of the code; A human reviewed and understands every line. label Sep 24, 2026

akabiru added 8 commits September 29, 2026 13:01

Expose labels in the work package schema

e20f90b

Labels are global and unbounded, so allowed values are linked to a project-scoped endpoint rather than embedded. The flag joins the schema cache dependencies so toggling it does not serve stale schemas.

Add labels listing by workspace ordered by relevance

8812c49

The work package labels dropdown needs labels already used in the current workspace first, then the most used ones, so the schema points at this endpoint instead of the global listing.

Include labels in the work package cache checksum

ebcdc56

Assigning labels does not touch the work package row, so without this the cached JSON representation kept serving the previous labels.

Derive the labelable type in the checksum from the model

ab4d4e0

Simplify label relevance ordering

b6b5582

Nothing reads usage_count from ordered_by_relevance_for, and plain SQL strings read easier than the Arel expressions here.

Serve workspace labels through the standard index endpoint

8ab6517

The shared index endpoint already handles offset and pageSize; reorder lets the relevance ordering replace the query's default name order on merge.

Drop the project-scoped labels path helper

389bd60

New nested resources only get workspace-scoped path helpers; the projects route remains an undocumented alias.

akabiru force-pushed the implementation/comms-1046-labels-schema-and-workspace-listing branch from c1f84a6 to 389bd60 Compare September 29, 2026 10:01

brunopagno approved these changes Sep 30, 2026

View reviewed changes

Navigation Menu

Implementation/COMMS-1046: Labels in the work package schema and labels-by-workspace API - #25552

Implementation/COMMS-1046: Labels in the work package schema and labels-by-workspace API#25552
akabiru wants to merge 8 commits into
devfrom
implementation/comms-1046-labels-schema-and-workspace-listing

akabiru commented Sep 23, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Sep 24, 2026

Uh oh!

akabiru Sep 24, 2026

Uh oh!

brunopagno Sep 30, 2026

Uh oh!

brunopagno left a comment

Uh oh!

brunopagno Sep 30, 2026

Uh oh!

brunopagno Sep 30, 2026

Uh oh!

This branch has not been deployed

Reviewers

Assignees

Labels

Milestone

Development

Uh oh!

2 participants

Scenario (labels / labelings / WPs)	Unfiltered	Filtered	`total` count	Alphabetical baseline
Small (100 / 10k / 5k)	4.7 / 68.7	0.7 / 1.9	0.3	1.9
Medium (1k / 100k / 50k)	97.2 / 114.5	1.2 / 2.6	0.3	31.6
Large (10k / 1M / 500k)	627.5 / 841.8	5.0 / 5.9	0.6	274.2

Rewrite	Unfiltered	Filtered
`EXISTS` as a CTE	~623	not run
`usage_count` via one `GROUP BY`	~227	not run
Both combined	~90	~87

Conversation

akabiru commented Sep 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

AI involvement

Uh oh!

github-actions Bot commented Sep 24, 2026

Uh oh!

akabiru Sep 24, 2026

Choose a reason for hiding this comment

🤖 Benchmark: Label.ordered_by_relevance_for

Uh oh!

brunopagno Sep 30, 2026

Choose a reason for hiding this comment

Uh oh!

brunopagno left a comment

Choose a reason for hiding this comment

Uh oh!

brunopagno Sep 30, 2026

Choose a reason for hiding this comment

Uh oh!

brunopagno Sep 30, 2026

Choose a reason for hiding this comment

Uh oh!

This branch has not been deployed

Reviewers

Assignees

Labels

Milestone

Development

Uh oh!

2 participants

akabiru commented Sep 23, 2026 •

edited

Loading

🤖 Benchmark: `Label.ordered_by_relevance_for`