docs(flaky-tests): make collections the default in the straggler copy by TylerJang27 · Pull Request #324 · trunk-io/docs2

TylerJang27 · 2026-09-09T18:18:43Z

Important

Do not land until the default test_collection_status enum is flipped. Every page here is already live, so merging earlier would present collections as the default to organizations for which they are not.

Overview

PR 3 of the Test Collections docs stack: the eight already-live pages that assumed a repository, and now either lead with collections or say plainly that they don't apply.

Details

Stacked on #323 → #322. Review those first.

Page	Change
`management/ticketing/automatic-ticketing`	Reframed: org-level integrations, selected and configured per collection
`quarantining/index`	The rule that decides which settings apply to an upload
`webhooks/index`	New collection-events section
`management/github-pull-request-comments`	Repository-only, with a pointer to the browser extension
`get-started/multiple-repositories`	Leads with a collection / repository / variant table
`management/managing-detected-flaky-tests`	The workflow is scope-agnostic; collections add a repository filter
`get-started/index`	Forks its two verify destinations
`overview`	Names collections in the opening; carries the support catch-all

Considerations

Ticketing is the real content change, not a path change. Integrations move from per-repository to connected once for the organization and then selected per collection, with automation configured per collection — so two collections can share one Jira project and behave differently. Written collections-first with a short repository section, since every setting behaves identically and only the location differs. Paths verified against settings-navigation.tsx: Settings → Organization → Ticketing.
Quarantining is deliberately brief. One rule carries it: if quarantining is enabled on the collection an upload was routed to, that collection's quarantining and flaky state are used; otherwise the repository's. Plus the ordering consequence — overrides can only be created after quarantining is on, because the control is disabled until then, so they are never staged in advance. Also removed a callout that restated the table directly above it.
The webhooks section leads with what consumers get wrong, not with payload shapes: test_collection is the only discriminator, and test_case.id cannot be deduplicated across scopes because the two don't share an ID space. The existing payload tables now sit under an ## Event payloads heading so the conceptual material comes first.
PR comments say outright that they are repository-only. A migrated organization would otherwise discover this by noticing the comments stopped. Points at the browser extension.
The support catch-all is on two pages only — this PR adds it to overview, and docs(flaky-tests): add the test collections concept and migration pages #322 has it on the migration guide. Everything else closes without it, per earlier review.
Two pre-existing back-to-back callouts (automatic-ticketing.mdx, webhooks/index.mdx) are left alone — confirmed they pre-date the stack, so fixing them here would widen the diff for something unrelated. Flagging it so a reviewer running the same check knows.
The API reference is split out into its own PR rather than riding here. It needs a generated spec artifact and nav wiring rather than prose, and can land on its own timeline.

Testing

Every internal link in the diff resolved against the file tree, including the cross-PR anchor from the webhooks page into docs(flaky-tests): add the test collections concept and migration pages #322's migration guide (#webhooks-while-you-migrate) and the merge-queue/browser-extensions target.
Callout types checked against CONTRIBUTING.md's decision rule; UI paths checked against the app's settings navigation rather than written from memory.
Not previewed with mint dev. Worth doing across the whole stack before anything leaves draft.

Follow-up Work

PR 4: dashboard.mdx, replaced for the collections state.
PR 5: the API reference restructured by scope, plus publishing the v2 spec.
PR 6: the flip — unhide docs(flaky-tests): add the test collections concept and migration pages #322's pages and add the nav entries.

References

docs(flaky-tests): add the test collections concept and migration pages #322, docs(flaky-tests): add the collection id to every setup instruction #323 — the rest of the stack
trunk-io/trunk2#5830 — the CLI flag these pages document

🤖 Generated with Claude Code

TylerJang27 · 2026-09-09T18:24:06Z

 1. Push your changes and trigger a CI run
 2. Check CI logs for successful upload confirmation
-3. Results typically appear within a few minutes. Verify uploads appear at [app.trunk.io](https://app.trunk.io) → your repo → **Flaky Tests** → **Uploads**
+3. Results typically appear within a few minutes. Verify uploads appear at [app.trunk.io](https://app.trunk.io) — on the collection's **Uploads** tab if you uploaded to a [test collection](./test-collections), or your repo → **Flaky Tests** → **Uploads** otherwise


We should assume collection is the default at that point, so this addition is unnecessary

TylerJang27 · 2026-09-09T18:24:14Z

 ### Step 4: Configure flake detection

-After uploads are flowing, navigate to your repo → **Flaky Tests** → **Monitors** to set up detection.
+After uploads are flowing, open the **Monitors** tab — on your [test collection](./test-collections), or on your repo under **Flaky Tests** — to set up detection.


TylerJang27 · 2026-09-09T18:24:45Z

+| Grouping | Use it to | Set by |
+|---|---|---|
+| [Test collection](./test-collections) | Group tests you want to configure and review together — by team, service, or suite — with their own monitors, quarantining, and ticketing. | `--test-collection-id` |
+| Repository | Nothing you choose. Detected from the git remote, and keeps test data separate between repositories and forks automatically. | Detected; `--repo-url` overrides |


Suggested change

| Repository | Nothing you choose. Detected from the git remote, and keeps test data separate between repositories and forks automatically. | Detected; `--repo-url` overrides |

| Repository | Detected automatically from the git remote, and keeps test data separate between repositories and forks automatically. | Detected; `--repo-url` overrides |

TylerJang27 · 2026-09-09T18:27:15Z

+Connect an integration once for your organization, then choose it on each [test collection](/flaky-tests/get-started/test-collections) that should file tickets.
+
+1. In the Trunk app, navigate to **Settings** → **Organization** → **Ticketing** and connect your Linear, Jira, or Asana integration. An organization can hold several — one Jira project for one team, another for a second.
+2. Open the collection's **Settings** tab, then **Ticketing**, and select which of those integrations the collection files into.


Suggested change

2. Open the collection's **Settings** tab, then **Ticketing**, and select which of those integrations the collection files into.

2. Open the collection's **Settings** tab, then **Ticketing**, and select which of those integrations the collection files into by default.

This setting only applies the default for auto-creation and the default when creating a ticket manually in the app. Include a piece under the "Automation is configured per collection" section to note that tickets can be created manually under any configured integration for the organization.

Fixed, and added the piece you asked for. Step 2 now says the collection files into that integration by default, and a paragraph under the per-collection note spells out what the default does and does not do: it decides where automatic tickets are filed and which integration the create-ticket modal opens on, but a manual ticket can be filed into any integration connected to the organization.

TylerJang27 · 2026-09-09T18:27:45Z


+## Repositories
+
+Repository-level ticketing works the same way, with the integration configured on the repository rather than the organization: navigate to **Settings** → **Repositories** → **[your repository]** → **Ticketing**. Every setting described above behaves identically; only where you configure it differs.


The other difference is that a repository can only have one ticketing integration and cannot use other integrations. Migrate to collections for greater flexibility.

Added — and it's a better framing than what I had, because it's a capability difference rather than a location one. The repository section now says a repository has exactly one ticketing integration and cannot file into any other, then names what collections give you instead: a choice from every integration connected to the organization, plus manual filing into any of them. Links to the migration guide from there.

Eight pages that assumed a repository and now need to lead with collections, or say plainly that they don't apply. The ticketing page is the real content change: integrations are no longer configured per repository but connected once for the organization and then selected per collection, with automation configured per collection. That means two collections can share one Jira project and still behave differently. The repository flow keeps a short section of its own, since every setting behaves identically and only the location differs. Quarantining leads with the rule that decides which settings apply to a given upload — the collection's if quarantining is enabled there, otherwise the repository's — and records that overrides can only be created after quarantining is on, never staged before it. The redundant callout restating the table above it is gone. Webhooks gain a collection-events section covering the three things a consumer needs: the `test_collection` object is the only discriminator, `test_case.id` cannot be deduplicated across scopes, and events are off until switched on from the organization's webhooks settings. Pull request comments say outright that they are repository-only and point at the browser extension, which is better than a migrated organization discovering it. The rest is lighter: `multiple-repositories.mdx` leads with a collection/repository/variant table, `managing-detected-flaky-tests.mdx` notes the workflow is scope-agnostic and that a collection's Tests tab adds a repository filter, `get-started/index.mdx` forks its two verify destinations, and the product overview names collections in its opening and carries the support catch-all. Two back-to-back callouts in these files pre-date the stack and are left alone. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Collections are the default by the time these pages ship, so the getting-started verify and monitors steps name the collection directly rather than forking between the two scopes. Two corrections on ticketing, both about what the collection's integration actually is. It sets the **default** — where automatic tickets are filed, and which integration the create-ticket modal opens on — and a manual ticket can still be filed into any integration connected to the organization. And the difference from repository-level ticketing is not only where it is configured: a repository has exactly one integration and cannot file into any other, which is the concrete thing migrating buys. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

TylerJang27 commented Sep 9, 2026

View reviewed changes

TylerJang27 mentioned this pull request Sep 9, 2026

docs(flaky-tests): replace the dashboard's landing page for collections #325

Draft

TylerJang27 and others added 2 commits September 9, 2026 18:40

TylerJang27 force-pushed the test-collections/straggler-copy branch from 0a8f58a to 9f9b791 Compare September 9, 2026 18:41

TylerJang27 added this pull request to stack #327 September 9, 2026 18:45

This was referenced Sep 9, 2026

docs(flaky-tests): publish the v2 API and split the reference by scope #329

Draft

docs(flaky-tests): publish the test collections pages #330

Draft

Navigation Menu

Uh oh!

docs(flaky-tests): make collections the default in the straggler copy - #324

docs(flaky-tests): make collections the default in the straggler copy#324
TylerJang27 wants to merge 2 commits into
test-collections/setup-instructionsfrom
test-collections/straggler-copy

TylerJang27 commented Sep 9, 2026

Uh oh!

TylerJang27 Sep 9, 2026

Uh oh!

TylerJang27 Sep 9, 2026

Uh oh!

TylerJang27 Sep 9, 2026

Uh oh!

TylerJang27 Sep 9, 2026

Uh oh!

TylerJang27 Sep 9, 2026

Uh oh!

TylerJang27 Sep 9, 2026

Uh oh!

TylerJang27 Sep 9, 2026

Uh oh!

TylerJang27 Sep 9, 2026

Uh oh!

TylerJang27 Sep 9, 2026

Uh oh!

TylerJang27 Sep 9, 2026

Uh oh!

Reviewers

Assignees

Labels

Milestone

Development

Uh oh!

1 participant

	\| Repository \| Nothing you choose. Detected from the git remote, and keeps test data separate between repositories and forks automatically. \| Detected; `--repo-url` overrides \|
	\| Repository \| Detected automatically from the git remote, and keeps test data separate between repositories and forks automatically. \| Detected; `--repo-url` overrides \|

	2. Open the collection's Settings tab, then Ticketing, and select which of those integrations the collection files into.
	2. Open the collection's Settings tab, then Ticketing, and select which of those integrations the collection files into by default.


		## Repositories

		Repository-level ticketing works the same way, with the integration configured on the repository rather than the organization: navigate to Settings → Repositories → [your repository] → Ticketing. Every setting described above behaves identically; only where you configure it differs.

Uh oh!

Conversation

TylerJang27 commented Sep 9, 2026

Overview

Considerations

Testing

Follow-up Work

References

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Milestone

Development

Uh oh!

1 participant