Projects, states and labels

The three things you set up once. A project holds the issues, its states are the columns they move through, and labels are the tags they carry. Editing any of them needs the Manage projects permission — held by Manage Server, the Manager and Admin presets, or any role or member row that ticks it (see who can do what).

Projects

A project is a body of work with a name and a short key. One server, one project is a perfectly good setup: use a second one when the work is genuinely separate — different people, different rhythm, nothing in common but the server — rather than as a category. A label or a state is the right tool for splitting work that the same people do together.

New project at the bottom of the project switcher opens the form, and the Edit action next to a project in the same switcher reopens it:

Saving creates the project and its six default columns in one go, so it is usable straight away.

The last three are the project's own answer to how big is this, and they are explained — including what happens to the issues already estimated when you change your mind — in estimates, time and teams.

Choosing a key

The key is read aloud and typed by hand — in a Discord message, in a commit, in a meeting. Short and obvious beats descriptive: WEB, MOD, ART, OPS. It is the only part of a project that other things quote, which is why it has rules the name does not.

Renaming a key

You can change a key later, and the form lets you, but read this first: the identifier of every issue in the project is its key plus its number, composed fresh each time it is shown. Rename WEB to SITE and WEB-12 becomes SITE-12 everywhere at once — on the board, on the cards, in /task.

Nothing breaks in the module. What breaks is everything outside it: a WEB-12 written in a Discord message last month, in a commit, in a document, no longer resolves, and /task view reference:WEB-12 answers that there is no such issue. Rename a key while a project is young, or not at all.

Archiving and deleting

Both live at the foot of the project's own form, next to the fields they act on rather than behind a menu somewhere else.

Archiving puts a project away: it drops out of the switcher unless you ask for the archived ones, it stops counting against your plan's project limit, and it keeps its key, so every identifier it ever handed out still resolves. Un-archiving is one click, and nothing inside the project is changed either way. This is how a finished project makes room for the next one.

Deleting removes the project and, with it, its issues, their comments, their activity and their states. The cards already posted in Discord stay where they are as ordinary messages nobody can press the buttons of. There is no undo, and the key becomes free again — so a future project could take it and start its own WEB-1. Archive unless you genuinely want the work gone.

Either one done to a parent project leaves its sub-projects where they are: archiving a parent touches none of its children, and deleting one lifts them to the top level, whole. See what happens to the children.

Sub-projects

A project can sit under another one. The website has its blog, its shop and its docs; each is work of its own, with its own people and its own rhythm, and each is still the website. A sub-project is that: a project like any other — its own key, its own issues, its own columns, its own cycles — that happens to have a parent.

The parent is an ordinary project too. It holds issues of its own, and it is not a folder: nothing forces you to file everything under a child. Pick the parent in the Parent project field of the form, when you create a project or later in Edit, and clear it to lift the project back to the top level.

Two levels, no more. A parent cannot have a parent of its own, and a project that already has children cannot be made somebody's child; the form refuses both rather than letting a tree grow that the switcher could not draw. Three levels of the website / the shop / checkout is what a label is for.

What a sub-project keeps, and what it does not:

• Its key. SHOP-4 stays SHOP-4. Nothing about its identifiers mentions the parent, and moving a project under one — or out again — rewrites nothing.
• Its own states and cycles. The columns are per project, so a child's board is its own board, and its sprints are its own sprints. A parent's cycle does not reach into its children.
• Its own slot. A sub-project counts against the plan's project limit exactly like a top-level one. Nesting is how the switcher reads, not a way round the cap.

The project switcher draws the tree: a parent, and its children indented under it. Picking a child shows that child and nothing else, as before.

Picking the parent shows the parent's own issues — and its filter bar gains Include sub-projects, which widens the board to the whole family. Because states belong to each project, a board holding three projects cannot be laid out by column, so with the switch on the board is grouped by project: one lane per project, the parent first, each card carrying its own project's state. A cycle belongs to one project too, so grouping by cycle falls back the same way, bands by state or cycle are dropped, and the state filter steps aside while the family is on. Every other grouping, the rest of the filters and the list work as usual across the family; creating an issue still files it into the project you are on.

The three built-in views — My issues, Created by me, Subscribed — answer for all projects, parents and children alike, since what is mine is not a question about one project. Lighting one puts an All projects chip beside the switcher, lit with it: press the chip to narrow the view back to the project you are on, and again to widen it. Each row carries its own identifier, so a wide answer never leaves you wondering which project a card came from. See the three you already have.

What happens to the children

• Archiving a parent archives the parent only. Its children stay active, stay in the switcher and keep working; the archived parent shows under Show archived with them still attached, and un-archiving it puts the tree back as it was.
• Deleting a parent removes the parent and its own issues, as deleting any project does — and lifts its children to the top level, untouched: their issues, states, cycles and keys are exactly as they were, they simply stop having a parent.

Neither ever deletes a child. A sub-project goes away only when somebody deletes that sub-project.

The workflow

A project's states are the columns of its board, in the order you put them. Settings lists them for the project you are on — each row with its name, its colour, its type, its optional WIP limit and a pair of arrows that move it left or right on the board.

Every new project starts with six:

Rename them, recolour them, reorder them, add your own and delete the ones you do not use. What a type means, and why two columns can share one, is in the overview.

Things worth knowing:

• The first column is the default. An issue created without a state — from /task create, or from a template that captured none — lands in whatever is leftmost. Put the column you file into first.
• A name is yours, a type is FlaviBot's. Call a column Shipped, Live or Merged; give it the completed type and FlaviBot will close the issues that reach it, count them in a cycle's progress and hide them behind Show closed.
• Twelve columns is the ceiling, and it is generous: past a screenful, a board stops being readable.
• Reordering is the arrows on a row, not a drag: the cards are the thing you drag, and a second drag surface in a settings list earns nothing. It moves the column for everybody and touches none of the issues in it.
• A column holding issues cannot be deleted. The row says how many are in it and offers the way out — move these 7 issues to … — and only then unlocks the delete. An issue has to be in some column, and silently dropping seven of them into another one is not a decision a dialog should make on its own.
• The last column cannot be deleted either. A project with no column could not hold an issue at all.
• A column can be named as a destination elsewhere. A column chosen as where a merged pull request lands its issues simply stops being one when it is deleted — the repository's setting falls back to moving nothing, and nothing else changes.
• A colour is not decoration. It is the column's header on the board and the stripe down the issue's card in Discord, which is how somebody scrolling a channel sees at a glance what is in progress and what is done.

WIP limits

A column can carry a WIP limit — work in progress — which is a number saying how much belongs in it at one time. In Progress, at most three. The column header then reads the count against the limit, and warns once it is over.

It is worth setting on exactly one column: the one where work actually happens. A team with eight things started and none finished is a team that will finish none of them, and a limit is how that becomes visible to everybody rather than being a feeling somebody has on a Friday. When the column is full, the next thing to do is to finish something in it.

FlaviBot warns and never refuses: an issue can always be dragged into a full column, and nothing is blocked or rolled back. Leave the limit empty on the columns where a number would mean nothing — a backlog is supposed to be long. How the header reads is in views and shortcuts.

Labels

Labels are the tags on an issue: bug, design, good first issue, waiting on Discord. Each has a name of up to 32 characters and a colour, and they are edited in Settings.

Labels belong to the server, not to a project. bug means the same thing everywhere, and a new project gets the whole set without you re-creating it. Names are unique case-insensitively — Bug and bug are the same label — and a server may define up to 50 of them, with up to 8 on any one issue.

Deleting a label removes it from every issue that carried it. The issues themselves are untouched, and their activity trail keeps the words, so an entry that reads "added label design" stays readable after design is gone.

Use a label for a property that cuts across projects and states — who is blocked, what kind of work it is — and a state for where the work has got to. A label named Done is a sign the board should have had a column instead.

Next: cycles.