Documentation
¶
Overview ¶
Package devstatus enriches an already-fetched Jira issue with all the development metadata Jira's Dev Status API surfaces: pull requests, branches, commits, repositories, and builds.
Why this package exists ¶
The standard GET /rest/api/3/issue/{key} response carries a development-summary field (customfield_10000) that reports per- dataType counts of associated entities, but not the underlying URLs or details. The actual entity lists live behind an undocumented endpoint:
GET /rest/dev-status/1.0/issue/detail
?issueId=<NUMERIC>&applicationType=<APP>&dataType=<DT>
Atlassian's own Jira UI consumes this endpoint to populate the per- issue Development panel, and the response shape has been stable for over a decade. gojira treats it as best-effort enrichment that can be opted out cleanly via config.Config.IncludeDevStatus.
Architectural placement ¶
devstatus is a small leaf package that depends only on stdlib, errext, client (for HTTP transport and the Dev Status response types), config (for the IncludeDevStatus / DevStatusApplications / DevStatusDataTypes flags), and parse (for the parse.Issue type and the canonical parse.DevStatusData result type). It deliberately does NOT import crawl, render, output, events, fetch, extract, adf, or classify: those would create cycles or layering regressions.
The crawl orchestrator constructs a single *Enricher at startup and shares it across all worker goroutines, mirroring the pattern used by internal/hierarchy.
No smart gate: always query every configured dataType ¶
Earlier revisions of this package parsed the customfield_10000 summary blob and asked a "smart gate" which dataTypes to query, skipping the ones the summary reported as zero-count. That optimisation produced two silent-miss bugs in three commits (PROJ-1578 in particular: the summary said repository.count=1 and zero for every other dataType, but the Jira UI showed a PR, branches, commits, and builds — all of which the gate silently dropped, regardless of the summary's own "isStale":true flag).
The current contract is: when IncludeDevStatus=true, every configured (application, dataType) pair is queried. The customfield_10000 summary is no longer parsed. The cost is at most five extra HTTP calls per issue; the benefit is that "no data reached me" can no longer be silently caused by a stale summary cache.
Failure isolation ¶
One Dev Status request is issued per (application, dataType) pair. Per-call errors are accumulated rather than surfaced immediately: if at least one call returns results, those results are returned alongside a non-fatal joined error the caller can log as a partial-failure warning. Only when every call failed AND no entities were collected does Enricher.Enrich return a fatal error.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var CanonicalDataTypes = []string{
"pullrequest",
"branch",
"commit",
"repository",
"build",
}
CanonicalDataTypes is the canonical order of the five Dev Status dataType values gojira understands. It is used to order the configured DataTypes deterministically for per-issue fan-out (so per-call error messages and the order in which entities are merged are stable across runs). It mirrors the typical top-down order in which the Jira UI Development panel groups them.
Functions ¶
This section is empty.
Types ¶
type Enricher ¶
type Enricher struct {
// contains filtered or unexported fields
}
Enricher queries the Jira Dev Status API for development metadata associated with an issue.
Construct via New. A single *Enricher is intended to be shared across all crawl workers; the underlying *client.Client already holds the connection pool and auth state.
func New ¶
New constructs an Enricher backed by the given client and config. A nil client is treated as a programming error and will produce a fatal error on the first call to Enricher.Enrich; the crawl orchestrator always supplies a non-nil client.
func (*Enricher) Enrich ¶
Enrich returns the populated parse.DevStatusData for issue, fanning out one Dev Status request per (configured application, configured dataType) pair and merging the results.
The following cases short-circuit with the zero value and no error, without issuing any HTTP requests:
- cfg.IncludeDevStatus is false.
- issue.NumericID is empty (no opaque ID to query against).
- cfg.DevStatusApplications is empty.
- cfg.DevStatusDataTypes is empty (filtering to the canonical set also yields empty).
Otherwise every (application, dataType) cross-product is queried. Per-call errors are joined and returned alongside any partial results; only when no results are collected AND every call failed is the error wrapped as a fatal-style error the crawl orchestrator can use to distinguish "this issue's enrichment found nothing because the summary really had nothing" from "every upstream request failed and we have no data".
The returned lists are deduplicated per entity type (PRs/branches/ repos/builds by URL; commits by full SHA) and sorted by their canonical key for determinism.
Source Files