Repository navigation
Tighten comments in the software development tools webhook examples - #325
Merged
Merged
Conversation
Rewrite module docstrings, task docstrings, and inline comments in the GitHub, Slack, Jira, Linear, and ClickUp webhook examples to match the docs' reference style: state what the code does and what the reader needs to know, without design rationale or bug history. Also fixes two inaccurate comments: - slack_tasks.py: the approval handler, not approval.request, replaces the buttons after a click. - slack_webhooks.py: on_deploy_command doesn't launch a run. Comments, docstrings, and assert messages only; the code is unchanged (verified by AST comparison). docs-fragment markers are untouched. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Signed-off-by: Peeter Piegaze <1153481+ppiegaze@users.noreply.github.com>
ppiegaze
added a commit
to unionai/unionai-docs
that referenced
this pull request
Oct 5, 2026
Pick up unionai/unionai-examples#325, which tightens the comments in the software development tools webhook examples embedded on these pages. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Signed-off-by: Peeter Piegaze <1153481+ppiegaze@users.noreply.github.com>
ppiegaze
added a commit
to unionai/unionai-docs
that referenced
this pull request
Oct 5, 2026
…1673) * docs(api-reference): add the five SaaS webhook provider plugins Registers flyteplugins-{github,slack,jira,clickup,linear} in api-packages.toml and commits their generated API reference. The five are a family, not five unrelated plugins: each contributes one `Provider` to the receiver in `flyte.extras.webhooks`, which ships with flyte and is already documented with the SDK. So they are grouped under a nested output_folder the way the agents adapters are, sharing one explanatory landing page, rather than flattened into five siblings at the top of the integrations base. `name` stays flat (saas-<product>) because it names the linkmap file, which lives in a single flat directory; page URLs follow output_folder. No `extras` on any entry: github's `review_pr` and `mint_installation_token` import PyGithub and PyJWT lazily, so the parser imports the package without the [review] and [auth] extras installed. Signed-off-by: Niels Bantilan <niels.bantilan@gmail.com> * docs(integrations): add the SaaS integrations guide for five products A section rather than five flat pages, following the agents/ precedent: the five providers share one model -- the normalized event, run_once, the scope allowlist, the dashboard -- and documenting that five times would be both repetitive and the thing most likely to drift. `_index.md` carries the shared half, including the parts that are only learnable the hard way: - events with no scope are acknowledged but never dispatched, which presents as "my webhook is not firing"; - two simultaneous deliveries of one event can both launch, because the label check is a read followed by a launch; - handlers must await run_once.aio, since the blocking form stalls the event loop and GitHub times out in ten seconds. Per-product pages carry the setup steps, the full event-constant tables, and each product's quirks: GitHub's two content types normalizing identically, Slack's three delivery shapes on one route and its two non-interchangeable credentials, Linear's nested team id, ClickUp's single-string event names, Jira's lack of signing. The Jira page states plainly what the shared-token substitution does not give you, and says not to reach for require_signature=False to make deliveries flow. Nothing else in the docs would tell a reader that before they shipped it. Also adds a "Not to be confused with" section: FlyteWebhookAppEnvironment exposes Flyte's own operations outbound, WebhookAppEnvironment receives inbound. Similar names, opposite directions. Code is embedded from the examples added in unionai-examples #319-323, so the published snippets are the tested source. HMAC goes in the shared cspell dictionary; it is RFC 2104, not a coinage. Signed-off-by: Niels Bantilan <niels.bantilan@gmail.com> * chore: bump unionai-examples to pick up the SaaS webhook examples Deliberate pointer bump, not a side effect: this is what makes the `{{< code >}}` references on the new SaaS integration and lifecycle pages resolve, so it belongs with them rather than in a later sweep. fee0dae..7b76784, which merges unionai-examples #319-323 — the GitHub, Slack, Jira, ClickUp, and Linear webhook examples. Verified against the merged tree rather than assumed: all 24 code references from these pages resolve to a real file and a real fragment marker on examples origin/main, both Hugo variants build, check-links passes, and no page renders a "File not found" or "Fragment not found" banner. Built with `make variant` rather than `make dist` on purpose — dist runs update-api-docs, which regenerates the whole SDK reference and leaves ~380 unrelated modified files in the tree. Signed-off-by: Niels Bantilan <niels.bantilan@gmail.com> * docs: correct the ClickUp and Linear signature headers for 2.10.7 flyte-sdk #1645 fixed both providers: ClickUp signs with `X-Signature`, not `X-Clickup-Signature`, and Linear with `Linear-Signature`, not `X-Linear-Signature`. Before 2.10.7 `verify` looked for headers no real delivery carries, so with the default `require_signature=True` both integrations returned 401 to every genuine webhook. Two kinds of change here. Regenerated all five API references at 2.10.7. The only substantive diff is the two corrected `verify` docstrings; the rest is the version stamp. All five move together so the advisory freshness check stays clean -- confirmed committed=2.10.7 latest=2.10.7 for each. Corrected the header by hand in the four places prose names it: both landing tables, plus the ClickUp and Linear pages. On those two pages the fix is not a find-and-replace. Each now says why the right name looks wrong, because a reader who distrusts it will "fix" it back and lose every delivery: ClickUp's is `X-Signature` and not the `X-Clickup-Signature` it looks like it should be; Linear's has no `X-` prefix at all. The issue raised was about ClickUp, but #1645 fixed Linear identically and its own PR body flags that these docs needed the same correction. Both are done rather than leaving Linear quietly wrong. GitHub, Slack, and Jira prose is untouched and was already right: `X-Hub-Signature-256`, `X-Slack-Signature`, and Jira's `X-Webhook-Token` shared-token stand-in. Built with `make variant`, not `make dist`, so the tree carries no regenerated-SDK noise. Submodule pointers untouched -- the matching examples update is unionai-examples #324, which this PR does not depend on. Signed-off-by: Niels Bantilan <niels.bantilan@gmail.com> * Bump examples to 17d01d5, and fix a claim the header bug disproved Deliberate pointer bump, 7b76784..17d01d5, picking up unionai-examples #324: the ClickUp and Linear examples now pin 2.10.7 and their replay tasks assert the signature header a real delivery carries. The embedded `replay` fragments on those two pages pick that up. The more important change is prose. The landing page claimed `SAMPLE_DELIVERY` is "how `verify` and `parse` are checked against something the product actually sent rather than against each other." The ClickUp and Linear bug disproves that as written, and it is the exact misconception that let the bug ship, so leaving it would be worse than the original omission. What is true: the *body* is real, so field extraction is checked against reality. The *headers* are fabricated by the plugin, so for anything whose name the plugin chooses -- the signature header above all -- the sample agrees with `verify` whatever that name is. Both providers shipped reading a header no real delivery carries, with conformance green and every genuine webhook getting a 401. The page now says that. Each product page gets a note on why its replay asserts the header *name*: it is the one check a round trip cannot make, and worth copying for any provider a reader adds. Verified after the bump: all 24 code references resolve against the new tip, both variants build, every check passes, and no page renders a not-found banner. Known and deliberately not fixed here: the same overstatement survives in one docstring line in the merged github_tasks.py example, which this page renders. It is imprecise rather than false -- GitHub's header was always correct -- and not worth a third examples PR plus another pointer bump on its own. Signed-off-by: Niels Bantilan <niels.bantilan@gmail.com> * docs: rename to SDLC integrations, and pin it below Agent frameworks Renames the section from "SaaS integrations" to "SDLC integrations" and moves it directly below Agent frameworks in both nav trees. The rename goes all the way down rather than stopping at the title, so nothing is left reading as a leftover: the URL (`integrations/sdlc-integrations/`), the api-reference path, the registry `name`/`output_folder` keys, and the five linkmap files. No redirects are owed -- the old path never reached main, which `detect_moved_pages` and `check-deleted-pages` both confirm rather than my assuming it. Framing follows the name. The section intro now says these let something that happened in "one of your team's own tools" start a run, rather than "another product", which pairs it with the Software development lifecycle user guide. "SaaS" survives in the two places it is still the precise word: that these receive calls *from* SaaS products, and upstream's own `examples/external_saas_integrations` in the generated docstrings, which is not ours to edit. Two separate ordering defects, both now fixed: - The category list had this at item 11, at the end, while its prose section sat third. Moved to item 3, right after Agentic AI, and renumbered. The list and the section order now agree. - The sidebar was the real problem. Every other integration carries `weight: 1`, so a `weight: 2` sorted this section *last*, not second. The existing convention is "agents pinned first, everything else alphabetical"; this extends it to a two-item pinned group -- agents 1, sdlc-integrations 2, the other 21 bumped to 3. That is the 21-file diff here, and it preserves their relative (alphabetical) order exactly. The api-reference side needed no weight changes: generated plugin pages carry no weight at all, so they already sorted after the two weighted entries. Verified in the built HTML rather than inferred from frontmatter: both nav trees render Agent frameworks then SDLC integrations. Also zero `saas-integrations` references left anywhere tracked, no stale output under the old path, and no code-shortcode error banners site-wide. Signed-off-by: Niels Bantilan <niels.bantilan@gmail.com> * docs: rename the integrations section to Software development lifecycle Spells the section out, matching the user-guide section of the same name, so the two read as one story rather than one acronym and one phrase. Carried all the way down again -- URL (`integrations/software-development-lifecycle/`), api-reference path, and the regenerated linkmaps, which held the old URLs and would otherwise have pointed the inline-code linker at 404s. No redirects owed: the old path never reached main, confirmed by detect_moved_pages and check-deleted-pages rather than assumed. Two deliberate exceptions to spelling it out: The registry `name` keys stay `sdlc-<product>`. `name` is the linkmap filename and appears in no URL, so spelling the section out would give every linkmap a 40-character prefix for no reader-visible gain. The comment block now says so, since the next person to read it will otherwise wonder why it disagrees with output_folder. Prose that referred to the section by name now says "These integrations" rather than repeating the full phrase immediately under a heading that already says it. Verified in the built HTML in both variants, both nav trees: Agent frameworks -> Software development lifecycle. No stale output under either previous path, no code-shortcode error banners, and every check passes. Signed-off-by: Niels Bantilan <niels.bantilan@gmail.com> * docs: rename the integrations section to Software development tools Gives the integrations section its own name, so it no longer collides with the Software development lifecycle user guide. The pairing stays legible -- tools on one side, the lifecycle they serve on the other -- without two nav entries, two breadcrumbs, and two search results reading identically. Renamed through the URL (`integrations/software-development-tools/`), the api-reference path, and the linkmaps, which still held the previous URLs and would otherwise have pointed the inline-code linker at 404s. Still no redirects owed: no earlier path ever reached main, confirmed by detect_moved_pages and check-deleted-pages. Registry `name` keys move sdlc-<product> -> devtools-<product>. They stay abbreviated for the reason the comment already gives -- `name` is the linkmap filename and appears in no URL -- but `sdlc` would now name something this section is not. Fixed two sentences while here. "This is the richest of the [Software development lifecycle]" and "Slack is the broadest of the [Software development lifecycle] in both directions" were left as broken noun phrases by an earlier rename, which swapped a plural category name into a slot that needed one. Both now read "of these integrations", which does not break again on the next rename. Dropped the disambiguating wording added when the two sections shared a name: links from here to the user guide are plain again. Verified in the built HTML, both variants, both nav trees: Agent frameworks -> Software development tools. No stale output under any previous path, no code-shortcode error banners, and every check passes. Signed-off-by: Niels Bantilan <niels.bantilan@gmail.com> * docs(integrations): style pass on the Software development tools pages Rewrite the landing page and the five product pages for task-first reference style: - Lead with a quick start; move the API-wrapper rationale to a short "Calling the product's API" section. - State version requirements (ClickUp, Linear: 2.10.7+) instead of recounting the signature-header bug. - Drop editorial asides and sentence-length notice titles; state gotchas plainly. - Fix the Jira sentence missing its `require_signature=True` reference. - Correct the no-scope claim: events without a scope are skipped only when a `scopes` allowlist is set (flyte/extras/webhooks/_app.py). - Tighten the API-reference group landing page and the integrations index summary to match. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Signed-off-by: Peeter Piegaze <1153481+ppiegaze@users.noreply.github.com> * chore: bump unionai-examples to b663d54 Pick up unionai/unionai-examples#325, which tightens the comments in the software development tools webhook examples embedded on these pages. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Signed-off-by: Peeter Piegaze <1153481+ppiegaze@users.noreply.github.com> --------- Signed-off-by: Niels Bantilan <niels.bantilan@gmail.com> Signed-off-by: Peeter Piegaze <1153481+ppiegaze@users.noreply.github.com> Co-authored-by: Peeter Piegaze <1153481+ppiegaze@users.noreply.github.com> Co-authored-by: Claude Opus 5.5 (1M context) <noreply@anthropic.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
1 participant
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.
Style pass on the comments in
v2/integrations/flyte-plugins/{github,slack,jira,linear,clickup}/. These files are embedded in the Software development tools integration pages (unionai/unionai-docs#1673), so their comments render in the docs.slack_tasks.py, the handler added byapproval.registerreplaces the buttons, notapproval.request; inslack_webhooks.py,on_deploy_commanddoesn't launch a run.Comments, docstrings, and assert messages only. The code is unchanged in all ten files (checked by comparing ASTs with docstrings and assert messages stripped), and every
docs-fragmentmarker is untouched.After this merges, unionai/unionai-docs#1673 bumps the
unionai-examplespointer to pick it up.🤖 Generated with Claude Code