Show what picks leave behind and why each Jira key is there (#53)

Author: lesnik512

demo/scenario.py

@@ -61,6 +61,7 @@ class DemoIssue:
     category: str
     issue_type: str = "Story"
     links: tuple[str, ...] = ()
+    blocked_by: tuple[str, ...] = ()
 
 
 SERVICES: typing.Final = (
@@ -175,7 +176,12 @@ class DemoIssue:
             ),
         ),
     ),
-    DemoService(id=14, name="admin", production="3.1.0"),
+    DemoService(
+        id=14,
+        name="admin",
+        production="3.1.0",
+        linked=(LinkedMergeRequest(iid=15, title="SHOP-44 Export permission for managers", state="opened"),),
+    ),
 )
 
 ISSUES: typing.Final = (
@@ -200,6 +206,7 @@ class DemoIssue:
         status="In Review",
         category="indeterminate",
         links=(f"{ENDPOINT}/shop/api/-/merge_requests/40",),
+        blocked_by=("SHOP-45",),
     ),
     DemoIssue(
         key="SHOP-38",
@@ -211,6 +218,7 @@ class DemoIssue:
             f"{ENDPOINT}/shop/web/-/merge_requests/120",
             f"{ENDPOINT}/shop/mobile/-/merge_requests/7",
         ),
+        blocked_by=("SHOP-44",),
     ),
     DemoIssue(
         key="SHOP-40",
@@ -226,6 +234,14 @@ class DemoIssue:
         category="indeterminate",
         links=(f"{ENDPOINT}/shop/web/-/merge_requests/125",),
     ),
+    DemoIssue(
+        key="SHOP-44",
+        summary="Only managers may export orders",
+        status="In Progress",
+        category="indeterminate",
+        links=(f"{ENDPOINT}/shop/admin/-/merge_requests/15",),
+    ),
+    DemoIssue(key="SHOP-45", summary="Pick the dark palette with design", status="To Do", category="new"),
 )
 
 
@@ -383,6 +399,13 @@ def _issue(issue: DemoIssue) -> dict[str, typing.Any]:
             "summary": issue.summary,
             "status": {"name": issue.status, "statusCategory": {"key": issue.category}},
             "issuetype": {"name": issue.issue_type},
+            "issuelinks": [
+                {
+                    "type": {"name": "Blocks", "inward": "is blocked by", "outward": "blocks"},
+                    "inwardIssue": {"key": key},
+                }
+                for key in issue.blocked_by
+            ],
         },
     }
 

docs/page.md

@@ -39,7 +39,8 @@ Opening a line shows:
 - a link to create the next tag on the head, when rows have no tag yet;
 - the rows, each with its tags and their pipelines, its merge requests or commits with when they were merged or
   committed, Jira keys with their status, the time each environment first ran it, and failed jobs. Rows out of scope
-  are dimmed.
+  are dimmed. Each Jira key says why the row carries it: `named` when the merge request or commit mentions it,
+  `linked` when the Jira issue links to the change, or both.
 
 Links open in a new tab, including the GitLab settings pages that warnings and errors point to.
 
@@ -57,7 +58,9 @@ starts from the release tags again.
 ## Choosing issues
 
 When the report has Jira issues, the **Issues** list at the top of the Release column picks tags from issues instead.
-It lists every issue in the report, Done first and the rest after, by Jira's status category. You can filter it by
+It lists every issue in the report, Done first and the rest after, by Jira's status category. Related issues, which
+the report holds only because another issue relates to them, come last in a group of their own. Hover over a key to
+see its relations, such as `is blocked by SHOP-44`. You can filter it by
 key or summary, or show only the chosen issues.
 
 Under each issue are the services it touches, each with one of:
@@ -96,11 +99,22 @@ The **Release** column sits next to the services and stays in view while they sc
 screen. While a service is open, the column folds into a strip with the number of picked tags and tasks, so the rows
 get the full width. Clicking the strip closes the service.
 
+Above the tabs, **Left behind by these picks** lists what the picked tags leave out for every Jira task they ship,
+and for every issue related to one:
+
+- a service where the task or related issue has changes that no pick covers, with the tag it needs or why there is
+  none: `no tag yet`, `not merged`, `merged into <branch>`, `in prod or not merged`, `not in this report`, or
+  `failed to collect`;
+- a related issue with no changes at all that is not done in Jira, with its status.
+
+Changes already in production and closed merge requests are not listed.
+
 It turns the picked tags into four tabs. Each has a copy button and a text box to copy from by hand, since browsers
 allow the copy button only over HTTPS.
 
 - **Jira tasks**: the keys of every in-scope row from each picked tag down to production, without duplicates, with
-  summary and a status badge: grey for to do, blue for in progress, green for done. Copy them one per line, or as a
+  summary, a status badge (grey for to do, blue for in progress, green for done), and the merge requests or commits
+  that bring each one, such as `from api !57, web !120`. Copy them one per line, or as a
   JQL `key in (...)` clause.
 - **Tag pipelines**: the pipeline of each picked tag, as a Markdown list.
 - **Compare**: a GitLab compare link per service from production to the picked tag, as a Markdown list. A service

release_scope/_static/index.html

@@ -126,6 +126,7 @@
   .issue-row:hover { background: color-mix(in srgb, var(--accent) 5%, transparent); }
   .issue-row.chosen { background: color-mix(in srgb, var(--accent) 10%, transparent); }
   .issue-row code { font-weight: 500; }
+  .gaps ul { margin: 4px 0 12px; padding-left: 18px; }
   .issue-row .summary { overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
   .issue-row .reach { grid-column: 3 / -1; display: flex; gap: 4px; overflow: hidden; white-space: nowrap; }
   .rider-mark { padding: 0 6px; border: 1px dashed var(--warn); border-radius: 999px; color: var(--warn); font-size: 11px; white-space: nowrap; }
@@ -284,8 +285,9 @@ <h2 x-text="t('services')"></h2>
                       </td>
                       <td>
                         <template x-for="key in row.jira_keys" :key="key.key">
-                          <div>
+                          <div class="row-key">
                             <a :href="key.url" x-text="key.key"></a>
+                            <span class="muted via" :title="t('viaTitle')" x-text="viaText(key)"></span>
                             <span x-show="issue(key.key)" :class="statusClass(issue(key.key))" x-text="issue(key.key) && issue(key.key).status"></span>
                             <span x-text="issue(key.key) ? issue(key.key).summary : ''"></span>
                           </div>
@@ -354,7 +356,7 @@ <h2><span x-text="t('chooseIssues')"></span>
                 <label class="issue-row" :class="{ chosen: chosen.includes(key) }">
                   <input type="checkbox" :checked="chosen.includes(key)" @change="toggleIssue(key)">
                   <span class="dot" :class="'dot-' + (issue(key).status_category || 'new')" :title="issue(key).status"></span>
-                  <code x-text="key"></code>
+                  <code :title="relationsText(key)" x-text="key"></code>
                   <span class="summary" :title="issue(key).summary" x-text="issue(key).summary"></span>
                   <span class="rider-mark" :title="t('shipsAnywayTitle')" x-text="t('shipsAnyway')"
                     :style="{ visibility: shipsAnyway(key) ? 'visible' : 'hidden' }"></span>
@@ -374,6 +376,12 @@ <h2 x-text="t('release')"></h2>
       <p x-show="!pickable.length" class="muted" x-text="t('noCandidates')"></p>
       <p x-show="pickable.length && !picked.length" class="muted" x-text="t('pickToFill')"></p>
       <p x-show="copyFailed" class="warn" x-text="t('copyFailed')"></p>
+      <div class="gaps" x-show="picked.length && gaps.length">
+        <p class="warn" x-text="t('gapsTitle')"></p>
+        <ul>
+          <template x-for="gap in gaps" :key="gap"><li x-text="gap"></li></template>
+        </ul>
+      </div>
 
       <div class="outputs" x-show="picked.length">
         <div class="tabs">
@@ -394,6 +402,7 @@ <h2 x-text="t('release')"></h2>
                 <span x-show="task.issue" :class="statusClass(task.issue)" x-text="task.issue && task.issue.status"></span>
                 <span x-text="task.issue ? task.issue.summary : ''"></span>
                 <span x-show="isMissing(task.key)" class="warn" x-text="t('notInJira')"></span>
+                <span x-show="task.sources.length" class="muted sources" x-text="t('taskFrom', { items: task.sources.join(', ') })"></span>
               </li>
             </template>
           </ul>
@@ -551,6 +560,15 @@ <h2 x-text="t('release')"></h2>
       planAlso: "also ships",
       planNoTag: "{keys}: no tag yet.",
       planElsewhere: "{items}, nothing to pick",
+      groupRelated: "Related",
+      viaNamed: "named",
+      viaLinked: "linked",
+      viaTitle: "named: the merge request or commit mentions the key; linked: the Jira issue links to this change",
+      taskFrom: "from {items}",
+      gapsTitle: "Left behind by these picks:",
+      gapNeeds: "needs {tag}",
+      relationParent: "has parent",
+      relationSubtask: "has subtask",
     },
     ru: {
       language: "Язык",
@@ -651,6 +669,15 @@ <h2 x-text="t('release')"></h2>
       planAlso: "также войдут",
       planNoTag: "{keys}: тега ещё нет.",
       planElsewhere: "{items}, выбирать нечего",
+      groupRelated: "Связанные",
+      viaNamed: "в тексте",
+      viaLinked: "по ссылке",
+      viaTitle: "в тексте: ключ упомянут в MR или коммите; по ссылке: задача в Jira ссылается на это изменение",
+      taskFrom: "из {items}",
+      gapsTitle: "Не войдёт с этими тегами:",
+      gapNeeds: "нужен {tag}",
+      relationParent: "родитель",
+      relationSubtask: "подзадача",
     },
   };
 
@@ -881,13 +908,64 @@ <h2 x-text="t('release')"></h2>
       },
       get tasks() {
         const tasks = new Map();
-        for (const { candidate } of this.picked) {
+        for (const { service, candidate } of this.picked) {
+          const shipped = service.rows.slice(this.tagRow(service, candidate.tag.name)).filter((row) => row.in_scope);
           for (const key of candidate.jira_keys) {
-            if (!tasks.has(key.key)) tasks.set(key.key, { key: key.key, url: key.url, issue: this.issue(key.key) });
+            if (!tasks.has(key.key)) tasks.set(key.key, { key: key.key, url: key.url, issue: this.issue(key.key), sources: [] });
+            tasks.get(key.key).sources.push(
+              ...shipped
+                .filter((row) => row.jira_keys.some((item) => item.key === key.key))
+                .map((row) => `${this.shortName(service.project)} ${this.changeLabel(row)}`),
+            );
           }
         }
         return [...tasks.values()];
       },
+      get gaps() {
+        const starts = new Map(this.picked.map(({ service, candidate }) => [service.project, this.tagRow(service, candidate.tag.name)]));
+        const gaps = new Set();
+        const check = (source, relation, key) => {
+          const via = relation ? ` ${this.relationLabel(relation)} ${key}` : "";
+          const reach = this.reach[key] || [];
+          for (const item of reach) {
+            const reason = this.gapReason(item, starts);
+            if (reason) gaps.add(`${source}${via} → ${this.shortName(item.project)}: ${reason}`);
+          }
+          const issue = this.issue(key);
+          if (relation && !reach.length && issue && issue.status_category !== "done") gaps.add(`${source}${via}: ${issue.status}`);
+        };
+        for (const task of this.tasks) {
+          check(task.key, null, task.key);
+          for (const relation of task.issue ? task.issue.relations : []) check(task.key, relation, relation.key);
+        }
+        return [...gaps];
+      },
+      gapReason(item, starts) {
+        if (item.state === "tag" || item.state === "untagged") {
+          const start = starts.get(item.project);
+          if (start !== undefined && start <= item.index) return "";
+          return item.state === "tag" ? this.t("gapNeeds", { tag: item.tag }) : this.t("reachUntagged");
+        }
+        return ["production", "older", "closed"].includes(item.state) ? "" : this.reachLabel(item);
+      },
+      tagRow(service, tag) {
+        return service.rows.findIndex((row) => row.tags.some((item) => item.name === tag));
+      },
+      changeLabel(row) {
+        return row.merge_requests.length ? row.merge_requests.map((item) => "!" + item.iid).join(" ") : row.commits[0].short_sha;
+      },
+      viaText(key) {
+        return key.via.map((source) => this.t(source === "named" ? "viaNamed" : "viaLinked")).join(", ");
+      },
+      relationLabel(relation) {
+        if (relation.kind === "parent") return this.t("relationParent");
+        if (relation.kind === "subtask") return this.t("relationSubtask");
+        return relation.label;
+      },
+      relationsText(key) {
+        const issue = this.issue(key);
+        return issue ? issue.relations.map((relation) => `${this.relationLabel(relation)} ${relation.key}`).join("\n") : "";
+      },
       get taskKeys() {
         return this.tasks.map((task) => task.key).join("\n");
       },
@@ -938,9 +1016,11 @@ <h2 x-text="t('release')"></h2>
             (!text || `${key} ${this.issue(key).summary}`.toLowerCase().includes(text)),
         );
         const done = (key) => this.issue(key).status_category === "done";
+        const related = (key) => this.issue(key).via_relation;
         return [
-          { name: "groupDone", keys: keys.filter(done) },
-          { name: "groupNotDone", keys: keys.filter((key) => !done(key)) },
+          { name: "groupDone", keys: keys.filter((key) => !related(key) && done(key)) },
+          { name: "groupNotDone", keys: keys.filter((key) => !related(key) && !done(key)) },
+          { name: "groupRelated", keys: keys.filter(related) },
         ].filter((group) => group.keys.length);
       },
       get plan() {
@@ -1023,7 +1103,7 @@ <h2 x-text="t('release')"></h2>
       },
       untickMissed(service) {
         const tag = this.picks[service.project];
-        const picked = tag ? service.rows.findIndex((row) => row.tags.some((item) => item.name === tag)) : -1;
+        const picked = tag ? this.tagRow(service, tag) : -1;
         const missed = this.chosen.filter((key) =>
           this.reach[key].some((item) => item.project === service.project && item.state === "tag" && (picked === -1 || picked > item.index)));
         if (!missed.length) return;

tests/test_browser.py

@@ -117,7 +117,7 @@ def test_demo_lists_its_services_and_picks_tags_for_an_issue(page: Page, demo_si
     names = page.locator("details.service .name")
     expect(names).to_have_text(["admin", "api", "web", "worker"])
     expect(names.first).to_have_attribute("title", "shop/admin")
-    expect(page.locator(".issue-row code")).to_have_count(6)
+    expect(page.locator(".issue-row code")).to_have_count(8)
     _issue(page, "SHOP-38").check()
     expect(page).to_have_url(re.compile(r"#issues=SHOP-38&shop/api=2\.5\.0&shop/web=1\.9\.0$"))
     assert errors == []
@@ -311,3 +311,69 @@ def test_demo_service_rows_line_up_with_and_without_a_pick(page: Page, demo_site
     assert names[0] == pytest.approx(names[1], abs=0.5)
     assert max(states) - min(states) < 0.5, states
     assert errors == []
+
+
+def test_row_keys_say_whether_the_change_names_them_or_jira_links_them(
+    page: Page, site: str, errors: list[str]
+) -> None:
+    page.goto(site)
+
+    page.locator("details.service summary").click()
+
+    row_key: typing.Final = page.locator(".row-key", has=page.locator("a", has_text="SHOP-12")).first
+    expect(row_key.locator(".via")).to_have_text("named, linked")
+    expect(page.locator(".row-key", has=page.locator("a", has_text="SHOP-9")).locator(".via")).to_have_text("named")
+    assert errors == []
+
+
+def test_demo_a_hand_pick_lists_the_changes_it_leaves_behind(page: Page, demo_site: str, errors: list[str]) -> None:
+    page.goto(demo_site)
+    gaps: typing.Final = page.locator(".gaps li")
+
+    api: typing.Final = _demo_service(page, "shop/api")
+    api.locator("summary").click()
+    api.locator(".tag", has_text="2.5.0").get_by_role("button").click()
+
+    expect(gaps).to_have_text(
+        [
+            "SHOP-38 → web: needs 1.9.0",
+            "SHOP-38 → mobile: not in this report",
+            "SHOP-38 is blocked by SHOP-44 → admin: not merged",
+            "SHOP-35 → worker: needs 0.15.0",
+        ]
+    )
+    web: typing.Final = _demo_service(page, "shop/web")
+    web.locator("summary").click()
+    web.locator(".tag", has_text="1.9.0").get_by_role("button").click()
+    expect(gaps).to_have_text(
+        [
+            "SHOP-38 → mobile: not in this report",
+            "SHOP-38 is blocked by SHOP-44 → admin: not merged",
+            "SHOP-35 → worker: needs 0.15.0",
+            "SHOP-36 is blocked by SHOP-45: To Do",
+        ]
+    )
+    assert errors == []
+
+
+def test_demo_tasks_name_the_changes_that_bring_them(page: Page, demo_site: str, errors: list[str]) -> None:
+    page.goto(demo_site)
+
+    _issue(page, "SHOP-38").check()
+
+    task: typing.Final = page.locator(".outputs li", has=page.locator("a", has_text="SHOP-38"))
+    expect(task.locator(".sources")).to_have_text("from api !57, web !120")
+    expect(page.locator(".outputs li", has=page.locator("a", has_text="SHOP-35")).locator(".sources")).to_have_text(
+        "from api !55"
+    )
+    assert errors == []
+
+
+def test_demo_related_issues_have_their_own_group_and_relations_show_on_hover(
+    page: Page, demo_site: str, errors: list[str]
+) -> None:
+    page.goto(demo_site)
+
+    expect(page.locator(".issue-group")).to_have_text(["Done · 3", "Not done · 3", "Related · 2"])
+    expect(page.locator(".issue-row code", has_text="SHOP-38")).to_have_attribute("title", "is blocked by SHOP-44")
+    assert errors == []