The board and the issue

The board is where the work is. One column per state, cards in each column, and a drag to move a card from one to the next. The list is the same issues as a table, for reading rather than moving — the two are one page, and which of them you get is a switch at the top of Display. Clicking a card on either opens the issue's own page, a real address you can link, bookmark and send.

The project switcher

Everything on the page is about one project at a time, chosen in the switcher in the header. It lists the server's active projects by name and icon, with the one you are reading marked in the accent colour, followed by New project, Edit project for the one you are on, and a Show archived toggle, which is always there whether or not any project is archived. New project is also a button of its own, beside the switcher.

Switching project switches the whole page: the board, the list, the cycles and the workflow shown in Settings all follow it. An archived project is still readable — pick it under Show archived — but read-only: the columns draw, the cards open, and nothing can be dragged or created.

A server with no project at all gets a short "create your first project" card instead of a board. See projects, states and labels.

The board

One column per state of the project, left to right in the order the workflow is in. Each column has a coloured header — the state's own colour — with its name, the number of issues in it, and a + that creates an issue directly in that column. Where the issues are sized, the header also sums their estimates, and where the state carries a WIP limit it shows the count against that limit and warns when it is over.

Columns do not have to be states. In the Display popover at the end of the filter bar, Group by re-buckets the same issues by assignee, priority, label, cycle or project, and Swimlane by adds horizontal bands on top of that, so "columns by state, lanes by assignee" is a board you can have — see views and shortcuts. Everything below describes the board grouped by state, which is where it starts.

A card is read top to bottom:

• the identifier, WEB-12;
• the parent, when the issue has one — WEB-4 › rebuild the pricing page, which is a link to it;
• the status glyph and the title, over two lines at most. The glyph is the shape of the state's type: a dashed circle for a backlog state, an empty one for unstarted, a circle filling like a pie for something in progress, a tick for completed and a cross for cancelled;
• a property row: its priority, its project, its estimate, its labels, a #2891 badge for anything attached from GitHub, its cycle, its team, the time on it, the due date marked once it is in the past, and the number of comments and of sub-issues when it has any;
• the month it was created, at the foot.

The assignee's avatar sits at the right of the identifier line. Everything in the property row is silent when the issue does not carry it, so a bare issue is still a short card. The title and the created month always draw. The identifier and the assignee's avatar are properties like the rest — turn both off in Display and the top line of the card goes with them.

Which of those properties a card shows is yours to choose under Display, along with how tightly the cards are packed. It is a per-person choice: turning the due date off on your own board changes nobody else's.

Columns whose state type is completed or cancelled hold the issues that are done. They are shown like any other column — a board without its Done column is hard to read — but their contents are what Show closed hides everywhere else.

Moving a card

Drag a card and drop it: into another column to change its state, or higher and lower inside its own column to change its order. With a mouse the drag starts as soon as the pointer travels a little; on a touch screen, press and hold — which is why a tap still opens the issue and a swipe still scrolls the column.

While it runs, the card you picked up stays dimmed in place, a copy of it follows the pointer, and a thin line shows the slot it would drop into. Escape abandons the drag and nothing is sent. On a drop the board moves the card straight away and saves in the background; a refused move rolls back on its own, and an error says why.

Order within a column is yours to decide and is kept per column: it is the board's "what next", not a sort. Moving a card to another column puts it exactly where you dropped it there.

Dropping a card into a completed or cancelled column closes the issue: the moment is recorded, it leaves the open counts, and it counts towards its cycle's progress. Dragging it back out reopens it. Nothing is deleted either way.

Every drop repaints the issue's card in Discord and is written to its activity trail, so somebody reading the channel sees the same move you just made.

The filter bar

The board and the list share one filter bar, and what you set applies to both:

The bar sits above both drawings and what you set there stays as you move between them, so narrowing to everything urgent and unassigned on the board and then switching to the list gives you the same issues as a table. The bar also carries Save view, and Display at the end of it holds the board-or-list switch, the grouping, the swimlanes, the ordering, the density and what a card shows: a slice you keep rebuilding is a saved view away.

Active, Backlog, All issues

Above the board, beside the view pills, three segments cut the same issues the way most people actually ask for them:

It is a filter rather than another kind of view, and it narrows whatever the board is already showing: pick a saved view and then a segment, and you get both. Active is where most teams live, because a board that draws its backlog next to its work in progress is a board where the work in progress is three columns from the left.

The segments also sit above the list, where they behave slightly differently and it is worth knowing why. On the board they are exact — the board holds the whole project — and they hide the columns they exclude, so Active has no Done column to drop anything into. The list pages, so there a segment narrows the rows already loaded rather than the project: a segment that empties the page still has a Load more under it. Switching segments never costs a request either way, which is what makes it feel like a tab.

The list

The same issues as a dense table of eight columns: identifier, title, state, priority, assignee, labels, due date and last update. Click a header to sort by it, click again to reverse it — every column but labels sorts. Unlike the board, the list hides closed issues until Show closed asks for them.

It loads a page at a time, with a Load more at the foot and a count of how many rows are loaded. Sorting applies to the rows already loaded, so on a project with more than one page, sorting by due date orders what is on screen rather than the whole project — load the rest first, or narrow the filters.

Order by, in Display, sets the list's order the same way it sets the board's — and a click on a column header overrides it until you pick an order there again. Whichever you touched last is the one you get.

Grouping applies here too: a grouped list is the same rows under headed bands rather than in columns. Each band is headed by the same name, the same count and the same estimate total the board draws over that column, and clicking the header folds the band away — folded bands are remembered per project and per grouping, in the browser you fold them in.

Use the board to decide what happens next, and the list to answer questions — what is overdue, what nobody has picked up, what one person is carrying.

The issue page

Clicking any card, on either, opens that issue at its own address. It holds everything about that one issue, and there is no form to submit: every control saves the moment you change it, so leaving the page loses nothing.

The crumb at the top names the board and the project, and takes you back to them. Your browser's own back button is the shorter way: it returns you to the board exactly as you left it.

Beside the crumb, 3 of 21 and a pair of arrows walk the issues you were looking at when you opened this one — the board's order, or the list's, filters included. It is how you read a triage list end to end without going back to the board between each one. An issue you opened from a Discord link belongs to no such list, so it shows no counter.

The title and the description are edited in place, and they are no exception to the rule above: they save like everything else does.

The title is the page's heading — no box around it, no pencil beside it. Click into it and type. Enter stores it and drops the caret, leaving the field stores it, and Escape puts the stored one back. Emptying it and leaving brings the stored title back rather than saving a blank one, because an issue with no title is an issue nobody can find again.

The description is the rendered text itself: click in the prose and the caret lands near the line you clicked. It saves after a short pause in typing, when you leave it, on ⌘Enter / Ctrl+Enter, and on Escape — all four commit, so there is no undo key here, only Unsaved changes turning into Saved beside it. If somebody edited the same description elsewhere while you were typing, the save stops and asks which version to keep rather than posting over theirs. It takes up to 4,000 characters and is written in Markdown.

The properties, down the side:

The time log is under the properties: the total logged so far, an entry per stretch of work with who logged it and on which day, and Start timer for counting it as you go rather than remembering afterwards. All of it is in estimates, time and teams.

GitHub, on a server that has connected one, adds a banner naming the pull requests attached to the issue and what state each one is in. Most of them attach themselves, from the identifier somebody wrote in the pull request.

Sub-issues link two issues of the same project, and are nothing more than that: a child names its parent at the top, with an × to detach it, a parent lists its children underneath the properties, and one click on either gets you to the other. Closing a parent does not close its children, and deleting a parent does not delete them — they simply stop having one. Use it for "this is part of that", not as a second board.

A parent's list of children carries a progress bar and a completed of total count. A child counts towards it once it is closed — in a completed or a cancelled column, the same meaning the word has everywhere else here. It is the number that makes a parent worth having: 3 of 7 says more about "release the new site" than the parent's own state ever will.

Children are made two ways. Add sub-issue on the parent types a title inline and files the child straight away, in the project's first column. On an issue that already exists, convert to sub-issue picks the parent instead — which is what you want when something you filed in a hurry turns out to be part of something bigger. The picker never offers the issue itself, its own parent or one of its children: each of those would be a loop.

The trail, at the bottom, is the comments and the activity merged into one chronological list, because they are one story: assigned to Ana — "on it" — moved to In Progress only reads correctly interleaved. Activity entries keep the words they were written with, so an entry naming a state or a label stays readable long after that state or label has been deleted.

The comment box is under the trail. A comment is up to 4,000 characters, written in Markdown, and mirrored into the issue's Discord thread when it has one. Where a thread exists, a link to it sits at the top of the page.

The person who wrote a comment can edit it, and an edited comment says so next to its date — the point of the marker being that a thread where an answer can change under you silently is a thread nobody trusts. Deleting one is the author's right too, and a member with Moderate can delete anyone's.

Anyone reading the issue can react to a comment, from a fixed set of eight — 👍 👎 😄 🎉 😕 ❤️ 🚀 👀. Clicking one adds yours and grows the count, and clicking it again takes yours away. Eight rather than every emoji there is, because a reaction is meant to be read at a glance — and because a thumbs-up on "shipped it" saves the comment that says nothing but "ok", which is most of what a tracker's comments are otherwise made of.

Relations

A relation is a line drawn between two issues that have something to do with each other without one being part of the other. This cannot start until that is done, these two are the same bug, read this one alongside that one. Sub-issues answer "is part of"; relations answer everything else.

The Relations block sits on the issue's page, under the properties. Add relation picks the kind, then finds the other issue by identifier or by title. Say you are reading WEB-12 and you pick WEB-19:

A relation is always written on both issues, which is the last column. Add it on WEB-12 and WEB-19 carries its half from that second, without anybody opening it; remove it from either side and it goes from both. There is no such thing as a one-sided relation somebody forgot to mirror, which is the reason to have the feature at all rather than a sentence in a description.

Relations can cross projects, as long as both issues are on the same server: the website cannot ship until the moderation queue is emptied is a real dependency and a sub-issue could not express it, since sub-issues stay inside one project. An issue cannot relate to itself, the same pair cannot be added twice, and an issue may carry 25 relations.

The block lists what blocks this issue first and the trivia last, and an issue with something still in its way says so in a banner above its description — that one fact is the reason the feature exists, and it is no use three scrolls down.

Nothing is enforced. Blocks does not stop you moving, closing or working on the blocked issue, and no DM is sent when a blocker closes. It is a note two issues carry about each other, for the people reading them — a tracker that refuses to let you finish something because a year-old issue still says it is blocking is a tracker people work around.

Markdown, mentions and checkboxes

Issue descriptions and comments are written in one box that shows the formatting as you type it: bold is bold, a heading is a heading, a checkbox is a checkbox and a mention is a chip with the member's name. Eight buttons sit over it — bold, italic, strikethrough, code, a link, a quote, a bullet list and a task list — and each one toggles: press it again on the same text and the formatting comes off. Markdown shortcuts work as you type them, so **bold** goes bold the moment you close it and - starts a list.

What is stored is still Markdown — the exact text Discord reads — so a description written here, a description typed into the Discord modal and one pushed from GitHub are the same kind of string. The Source button, next to the toolbar, swaps the box for that raw text whenever you want to see it or edit a character by hand; the choice is remembered in your browser. One thing is deliberately missing from the formatted box: tables cannot be built there, because Discord has none. A table already in a description is left exactly as it is, and Source is where to edit it.

Enter starts a new paragraph and Shift+Enter breaks the line without one — and a single line break is a single line break everywhere this text goes, here and in Discord. Images are not rendered, and neither is HTML: a <b> typed into a description reads as the four characters you typed. What is rendered is cleaned first, so a description can only ever carry text and formatting — never anything that behaves.

Checkboxes are clickable. A task list in a description is a real checklist: tick a box and the description is saved with the box ticked, for everybody. It is the right size of tool for the five things an issue needs doing in order, where five sub-issues would be five cards nobody wants on the board.

Mentions turn an id into a name. Paste a mention out of Discord — the <@123456789> you get by copying one — and it renders as a chip carrying that member's display name, so the sentence reads ask @Ana about the copy rather than a row of digits. It also sends them a single DM pointing at the issue. It does not assign them the issue and does not make them follow it: assigning is the assignee property, and following — and the limits on mention DMs — are explained under notifications.

A mention or a checkbox written inside code is left exactly as typed — somebody showing how the syntax works is not mentioning anybody.

A comment mirrored into the issue's Discord thread is sent as you wrote it, and Discord renders the parts of Markdown it knows — bold, italics, lists, code — while the rest, checkboxes included, reads there as the plain text it is.

The address of an issue

Every issue has an address of its own:

/dashboard/123/tasks/WEB-12
           │     │    │
           │     │    └─ the issue's identifier
           │     └───── the tasks page
           └─────────── your server's id

That is the page a card opens, and it is the only place an issue is read: the properties, the sub-issues, the relations, the trail and the comment box, with room to read them in.

That is what the address is for. Pasted into a Discord message, a commit or a document, it lands the reader on the issue itself rather than on a board they then have to search. The link is also one keypress away: copy link in the command palette.

It is still a dashboard page, so it needs View the tracker: somebody who cannot open the tracker cannot read the issue there, and the card in Discord is what they have. A member let in by a tracker role alone sees the tracker and nothing else of your server's dashboard. An identifier that names nothing — a deleted issue, a typo, a project whose key was renamed — gets a plain "no such issue" page rather than an empty board.

Creating an issue

Three ways in, all ending at the same place:

• The + on a board column, which opens a one-line composer at the top of it: type a title, press enter, and the issue is filed in that column. A create that fails keeps what you typed.
• C on the keyboard, which is the same composer, opened at the top of the first column.
• /task create in Discord — see the Discord side.

Only the title is required. Everything else can be set now or later, on the issue's page, from the card, or with /task.

A project that has reached its issue cap refuses the create and names the cap; see the limits. Closed issues count towards it, so a very old project reaches its ceiling by being long-lived rather than busy — archive it and start the next one, or move up a tier.

Templates

A template is an issue filled in ahead of time. A server that files the same shape of thing over and over — a bug report that always wants the same three headings, a weekly stream checklist, an application to review — makes it once and starts from it afterwards: New from template, on the filter bar, offers the templates the project can use. A template that already carries a title is a complete issue and is filed the moment you pick it; one that does not opens the column composer with the rest of it filled in, leaving you to type the title and change whatever else is different this time.

A template is made from an issue that already got it right: Save as template on that issue captures what it holds — title, description, state, priority, estimate and labels, plus an assignee, a due date or a cycle if it had them — under a name of up to 60 characters. Templates are then edited in Settings, where the editor owns the first six and shows the rest as chips you can take off, and a server may keep 30.

Each template is either tied to one project or offered to all of them. A column belongs to one project's workflow, so making a template global drops the column it had captured — the form says so as you switch — and an issue made from it lands in whichever column is first, like any other new issue.

Starting from a template copies it; it does not attach the issue to anything. Editing a template later changes what the next issue starts from and leaves the issues already made exactly as they are.

Archiving an issue

Archive is how an issue leaves without being destroyed. The archived issue drops off the board, out of the list, out of every filter and every saved view; it keeps its identifier, its description, its comments, its activity trail and its place in whatever relations and sub-issue links it had, and restoring it puts all of that back.

Two ways to it: the button on a list row, which appears as you hover it, and Archive in the command palette. The list is therefore where a board gets its spring clean — one row after another, without leaving the page.

To find one again, turn on Show archived in the filter bar. Archived issues come back into view drawn apart from the rest — dimmed, with an Archived badge — and where every other row offers an archive button, they offer Restore, because the reason to go looking in an archive is nearly always to undo it.

Three things that sound alike and are not:

An issue does not have to be closed before it is archived, and archiving is not a second way of closing: a duplicate you archive was never done. When you are unsure which of the three you want, it is archiving — it is the only one of the three you can take back.

What archiving does not do is make room: the project still holds the issue, so it still counts towards the project's issue cap, exactly as a closed one does.

Keeping the two halves in step

Anything you do on the dashboard repaints the Discord card, and anything done from Discord — a button, a /task command — shows on the dashboard when you next open it. The card is only a view of the issue: deleting it by hand loses nothing, and the next change to the issue posts a fresh card in its place. An issue whose card could not be posted at all — no default channel, or a missing permission — is a perfectly normal issue that happens to live only here.

Next: projects, states and labels.