Discussion #80: developer guides, sidebar, and the pages this made stale
New:
Email-Template-Sender-Rules-Developer-Guide
Email-Signatures-Developer-Guide
Updated because the change made them wrong, not merely incomplete:
Email-Send-Log - Result is now Sent / Failed / Not sent
Canned-Responses - [ticket_url] joins the merge code table
Tickets - sender rules and [ticket_url] on email templates
External-Issue-Trackers-Developer-Guide,
Azure-DevOps-Connector-Developer-Guide
- integrationsAbsoluteUrl now delegates to
publicAbsoluteUrl, plus the subfolder fault it had
_Sidebar - all five pages, nested under Tickets
Every internal link in the changed pages checked against a real file.
Issue trackers: Azure DevOps connector, and the contract test it settled (#964-966)
New page: Azure-DevOps-Connector-Developer-Guide, the sibling of the Jira
one. Issue-Trackers gains Azure DevOps setup and the Resolved setting;
the two guides that PREDICTED this work now record how it turned out.
The engine guide committed to a falsifiable claim before Jira shipped:
adding connector #2 must touch nothing but the provider, one registry
row and its settings partial. It held, and the page now says so with the
three things that did change for everyone:
- settings_fields, and why it is separate from credential_fields — a
dropdown among the credential boxes inherits their blanking rule and
silently resets on every save;
- integrationsAbsoluteUrl(), because the ticket link every connector
puts in an issue was built from BASE_URL, which is a path, so it 404'd
from inside any tracker and had never worked;
- $target may be keyed either way — core's neutral `issue_type` or the
provider's own word — because reading only one silently creates the
wrong kind of work item.
The Jira guide's "if you are writing the next connector" list is now
marked as validated, with two of its decisions reclassified as Jira-ONLY
now there is something to compare against:
- relative JQL dates exist because Jira reads an absolute date in the
USER's timezone. Azure DevOps honours an explicit UTC Z. Copying
either across is a bug, and both are right for their own tracker;
- flavour-dependent author_identity is an Atlassian quirk, not a general
requirement. What IS general is that it match testConnection().
What the new page records that the code cannot say for itself:
- ⚠️ which field holds the body depends on the work item TYPE. A Bug's
form shows Repro Steps and not System.Description, so writing the
description to the obvious field returns 200 and produces a work item
that looks empty to the developer who opens it;
- 🔑 five state categories, not four, and why the fifth is a per-connection
SETTING rather than a mapping — plus the live vindication of "never
branch on a status name": "Resolved" is category Resolved on a Bug and
InProgress on a User Story, same project;
- ⚠️ timePrecision=true is a query parameter, not a body field, and the
tempting fix for the error it throws silently re-reads a day of comments;
- ⚠️ echo suppression must use createdBy.id — the two endpoints report
DIFFERENT descriptor formats for the same person, so comparing those
never matches and every comment we write comes back as a developer's;
- ⚠️ attachments are two steps and step one attaches the file to nothing;
- ⚠️ a rejected token answers 203 with a sign-in page, not 401 with JSON.
Also corrected two stale rows in the analyst page's "not there yet"
table: attachments and "tell the requester when it is done" both shipped
weeks ago and were still listed as missing.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>