Re-rank Jira's backlog to match an epic's ranking, moving only the issues the loop filed

This commit is contained in:
2026-11-18 18:51:50 +01:00
parent 92bc84ba80
commit 49fe132be2
8 changed files with 186 additions and 13 deletions
+9
View File
@@ -150,3 +150,12 @@ class EpicStoreContract:
task = self.filed(store, ours, "Count them in the api.")
read = {issue.key: issue for issue in self.issues(store)}
self.assertEqual([read[key].by_loop for key in (ours, theirs, task)], [True, False, True])
def test_ranks_a_child_issue_just_before_or_just_after_another_and_its_sub_tasks_follow_it(self) -> None:
store = self.new_store()
first, second, third = (self.filed(store, store.epic_key, f"Item {n}.") for n in range(3))
task = self.filed(store, third, "A task.")
self.assertEqual(store.rank(third, first), None)
self.assertEqual([issue.key for issue in self.issues(store)], [third, task, first, second])
self.assertEqual(store.rank(third, second, after=True), None)
self.assertEqual([issue.key for issue in self.issues(store)], [first, second, third, task])
+11 -1
View File
@@ -7,7 +7,7 @@ from failure import Failure
@dataclasses.dataclass
class MemoryEpic:
"""An epic whose issues rank in the order filed. Where fails is set, every read and filing fails with it as the reason."""
"""An epic whose issues rank in the order filed, until one is ranked. Where fails is set, every call fails with it as the reason."""
epic_key: str
issues: list[EpicIssue] = dataclasses.field(default_factory=list)
fails: str | None = None
@@ -39,6 +39,16 @@ class MemoryEpic:
self.change(key, labels=tuple(sorted({*child.labels, label})))
return None
def rank(self, key: str, other: str, after: bool = False) -> None | Failure:
if self.fails:
return Failure(self.fails)
children = {issue.key: issue for issue in self.issues if issue.parent == self.epic_key}
if stray := next((each for each in (key, other) if each not in children), None):
return Failure(f"{stray} is not one of the child issues of the epic {self.epic_key}, so it cannot be ranked")
self.issues.remove(children[key])
self.issues.insert(self.issues.index(children[other]) + after, children[key])
return None
def change(self, key: str, **fields: object) -> None:
"""Changes the issue named key as a person would in the tracker, such as assignee="Ada Lovelace"."""
self.issues = [dataclasses.replace(issue, **fields) if issue.key == key else issue for issue in self.issues] # type: ignore[arg-type]
+8 -1
View File
@@ -5,7 +5,7 @@ import typing
from adf_codec.convert import adfs_to_markdown, markdown_to_adf, Refused
from atlassian.client import basic_auth, Http, jira_json, ToAdf, ToMarkdown
from plan_store.jira_epic import blocked_by_links, FILED_BY, ISSUE_KEY, ISSUE_TYPE, project_of, PROPERTY, scores, searched
from plan_store.jira_epic import blocked_by_links, FILED_BY, ISSUE_KEY, ISSUE_TYPE, project_of, PROPERTY, rank_refusal, scores, searched
from project_config.settings import Epic
from do_epic.backend.protocol import EpicIssue, no_child, no_parent, unfit, unfit_label
from failure import Failure
@@ -92,6 +92,13 @@ class JiraEpic:
edited = self.http("PUT", f"{self.epic.site}/rest/api/3/issue/{key}", authorization, {"update": {"labels": [{"add": label}]}})
return Failure(f"cannot label {key}: {edited.reason}") if isinstance(edited, Failure) else None
def rank(self, key: str, other: str, after: bool = False) -> None | Failure:
authorization = basic_auth(self.env_file)
if isinstance(authorization, Failure):
return authorization
refused = rank_refusal(self.epic.site, key, other, after, authorization, self.http)
return Failure(refused) if refused else None
def not_a_parent(self, parent: str, authorization: str) -> Failure | None:
"""Why nothing can be filed under parent; None where it is the epic or one of its child issues."""
if parent == self.epic_key:
+3
View File
@@ -57,6 +57,9 @@ class EpicStore(typing.Protocol):
def add_label(self, key: str, label: str) -> None | Failure:
"""Adds label to the epic's child issue named key, leaving its other labels as they are; adding one it already has leaves the labels as they are. A sub-task, or an issue outside the epic, is refused."""
def rank(self, key: str, other: str, after: bool = False) -> None | Failure:
"""Ranks the child issue named key just before the child issue named other, or just after it where after is True; its sub-tasks follow it. Both must be child issues of the epic, as read answers them: a backend may not check, and Jira ranks any issue it is given."""
def unfit(summary: str, labels: tuple[str, ...]) -> Failure | None:
"""Why no tracker can file an issue with this summary and these labels; None where a tracker can file it."""
+26
View File
@@ -23,6 +23,7 @@ EPIC_URL = f"{SITE}/rest/api/3/issue/ABC-12?fields=summary"
ISSUE_TYPES = f"{SITE}/rest/api/3/issue/createmeta/ABC/issuetypes"
SEARCH = f"{SITE}/rest/api/3/search/jql"
ISSUES = f"{SITE}/rest/api/3/issue"
RANK = f"{SITE}/rest/agile/1.0/issue/rank"
TO_DO = {"name": "To Do", "statusCategory": {"key": "new"}}
TYPES = {"issueTypes": [{"id": "10001", "name": "Task", "subtask": False}, {"id": "10003", "name": "Subtask", "subtask": True}]}
@@ -59,6 +60,8 @@ class FakeJira:
return {"key": held["key"], "fields": {"parent": held["fields"]["parent"]}} # type: ignore[index]
if method == "POST" and url == ISSUES:
return self.created(body)
if method == "PUT" and url == RANK:
return self.ranked(body)
if method == "PUT" and (held := next((issue for issue in self.issues if url == f"{ISSUES}/{issue['key']}"), None)):
assert isinstance(body, dict)
added = [change["add"] for change in body["update"]["labels"]]
@@ -87,6 +90,15 @@ class FakeJira:
self.issues.append({"key": key, "fields": {"summary": fields["summary"], "description": fields.get("description"), "labels": fields["labels"], "assignee": None, "status": TO_DO, "parent": {"key": parent}, "issuelinks": []}, "properties": {entry["key"]: entry["value"] for entry in body["properties"]}})
return {"id": "1", "key": key}
def ranked(self, body: object) -> object:
"""Moves the one issue named just before or just after another, and answers no body, as Jira does for a rank it made."""
assert isinstance(body, dict)
[key], other = body["issues"], body.get("rankBeforeIssue") or body["rankAfterIssue"]
moved = next(issue for issue in self.issues if issue["key"] == key)
self.issues.remove(moved)
self.issues.insert(next(place for place, issue in enumerate(self.issues) if issue["key"] == other) + ("rankAfterIssue" in body), moved)
return None
def change(self, key: str, **fields: object) -> None:
next(issue for issue in self.issues if issue["key"] == key)["fields"].update(fields) # type: ignore[union-attr]
@@ -231,6 +243,20 @@ class Jira(Case):
store = JiraEpic(Epic(SITE, "ABC-99"), self.env_file, self.jira, to_markdown, to_adf)
self.assertEqual(store.read(), Failure(f"cannot read the epic ABC-99: Jira answered 404 for GET {SITE}/rest/api/3/issue/ABC-99?fields=summary"))
def test_a_rank_jira_refuses_fails_with_its_reason_and_ranks_nothing(self) -> None:
store = self.new_store()
first, second = (store.file("ABC-12", f"Item {n}.", "", ()) for n in range(2))
for answer, reason in (
(Failure("Jira answered 403"), "Jira answered 403"),
({"entries": [{"issueKey": second, "status": 400, "errors": ["Rank is not configured"]}]}, "Rank is not configured"),
):
with self.subTest(answer=answer):
self.jira.answers[("PUT", RANK)] = answer
self.assertEqual(store.rank(str(second), str(first)), Failure(reason))
read = store.read()
assert isinstance(read, list), read
self.assertEqual([issue.key for issue in read], [first, second])
if __name__ == "__main__":
unittest.main()
+30
View File
@@ -7,6 +7,7 @@ import ast
import dataclasses
import decimal
from do_epic.backend.protocol import EpicStore
from plan.blockers import blockers_first
from plan.todo_table import CODE_HEALTH, EPIC_GOAL, Item, REPO_GOAL, SHAPE
from failure import Failure
@@ -59,6 +60,35 @@ def ranked(items: list[EpicItem], formula: str, epic_goals: str, repos: dict[str
return blockers_first(scored)
def reranked(store: EpicStore, order: list[str]) -> None | Failure:
"""Ranks the epic's child issues named in order, each one the loop filed, so the tracker's backlog lists them in order. Each other child issue, such as one a person filed, keeps its slot; the slots of the named issues take them in order's order. A sub-task holds no slot and follows its parent.
The walk goes from the backlog's end: an issue not just before the one that follows it in the target ranks just before that one, so only the loop's issues move. The target's last issue, where it isn't already last, ranks just after the issue that is. A rank the tracker refuses stops the walk, which fails naming it, since a wrongly ranked team backlog takes hours to restore; the ranks made before it stay."""
read = store.read()
if isinstance(read, Failure):
return read
children = [issue for issue in read if issue.parent == store.epic_key]
if stray := next((key for key in order if key not in {issue.key for issue in children if issue.by_loop}), None):
return Failure(f"{stray} is not one of the child issues of the epic {store.epic_key} that the loop filed, so the backlog was not re-ranked")
if twice := next((key for key in order if order.count(key) > 1), None):
return Failure(f"the order names {twice} twice, so the backlog was not re-ranked")
now = [issue.key for issue in children]
slots = iter(order)
target = [next(slots) if key in order else key for key in now]
for place in reversed(range(len(target))):
key = target[place]
at = now.index(key)
# The slices are empty past the end, so the last issue already in place is skipped too.
if key not in order or now[at + 1:at + 2] == target[place + 1:place + 2]:
continue
other, after = (now[-1], True) if place == len(target) - 1 else (target[place + 1], False)
if refused := store.rank(key, other, after):
return Failure(f"cannot rank {key} just {'after' if after else 'before'} {other}: {refused.reason}; the re-rank stopped there, so rank the loop's issues in {store.epic_key}'s backlog by hand as {', '.join(order)}")
now.remove(key)
now.insert(now.index(other) + after, key)
return None
def chain_scoring(formula: ast.Expression, epic_goals: str, repo: str | None, own: RepoRanking | None) -> ranking.Scoring | Failure:
"""How an item in repo scores: the chain's goals, and what each achieve goal weighs. The bar is 0, since a bar decides what is filed, and the order holds every item that was.
+88 -1
View File
@@ -6,7 +6,8 @@ import unittest
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[1]))
from do_epic.ranking import chain, EpicItem, ranked, RepoRanking
from do_epic.backend.fake import MemoryEpic
from do_epic.ranking import chain, EpicItem, ranked, reranked, RepoRanking
from failure import Failure
from plan.todo_table import Item, parse_moves
@@ -155,5 +156,91 @@ class RankedTest(unittest.TestCase):
self.assertIsInstance(order([item(1, "epic 1 by 9")], {"billing-api": VOIDED}, "V +"), Failure)
class Recording(MemoryEpic):
"""A MemoryEpic that keeps each rank asked of it, and refuses the one to rank the issue named in refused."""
refused: str | None = None
asked: list[tuple[str, str, bool]]
def rank(self, key: str, other: str, after: bool = False) -> None | Failure:
self.asked.append((key, other, after))
return Failure("Jira answered 403") if key == self.refused else super().rank(key, other, after)
def epic(*people: int, issues: int = 4) -> Recording:
"""An epic of child issues ABC-100 onwards, the loop's apart from those whose places are in people."""
store = Recording("ABC-12")
store.asked = []
for place in range(issues):
store.file("ABC-12", f"Item {place}.", "", ())
if place in people:
store.change(f"ABC-{100 + place}", by_loop=False)
return store
def keys(store: MemoryEpic) -> list[str]:
read = store.read()
assert isinstance(read, list), read
return [issue.key for issue in read]
class RerankedTest(unittest.TestCase):
def test_the_loops_issues_take_their_slots_in_the_order_given_and_a_persons_keep_theirs(self) -> None:
store = epic(1)
self.assertEqual(reranked(store, ["ABC-103", "ABC-100", "ABC-102"]), None)
self.assertEqual(keys(store), ["ABC-103", "ABC-101", "ABC-100", "ABC-102"])
def test_the_last_slot_takes_its_issue_where_a_persons_issue_comes_before_it(self) -> None:
store = epic(0, issues=3)
self.assertEqual(reranked(store, ["ABC-102", "ABC-101"]), None)
self.assertEqual(keys(store), ["ABC-100", "ABC-102", "ABC-101"])
def test_an_order_the_backlog_already_reads_in_ranks_nothing(self) -> None:
store = epic(1)
self.assertEqual(reranked(store, ["ABC-100", "ABC-102", "ABC-103"]), None)
self.assertEqual(store.asked, [])
def test_ranks_only_the_issues_out_of_place(self) -> None:
store = epic(issues=5)
self.assertEqual(reranked(store, ["ABC-100", "ABC-101", "ABC-102", "ABC-104", "ABC-103"]), None)
self.assertEqual(store.asked, [("ABC-103", "ABC-104", True)])
def test_an_issue_the_order_doesnt_name_keeps_its_slot(self) -> None:
store = epic()
store.change("ABC-101", status="Done", done=True)
self.assertEqual(reranked(store, ["ABC-103", "ABC-102", "ABC-100"]), None)
self.assertEqual(keys(store), ["ABC-103", "ABC-101", "ABC-102", "ABC-100"])
def test_sub_tasks_hold_no_slot_and_follow_their_parent(self) -> None:
store = epic(issues=2)
task = store.file("ABC-100", "A task.", "", ())
self.assertEqual(reranked(store, ["ABC-101", "ABC-100"]), None)
self.assertEqual(keys(store), ["ABC-101", "ABC-100", task])
def test_refuses_an_order_naming_a_persons_issue_a_sub_task_an_issue_outside_the_epic_or_one_twice(self) -> None:
store = epic(1)
task = store.file("ABC-100", "A task.", "", ())
for order, reason in (
(["ABC-101", "ABC-100"], "ABC-101 is not one of the child issues of the epic ABC-12 that the loop filed, so the backlog was not re-ranked"),
([task, "ABC-100"], f"{task} is not one of the child issues of the epic ABC-12 that the loop filed, so the backlog was not re-ranked"),
(["ZZZ-1"], "ZZZ-1 is not one of the child issues of the epic ABC-12 that the loop filed, so the backlog was not re-ranked"),
(["ABC-100", "ABC-102", "ABC-100"], "the order names ABC-100 twice, so the backlog was not re-ranked"),
):
with self.subTest(order=order):
self.assertEqual(reranked(store, order), Failure(reason))
self.assertEqual(store.asked, [])
def test_a_rank_the_tracker_refuses_stops_the_walk_and_names_the_order_to_finish_by_hand(self) -> None:
store = epic()
store.refused = "ABC-101"
self.assertEqual(reranked(store, ["ABC-103", "ABC-102", "ABC-101", "ABC-100"]), Failure("cannot rank ABC-101 just before ABC-100: Jira answered 403; the re-rank stopped there, so rank the loop's issues in ABC-12's backlog by hand as ABC-103, ABC-102, ABC-101, ABC-100"))
self.assertEqual(store.asked, [("ABC-100", "ABC-103", True), ("ABC-101", "ABC-100", False)])
def test_a_read_that_fails_ranks_nothing(self) -> None:
store = epic()
store.fails = "Jira is down"
self.assertEqual(reranked(store, ["ABC-101"]), Failure("Jira is down"))
self.assertEqual(store.asked, [])
if __name__ == "__main__":
unittest.main()
+11 -10
View File
@@ -156,7 +156,7 @@ class JiraPlan:
notes.append(f"filed {key}, but cannot link it as blocked by {blocker}: {linked.reason}; link it in Jira")
if isinstance(before, Failure):
notes.append(f"filed {key}, but cannot rank it: {before.reason}; rank it in Jira")
elif before is not None and (refused := self.rank_refusal(key, before, authorization)):
elif before is not None and (refused := rank_refusal(self.epic.site, key, before, False, authorization, self.http)):
notes.append(f"filed {key}, but cannot rank it before {before}: {refused}; rank it in Jira")
return tuple(notes)
@@ -178,15 +178,6 @@ class JiraPlan:
notes.append(f"edited {issue.key}, but cannot delete the link that makes it blocked by {link.blocker}: {deleted.reason}; delete it in Jira")
return tuple(notes)
def rank_refusal(self, key: str, before: str, authorization: str) -> str | None:
"""Ranks the issue named key just before the issue named before; why Jira refused, or None where it didn't. Jira answers a rank it made with no body, and one it refused with an error, or with an entry per issue that holds the errors."""
answer = self.http("PUT", f"{self.epic.site}/rest/agile/1.0/issue/rank", authorization, {"issues": [key], "rankBeforeIssue": before})
if isinstance(answer, Failure):
return answer.reason
entries = answer.get("entries") if isinstance(answer, dict) else None
refused = [entry for entry in entries if isinstance(entry, dict) and entry.get("status") != 200] if isinstance(entries, list) else []
return "; ".join(str(error) for entry in refused for error in entry.get("errors") or [f"Jira answered {entry.get('status')}"]) or None
def fix_version(self, release: str, authorization: str) -> str | Failure:
"""The name of the Jira project's Fix Version for release, which a project may spell with a leading v, as `earliest_release` reads it."""
project = project_of(self.epic.key)
@@ -451,6 +442,16 @@ def children(epic: Epic, authorization: str, http: Http) -> list[object] | Failu
return searched(epic.site, f"{epic.key}'s children", f'parent = "{epic.key}" AND statusCategory != Done ORDER BY Rank ASC', {"fields": ["summary", "description", "fixVersions", "issuelinks"], "properties": [PROPERTY]}, authorization, http)
def rank_refusal(site: str, key: str, other: str, after: bool, authorization: str, http: Http) -> str | None:
"""Ranks the issue named key just before the issue named other, or just after it where after is True; why Jira refused, or None where it didn't. Jira answers a rank it made with no body, and one it refused with an error, or with an entry per issue that holds the errors."""
answer = http("PUT", f"{site}/rest/agile/1.0/issue/rank", authorization, {"issues": [key], "rankAfterIssue" if after else "rankBeforeIssue": other})
if isinstance(answer, Failure):
return answer.reason
entries = answer.get("entries") if isinstance(answer, dict) else None
refused = [entry for entry in entries if isinstance(entry, dict) and entry.get("status") != 200] if isinstance(entries, list) else []
return "; ".join(str(error) for entry in refused for error in entry.get("errors") or [f"Jira answered {entry.get('status')}"]) or None
def searched(site: str, what: str, jql: str, asked: dict[str, object], authorization: str, http: Http) -> list[object] | Failure:
"""Every issue a JQL search on site finds, page by page. The dict asked holds the request's `fields` and `properties` lists. The text what names the issues sought, in the Failure of a search that doesn't end."""
body: dict[str, object] = {"jql": jql, "maxResults": PAGE} | asked