Cycles

A cycle is a dated slice of a project's work: "these issues, these two weeks". It is the same idea a software team calls a sprint, and you do not have to use it — a server that just keeps a board of things to do can ignore cycles entirely. It becomes useful the day somebody asks "what are we actually doing this fortnight", because that is a question a board of fifty issues cannot answer and a cycle of eight can. It becomes useful a second time the day somebody asks "what did we ship", because a completed cycle answers that with its numbers frozen and its patch notes written.

Cycles belong to one project. Each has a number, handed out in order when you create it, and an optional name: Cycle 4, or Cycle 4 — Launch week.

Creating one

The Cycles view — the button in the page header, which you press again to go back to the issues — groups the project's cycles into active, upcoming and past, and New cycle opens the form:

The number is FlaviBot's to hand out: cycle 1, then 2, then 3, per project. You never type it, and two cycles of the same project can never carry the same one.

Nothing stops two cycles from overlapping, and nothing forces them to be back-to-back — a gap between one cycle and the next is a perfectly normal way to run a volunteer team.

Putting issues in a cycle

An issue's Cycle is one of its properties, set in the issue page. An issue can be in one cycle or in none; only the cycles of its own project are offered, and No cycle takes it back out.

A cycle is a window over the work, not another place to put it: an issue in a cycle sits on the board exactly where its state says it should, and what a cycle holds is read in the Cycles view. If you do want to see the cycles side by side for a moment, the board can be grouped by cycle, which turns them into columns for as long as you are looking — it moves nothing.

The list

The Cycles view is a list and a page: every cycle of the project down the left, the one you picked drawn as the page beside it. The list groups them into running, upcoming and finished — the running one being whichever open window today falls inside, first in the list — and each row carries its dates, when it starts or ends, how many of its issues are closed and what share of it that is, as a percentage and a small ring.

The running cycle is picked for you when you open the view, because "are we going to finish" is the question it is usually opened with. Picking another one replaces it, and a live update never moves your choice. The one you are reading is in the address bar as ?cycle=, so a cycle is something you can send somebody a link to.

Closed means the issue is in a completed or a cancelled column. Both count as resolved, so a cycle whose issues were all cancelled still reads 100%. That is on purpose: the percentage answers "is anything still open in this cycle", which is what you glance at a list for. The cycle's own page tells the two apart.

A cycle is open until somebody completes it. The end date passing is not that: an open cycle whose window is over still counts live, and sits under past with its numbers still moving, until you complete it.

The cycle page

Picking a cycle draws its page on the right. The burn-up leads it, because the shape of a fortnight is the thing a percentage cannot draw, and the numbers hang under the chart on its own grid rather than in front of it.

Between the two is the composition bar: the cycle's scope drawn as itself, one band per state — completed, in progress, not started, backlog, and cancelled hatched — in the same order and the same colours as the cells below it. It is the same five numbers as a shape, for the glance that does not stop to read them.

Those cells each answer a different question, so it is worth knowing which:

Two badges sit beside those tiles when they apply:

And one line stands apart from the tiles: N completed in the window · N of them outside this cycle — issues of the project completed between the cycle's start and its end, by the date they closed, whatever cycle they are in now, or none, with how many of those are not in this cycle.

That last line is the difference between in this cycle and completed in the window, and it is the difference that matters when you write up a fortnight. In this cycle is what you planned and how it went: scope, completed, in progress, added, carried over. Completed in the window is what actually landed between those two dates — including the urgent fix nobody put in the cycle, and excluding the issue that was in the cycle but closed the week after. The patch notes are built from the second one.

Under the header, three breakdowns — by assignee, by label and by state — each row with how many issues and how many of them are done, and each of them a click away from the board filtered to exactly those.

Where anything in the cycle carries an estimate, the page shows points beside the issue counts — the same numbers the board's column headers sum — and the issues nobody sized count as zero.

Burn-up

An open cycle that has started gets a chart: a burn-up, one point per day of the cycle so far, from its first day to today. It is the picture of a fortnight that a percentage cannot draw.

The first three stop at today — the days that have not happened yet are not days the team failed to finish anything — while the even finish carries on to the end, which is the whole point of it. Days are counted in UTC, the way every chart in the module is, and a cycle longer than 120 days draws its first 120.

The started line reads when work began, not where the issue sits today: an issue moved back out of a started column stays on the line from the day it first entered one. That is also why the line can sit above the header's In progress tile, which only counts the issues in a started column right now.

Read it as a shape rather than a number. A completed line running above the even finish is a cycle that is ahead; one running flat for four days and then jumping is a team that finished everything on the last afternoon, which is worth knowing before you plan the next one; a scope line that keeps climbing is work being added to a cycle that had already started; a wide gap between started and completed that never closes is too much in progress at once — see WIP limits.

The chart is drawn in points when anything in the cycle is estimated, with the unsized issues counting as zero; when nothing is estimated it counts issues instead. In points every number the chart prints carries pts after it — the end of each line and the day panel alike — because the cells hung under the chart count issues, and the two would otherwise print different numbers under the same word. The axis label says which unit it is and, in points, that unsized issues count as zero — it does not say how many of them there are. A team that does not size its work gets a useful chart either way; a team that sizes half of it should know that the other half weighs nothing here before trusting the shape.

Points are points whichever ladder the project spells them in: a t-shirt XL and a fibonacci 8 are the same 8 to this chart, because the scale is only how the number is written down. Changing a project's scale therefore redraws nothing here. See choosing a scale.

Scope is dated by the day an issue was put into the cycle, not the day it was created: pull a month-old backlog issue in on day six and the chart shows it as scope on day six. An issue taken out and put back counts from the day it came back, and one that was already closed when it joined only counts as completed from that day on. Saving an issue without touching its cycle changes none of this.

On an open cycle the chart is live, and live means honest about today rather than about history: which line an issue is on for every past day is decided by what the issue is now, so reopening an issue yesterday takes it off the completed line for the whole cycle. That is the reason a completed cycle keeps the chart it had the moment it was completed.

While the cycle is running the plot shades the days that have not happened, rules the last counted day, carries today's scope forward to the finish line as a dotted guide and brackets the gap still between completed and that line — the N left the cycle is actually being asked about. A cycle whose window has closed drops all four: there is no today inside it any more, and the shape it ended on is the whole of what there is to read.

Each line is named at its own end rather than in a legend, and hovering the plot reads one day out of it: the date, and where each of the four lines stood at the end of it.

An upcoming cycle has no chart: nothing has happened yet.

Completing a cycle

A cycle ends when you say so, not when its end date passes. Complete cycle, on the cycle's page, is for anyone who can manage the project, and it does three things at once:

• Freezes the numbers. The header, the breakdowns, the burn-up and the list of issues still open at that moment are written down as they stand, and a completed cycle reads from that record from then on. Its numbers never move again: reopen one of its issues next month, cancel another, archive a third, and the completed cycle still says what it said on the day. The page marks itself as frozen so you know you are reading a record and not a live count.
• Ends the window. Completing a cycle early moves its end date to today, so the days after are not drawn as days the cycle was still running and completed in the window stops at the moment you pressed the button. Completing one whose date has already passed leaves the dates alone.
• Asks about what is left. The dialog counts the issues still open and offers to roll them over into the next open cycle of the project — or to leave them where they are.

Rolling over moves every open issue of the cycle into the one you chose, in one go, and marks each of them carried over there: the new cycle's page counts them under carried over, not under added mid-cycle, whichever day you pressed the button. Each issue's activity trail gets a rolled over from cycle N line, and its Discord card is repainted like any other change. Move one of those issues to another cycle by hand later and it stops being carried over; it is simply in that cycle.

Leaving them is the other honest answer. An unfinished issue is not FlaviBot's decision to make, and a team that opens the next cycle by hand and picks what comes along, one issue at a time, is doing exactly what the rollover does with more thought. Either way the completed cycle keeps the list of what was still open when it closed, so the record of what that fortnight did and did not do survives whatever happens to the issues afterwards.

Two things a completion refuses: a cycle that has not started — there is nothing to freeze — and one that is already completed. Rollover only ever targets an open cycle of the same project; if there is none yet, create it first, or leave the issues and move them later.

Velocity

Above the list, once the project has completed a cycle, a velocity chart lines the completed cycles up oldest to newest with two bars each: what was planned — the issues in the cycle by the end of its first day — and what was completed. Points, where the cycles carried them, sit beside the issue counts, and each bar knows how many issues were added mid-cycle and how many were carried over.

It is read across, not down. Three cycles that plan twelve and complete seven are a team that plans for twelve and does seven, and the next cycle should plan seven; a completed bar that keeps growing while the planned bar does not is a team getting faster, or one starting to plan honestly. Because it is drawn from the frozen records, it cannot be nudged after the fact — which is what makes it worth looking at.

Cycles you never completed do not appear. If the chart is empty, that is why.

Patch notes

The Shipped tab of a cycle's page lists what the header calls completed in the window: every issue of the project completed between the cycle's start and its end, most recently closed first, whether or not it was ever in the cycle. It is the changelog of the fortnight, and two buttons turn it into one you can post:

The notes are written the same way every time:

• A title — the cycle's name or number — and the window under it.
• One section per label, most-used label first. An issue carrying two labels appears under the first section it matches, once: an entry in two places reads as a duplicate, not as thoroughness. Issues carrying no label come last, under Other changes.
• One line per issue: the identifier, then the sentence, then who did it and any merged pull request from GitHub — an open pull request on a shipped issue is a warning, not a link. The sentence is the issue's title, so a title written for the people who will read the changelog reads better here than one written for the board.
• A Full changelog link at the foot, which opens the dashboard on the same project, cycle and window, for anyone who wants the list behind the notes.

Two kinds of issue are left out on purpose. Cancelled issues are closed but not shipped, so a cycle that closed ten and cancelled three writes seven lines. Sub-issues fold into their parent: a shipped feature reads as one line, not as its six pieces.

The same list is the Shipped filter on the board and the list — completed between two instants, whatever cycle the issue sits in — which is how you write patch notes for a week, a month, or a cycle you never made: set the window and copy. Up to 500 issues go into one copy, which is more than any changelog should carry.

Editing and deleting

Dates and name are editable at any time on an open cycle, including a running one; stretching a cycle by a week is a normal thing to do and changes nothing about the issues in it. Once a cycle is completed its dates are frozen with the rest of its record — the name stays editable.

Deleting a cycle removes the cycle only. Its issues survive, having simply stopped belonging to one, and land back in No cycle where you can put them in the next. Numbering carries on from the highest cycle the project still has, so deleting the most recent one hands its number to whatever you create next — another reason to name a cycle you intend to refer back to. Deleting a completed cycle deletes its record with it, and the velocity chart forgets it.

For the server-wide view of the same questions — how long things take, who carries what, how the open pile moves week by week — see Insights.

Next: the Discord side.