docs(factories): clarity sweep over the launch pages - #566
Merged
Conversation
Follow-up to #562. The page explained how mention routing is built before it said what to do with it, which put the reader through the architecture to answer "how do I hand this issue to my factory?" - "Mention the factory" opened on an internal fact ("a factory doesn't get its own GitHub handle") and asked the reader to expand `factory:<alias>` themselves, with `<alias>` defined mid-sentence via a link into the definition-syntax reference. It now leads with the two actions and a worked example (`factory:payments`), and explains the shared account only where it changes behavior: the label is what picks which factory answers. The Foreman name now links to Settings, where you read it, rather than to the YAML key. - The default automations were one dense paragraph; they are two bullets. - Dropped mechanism the reader can't act on: "both passes are best-effort", "CI payloads don't carry issue or label data", and "managed GitHub factories". - Replaced remaining internal vocabulary: "Warp-owned check" and "the registered factory directory". - GitLab carried the same `factory:<alias>` placeholder; same fix. Co-Authored-By: Warp <agent@warp.dev>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
Contributor
|
I'm starting a first review of this pull request. You can view the conversation on Warp. I completed the review and no human review was requested for this pull request. Comment Powered by Oz |
Collaborator
Author
|
This PR was generated with Warp. Comment   |
|
Your GitHub account is not connected to Warp. Connect it here. |
Contributor
|
Your Warp account is not a member of any team with access to this repository. |
![oz-for-oss[bot]](https://avatars.githubusercontent.com/in/3450139?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Overview
This PR rewrites the factories GitHub and GitLab integration docs to lead with reader actions and simplify mechanism-heavy explanations. Most changes are presentation-only, but one GitHub section now omits a condition that affects when factory-definition checks run.
Concerns
- The factory-definition check instructions now imply that any pull request touching definition files gets the
warp/factory-configcheck, while the troubleshooting guidance still says the pull request must target the branch the factory runs from. - No implementation spec context was provided, and the diff is documentation-only; the supplemental security pass found no security findings.
Verdict
Found: 0 critical, 1 important, 1 suggestions
Request changes
Comment /oz-review on this pull request to retrigger a review (up to 3 times on the same pull request).
Powered by Oz
| ## Factory-definition pull request checks | ||
|
|
||
| If the factory's [definition is managed as code](/factories/factory-as-code/) in a GitHub repository, Warp reviews configuration changes like CI reviews code. When a pull request targets the production branch and changes files in the registered factory directory, a **warp/factory-config** check runs: it passes with a summary of the change, or fails with diagnostics on what to fix. Require the check in branch protection to block invalid definitions from merging. | ||
| If the factory's [definition is managed as code](/factories/factory-as-code/) in a GitHub repository, Warp reviews changes to it the way CI reviews code. Open a pull request that touches the definition files and a **warp/factory-config** check runs: it passes with a summary of what the change does, or fails with the specific fields to fix. Require the check in branch protection to stop an invalid definition from merging. |
Contributor
There was a problem hiding this comment.
warp/factory-config; keep it aligned with the troubleshooting guidance that the pull request must target the branch the factory runs from.
Suggested change
| If the factory's [definition is managed as code](/factories/factory-as-code/) in a GitHub repository, Warp reviews changes to it the way CI reviews code. Open a pull request that touches the definition files and a **warp/factory-config** check runs: it passes with a summary of what the change does, or fails with the specific fields to fix. Require the check in branch protection to stop an invalid definition from merging. | |
| If the factory's [definition is managed as code](/factories/factory-as-code/) in a GitHub repository, Warp reviews changes to it the way CI reviews code. Open a pull request against the branch the factory runs from that touches the definition files, and a **warp/factory-config** check runs: it passes with a summary of what the change does, or fails with the specific fields to fix. Require the check in branch protection to stop an invalid definition from merging. |
Net -80 lines across the section, almost all of it interface narration and mechanism a reader can't act on. The pages were written as separate PRs, so each was reasonable alone and repetitive together. UI narration replaced with the task: - Slack's five-step connect was two actions (install the app, invite it to channels); two of the steps were the wizard describing itself. - GitLab's eight-step connect mixed factory creation, project selection, and hand-building an automation. - Linear had two near-identical connect procedures ending in "Both paths end in the same state." - Jira's step 3 was ~90 words and four actions. - Slack and Jira each walked through screens Warp doesn't own (Slack's app-removal flow, Atlassian's install flow); both now link out, so they can't drift silently. - The generic four-step "add an automation" walkthrough appeared on four integration pages. automation-filters owns it now; each integration page keeps only its own events and filters. Mechanism removed: Slack's managed-apps model and manager authorization, GitLab's manager service account, credential minting, one-year provisioning token and generated-ID naming, the per-run short-lived token, compute resolution precedence, and "this declares the `jira` integration for the factory." Said once instead of five to nine times: "filters route work, they don't restrict access" (now owned by automation-filters) and "the factory hands off at the pull request" (owned by how-factories-work). Also: - /platform/harnesses/ never mentioned that third-party harnesses need a Build plan, so a Free-plan reader found out at the error. Verified in warp-server/logic/agent_entitlements.go:114. - Dropped the `topic: factories` frontmatter key from ten pages. Every factories page is listed in sidebar.ts, so the key does nothing there and implied it was required. Co-Authored-By: Warp <agent@warp.dev>
hongyi-chen
changed the title
Co-authored-by: oz-for-oss[bot] <277970191+oz-for-oss[bot]@users.noreply.github.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Two commits into
hyc/factory-launch: the GitHub page fix from your review, then a clarity sweep across the rest of the section. Net −80 lines infactories/, almost all of it interface narration and mechanism a reader can't act on.1. GitHub page: lead with what the reader does (follow-up to #562)
"Mention the factory" explained how routing is built before saying what to do with it:
Three things to get past before acting: an internal fact about handles, a placeholder to expand yourself, and a definition of that placeholder linking into the YAML reference. Now it's the two actions with a worked example (
factory:payments), and the shared-account fact appears below, framed as why the label matters. Foreman name links to Settings, where you read it.2. Clarity sweep across the section
Interface narration → the task. Slack's five-step connect was really two actions, and two of the steps were the wizard describing itself ("confirm that Slack shows Connected"). GitLab's eight-step connect mixed factory creation, project selection, and hand-building an automation. Linear had two near-identical connect procedures ending in "Both paths end in the same state." Jira's step 3 ran ~90 words across four actions.
Screens we don't own. Slack's app-removal flow and Atlassian's install flow were both walked through step by step. They now link to those vendors' docs, so they can't drift silently when either reskins.
One automation walkthrough, not five. The generic "open Automations → Add trigger → pick an event → Save" sequence appeared on four integration pages.
automation-filtersowns it; each integration page keeps only its own events and filters.Mechanism removed — Slack's managed-apps model and manager authorization; GitLab's manager service account, credential minting, one-year provisioning token, and generated-ID naming scheme; the per-run short-lived token; compute resolution precedence; "this declares the
jiraintegration for the factory."Said once instead of five to nine times — "filters route work, they don't restrict access" now lives on
automation-filters; "the factory hands off at the pull request" lives onhow-factories-work. Everywhere else points at them.Two fixes outside the sweep
/platform/harnesses/never mentioned plan gating. Third-party harnesses need a Build plan — stated on the factory agents page and enforced inwarp-server/logic/agent_entitlements.go:114— but absent from the page that exists to explain harnesses, so a Free-plan reader found out at the error.topic: factoriesfrom ten pages. Every factories page is listed insidebar.ts, and the key only does something for pages that aren't, so it was a no-op that implied it was required.What I deliberately didn't do
factories/. 377 pages isn't a reviewable diff and most of it isn't part of this launch. Happy to line that up separately.factory-as-code.mdxleft alone apart from redundancy — it's a syntax reference, where implementation detail is the point.Validation
npm run buildclean · 0 broken internal links · 0 anchor problems infactories/(several section headings moved, so this mattered) ·factory-proper-noun,platform-determiner,hardcoded-var, andfrontmatterall 0 · both lint suites pass (21 + 11 cases) · every changed page re-read top to bottom rather than reviewed as a diff, since this pass is about how they read.