Every answer Sprint Ledger gives, in the JQL functions, the fields, the gadget and the export, comes from one reconstruction of each sprint, built from the history Jira keeps for every issue. This page says exactly how that reconstruction decides what an issue did in a sprint, so that a number can be checked, and where it differs from Jira's own Sprint Report.
For each issue: every change Jira recorded to its Sprint field, status and estimate, and when the issue was created. For each sprint: its start date, its completion date, its state and the board it was created on. For each board: which statuses sit in which column, and which field holds the estimate. Nothing is guessed from the issue's current state when the history says otherwise.
From the Sprint field's history the app builds each issue's membership of each sprint: periods that begin when the sprint was added to the issue and end when it was taken away. An issue created directly inside a sprint has no such change in its history, so its membership begins when the issue was created.
Two moments decide everything: the sprint's start, its start date, and its close, its completion date, or now for the active sprint.
| An issue is | when | In the Sprint Report |
|---|---|---|
| Committed | it was in the sprint at the start | listed without an asterisk |
| Added after start | it was not committed, and joined the sprint after the start and before the close | marked with an asterisk |
| Removed | it was committed or added after start, and was no longer in the sprint at the close | Issues Removed From Sprint |
| Added then removed | it was added after start and removed | only under Issues Removed From Sprint |
| Completed | it was in the sprint at the close, with a status that counts as done, and was not already done at the start and ever since | Completed Issues |
| Carried over | it was in the sprint at the close, and not done | Issues Not Completed |
| Completed outside | it was in the sprint at the close, and had been done without a break since before the start, however it joined | Issues completed outside of this sprint |
Completed outside is Jira's own rule. An issue that was already done when the sprint started, and still done when it closed, did no work in that sprint, so Jira's report lists it apart and counts it neither as completed nor as not completed. Sprint Ledger does the same: such an issue is in neither completedIn() nor carriedOverFrom(), it does not count in say/do, and its tag is o:, so "Sprint tags (Ledger)" = "o:5231" finds the ones of sprint 5231. The commonest case is an issue carried over and finished between two sprints. An issue that was reopened during the sprint and done again, or that became done after the start while it was out of the sprint, is completed, as in the report.
Done means, by default, a status in the rightmost column of the sprint's board, as the Sprint Report counts it. An administrator can switch to "any status in the Done category" on the admin page; the whole history is then classified again, without reading Jira.
Completed, carried over and completed outside are final only for closed sprints. For the active sprint they describe the state now and change until it closes, which is why completedIn() and carriedOverFrom() answer for closed sprints only.
Estimates. A committed issue's estimate is the one it had at the start, an added issue's the one it had when it joined, as the Sprint Report does; the completed estimate is the one at the close, or at the moment of removal for a removed issue, which is the work its removal took out of the sprint. The Sprint Report shows a removed issue's estimate as it was at the close instead, so the two differ when an issue was re-estimated after it left (see the differences below). When the estimate was never changed, its current value is used.
| Case | What Sprint Ledger does |
|---|---|
| Committed, taken out, then put back before the close | Committed, and not removed, as in the Sprint Report |
| Added and taken out several times during the sprint | If it was committed: Removed when absent at the close, otherwise Committed. If not: Added then removed when absent at the close, otherwise Added after start |
| Subtasks | Their history is kept, but they are left out of counts, tags and fields unless an administrator turns on counting them; Jira's report leaves them out too. In team-managed projects subtasks are never sprint members |
| Parallel sprints, and a sprint shared by several boards | A sprint is identified by its ID, and membership does not depend on the board. The board the sprint was created on supplies the columns and the estimate field |
| The start date edited after the sprint started | The sprint is classified again with the new date |
| A deleted sprint | Its history is kept, but it produces no tags or field values, so the functions never return it |
| A deleted issue | Left out of every count, as it is gone from the Sprint Report too. An issue deleted before the app was installed left no history to read |
| An issue moved to another project | Followed by its ID, which Jira keeps |
| The board's columns rearranged after a sprint closed | The current columns are used, which can move an old sprint's completed count; see the differences below |
| An issue removed from every sprint it was ever in | Its Sprint field is empty, so Jira no longer lists it with any sprint. The reconstruction also reads issues without a sprint that were updated within a window before the first sprint start, 12 months by default, set on the admin page |
| An issue in more than 100 sprints' worth of tags | The oldest sprints' tags are dropped, whole sprints at a time; the carry count and the history are unaffected |
| A board whose filter is private | Jira does not show the board to apps, so its sprints are not reconstructed until the filter is shared with the project (FAQ) |
Seven differences are expected, and none is a bug:
| You will see | Why |
|---|---|
| Subtasks missing from both | Jira's report leaves them out and so does Sprint Ledger by default. The admin page's subtask setting counts them. |
An issue added after the start and then removed appears in both addedAfterSprintStart and removedFromSprint, while the report lists it only under "Issues Removed From Sprint" | Both statements are true, and a scope-change report needs both. The report shows each issue once, in one list. |
| An old sprint's completed count differs | "Completed" follows the board's columns as they are now. If the columns were rearranged after the sprint closed, the count can move. Defining done by status category on the admin page makes the answer independent of the columns. |
| An issue that was in the sprint but no longer matches the board's filter is counted by Sprint Ledger and missing from the report | Jira's report shows only the sprint's issues that the board's filter matches at the moment you open it, so it changes whenever the filter or the issue changes. Sprint Ledger counts every issue that was in the sprint, as JQL's sprint = … does, so a sprint's history stays as it was. The admin page's check asks Jira whether the filter still matches and names these issues. |
| On a site where only some projects are turned on, an issue of a project that is off is listed by the report and missing from Sprint Ledger | Sprint Ledger reads no issue of a project it is turned off for. With "Every project with a sprint board" on, it counts every issue on a tracked board's sprints, including issues of projects that have no board of their own. |
| An issue put into a sprint after the sprint closed is listed by the report and missing from Sprint Ledger | Jira's own screens refuse to add an issue to a closed sprint, yet an issue's history can show a sprint added after it closed. Jira's report then lists the issue under "Issues Removed From Sprint", or under "Issues completed outside of this sprint" when it was already done before the sprint started, although it was never in the sprint while the sprint ran. Sprint Ledger leaves it out of that sprint. The admin page's check reads when each such issue joined and names it. |
| A removed issue's estimate differs | For an issue removed from the sprint, the report shows the estimate it had when the sprint closed; Sprint Ledger keeps the one it had when it left, which is the work its removal took out of the sprint. The two differ only when the issue was re-estimated after it left, and the admin page's check names those issues. |
On the app's test site, fifty closed sprints were compared list by list with Jira's Sprint Report, ten of them built to exercise the cases above and forty sampled from five years of a larger project: forty-nine agreed exactly, and the fiftieth differed only by the second case in the table.
The quickest check is on the admin page: Compare with Jira's Sprint Report reads Jira's own report for the last three closed sprints of a board and compares it with the ledger issue by issue, including each issue's estimate at the start and at the close, and names every difference with its reason. To check a sprint by hand:
"Sprint tags (Ledger)" = "o:" followed by the sprint's ID:issue in committedTo("ACME Sprint 41")
issue in addedAfterSprintStart("ACME Sprint 41")
issue in removedFromSprint("ACME Sprint 41")
issue in completedIn("ACME Sprint 41")
issue in carriedOverFrom("ACME Sprint 41")For an issue that appears in one list and not the other, open it and add the Sprint history (Ledger) panel: it shows when the issue entered and left the sprint and the status it had at the close, which is usually the whole explanation.
Anything that differs other than the seven cases above is a bug, and we want to hear about it: the sprint, the issue key and what each side said is enough (Support).