---
name: sdp-jira-jobs
description: File or update SDP issues in JIRA (project SDP, perforce.atlassian.net) -- summary/description conventions, fixVersion naming, and the P4Blog/Resolution-field gotchas. Use whenever filing a new SDP bug/story, or closing one out.
---

# SDP JIRA Jobs

## They're JIRA issues, not P4 jobs

`SDP-<N>` looks like it could be a native Perforce job, and historically it was -- but SDP
issue tracking moved to JIRA at some point, carrying the naming convention over unchanged.
`p4 job -o SDP-<N>` and `workshop.perforce.com/jobs/SDP-<N>` are both stale/non-functional
for anything current; use the JIRA connector (Atlassian Rovo MCP tools), not `p4 job`.
Contrast with `BSW-<N>`, which really is a native P4 job on the PPN server -- see the
**bsw-ppn-jobs** skill for that separate system. Don't confuse the two.

- Cloud ID: `2accdbdb-9d65-4c22-b174-5d4a9d437c59` (`perforce.atlassian.net`)
- Project key: `SDP`
- Common issue types used: `Bug`, `Story`

## Summary/Description convention (established 2026-09-09)

**For every new SDP JIRA issue filed, duplicate the Summary as the literal first line of
the Description field, followed by a blank line, then the full explanation.** Target the
Summary at roughly 70 characters max -- not an absolute hard limit; a few extra characters
are fine if they meaningfully help clarity, but keep it tight.

```
summary: "install_sdp.sh: 'neovim' fails to install on stock Rocky/RHEL 9"

description:
install_sdp.sh: 'neovim' fails to install on stock Rocky/RHEL 9

Found during the 2026.1 GA release's Step 22 post-release smoke test...
[rest of the full explanation]
```

**Why**: in anticipation of a possible future JIRA -> P4 Jobs integration. If/when that
gets built, it will likely rely on the Description's first line matching the Summary
verbatim -- mirroring how a native P4 job's own `Description` field already works (the
first line doubles as the job's title in `p4 jobs` listings; see **bsw-ppn-jobs**'s
jobspec for the exact precedent this is modeled on). Keeping SDP JIRA issues in this shape
now means that future integration won't need a backfill pass across old issues.

Issues filed before 2026-09-09 don't follow this convention -- don't retroactively edit
them unless separately asked.

## Stick to plain ASCII in Summary and Description

Write Summary and Description using only plain ASCII characters -- no curly/smart quotes,
em/en dashes, non-breaking spaces, or other high-byte Unicode. Use `--` instead of an em
dash, straight `'`/`"` instead of curly ones, and a literal `<`/`>` rather than an HTML
entity like `&lt;`/`&gt;`.

**Why**: SDP-1391 was filed with `&lt;` literally baked into the Summary (an HTML-entity
artifact from how it got created) instead of a plain `<` -- caught and fixed after the
fact. Plain ASCII sidesteps this whole class of encoding/escaping glitches, and keeps text
copy-pasteable into terminals, commit messages, and P4 job descriptions without surprises.

## P4Blog field, set when closing

When transitioning an SDP JIRA issue to Done/Closed, also set the **P4Blog** custom field
(`customfield_10231` as of this writing -- confirm via `getJiraIssue` with `expand: names`
if it looks stale) to a URL of the form `https://workshop.perforce.com/changes/<changelist>`,
referencing the Perforce changelist that fixed the issue.

`P4Blog` is a rich-text field -- editing it via the API requires Atlassian Document Format
(ADF), not a plain string:
```json
{"customfield_10231": {"type": "doc", "version": 1, "content": [{"type": "paragraph", "content": [{"type": "text", "text": "https://workshop.perforce.com/changes/32482"}]}]}}
```
A plain string value fails with "Operation value must be an Atlassian Document".

This is an explicitly weak, low-effort substitute for real `p4 fix` issue<->changelist
association (not available here) -- don't chase complete linkage. If an issue spanned
several changelists, pick one representative (final/most-complete) CL, not an exhaustive
list. Occasionally a P4 Code Review (Swarm) review URL is used instead, but reviews aren't
always available promptly after shelving -- default to a change URL.

## Resolution field gotcha -- set it explicitly, don't trust the transition

This project's "Close" transition (id `2`) moves `status` to `Closed` (statusCategory
`Done`) but does **not** automatically set `resolution`. JIRA's release-blocking
"unresolved work items" check is driven by `resolution` being empty, independent of
`status`/`statusCategory` -- confirmed the hard way during the 2026.1 GA release, when the
"Release version" dialog reported 10 unresolved items for a Fix Version where every issue
was already visibly `Closed`.

After transitioning an issue to Closed, also run `editJiraIssue` with
`{"resolution": {"name": "Done"}}` (or whatever resolution value fits) -- don't assume the
transition handled it.

## fixVersion naming

Versions aren't named exactly like the release string. As observed in the `SDP` project:
- Major/minor releases: named literally, e.g. `"2026.1"`, `"2026.2"`.
- Patch releases: named `"<major>.<minor> Patch <N>"`, e.g. `"2026.1 Patch 1"` -- which is
  what a user means when they say "2026.1.1" or "the next patch." Look it up by JQL
  (`project = SDP AND fixVersion = "2026.1.1"`) if the exact display name isn't already
  known -- JQL matches by the dotted form even though the stored `name` differs.
- Don't assume a patch version exists yet -- check first; if it's not there, ask rather
  than assuming which patch/JIRA version it belongs to.