Versions & releases
What it is
A version is a batch of changes collected and shipped together, like 0.5.0.
In QU, a version is "a set of tasks + a separate copy of the code that collects their changes":
- Tasks belong to a version. Once accepted, they're first merged into that version's own copy of the code (called the version branch), not mixed into the official code (main) early.
- Each piece of work comes with a one-line changelog entry when it's handed in (one in Chinese, one in English). The versions page collects them into the version's changelog draft automatically.
- Say "ship 0.5.0", and QU merges the version into main, creates a release task, and hands it to a computer that can ship releases.
When to use it
- Things that have to be packaged and released, like apps: collect a version, then ship it. Use versions.
- Things that go live as soon as they're changed, like websites and backends: no need to collect anything; each piece goes live once accepted. Just keep "Ships as soon as it's merged" on under "Project settings › Rules" (it's on by default if you've never set it).
How to use it
The versions page
Below "Task board" in the left sidebar is a "Versions" row, showing how many tasks the earliest version still has left. Click in, and each version not yet shipped has its own column:
- A one-line status at the top: "3 to go", "Done · waiting to ship";
- A progress bar: done / accepted, waiting to merge / waiting for your acceptance / in progress / not started;
- All the tasks that belong to it, each with a one-line status;
- The version's changelog draft.
On the far right are the versions already shipped. Open one to see which tasks it had and the changelog it shipped with.
"Version ▾" on the board shows only one version's tasks.
Creating a version and putting tasks in it
- Click "New version" on the versions page; the version number is the last one plus one. Or tell Q "create version 0.5.0".
- A task belongs to one version only: pick it in the "Version" row of the task details, or use "Add tasks" on the versions page. Subtasks go with their parent task.
- Which version a task belongs to is only up to you; the system never moves it by itself.
We suggest opening a separate topic for each version and talking about everything for that version in it. See Best practices.
Version branches
A version branch is the separate copy of the code that collects this version's changes.
- To open one, on the versions page open this version's "⋯ → Open a version branch". Or, once accepted work piles up, Q asks in "Needs you": "Open a version branch for 0.5.0?", and you click to open it.
- Once it's open, this version's tasks are merged into the version branch after they're accepted. As soon as one step is handed in, the work waiting on it can carry on, without being held up by your acceptance.
- Several versions at once don't get mixed up: work for a later version that's accepted first is marked "Accepted · waiting to merge", and is merged into main once the earlier version ships.
- It picks up wherever the work is done, on any computer.
Changelog drafts
- When a session hands in its work, it writes one line for users, one in Chinese and one in English.
- Lines are sorted into "New / Improved / Fixed" by task type.
- If a session forgot to write one, Q fills one in, marked in yellow: "filled in by Q, take a look".
- Each line shows whether the session wrote it, Q filled it in, or you changed it. You can copy and edit them on the versions page.
- Things users won't notice, like docs, walkthroughs and research, aren't included.
Shipping
- When everything is done, the versions page says it's ready to ship.
- Tell Q "ship 0.5.0". QU first merges the version branch into main. Once that works, it creates a release task and hands it out automatically, with the version's changelog draft.
- You can also click "Ship 0.5.0" on the versions page. That only creates the release task; it starts once you hand it out.
- Release tasks only go to a computer with "Can sign releases" ticked (tick it in each computer's menu on the "Computers" page). If none can take it, it isn't handed out, and you're asked in "Needs you".
- When it's shipped, click "Released" to wrap up; this can be undone. Any tasks not yet done can be moved to the next version in one click.
Before shipping, the board, the task details and the versions page all show how far the merge into main has got. You can also ask Q "how far has this version's merge got?"
To merge into main without shipping yet, pick "Merge into mainline only" in "⋯".
Safety nets when merging
- Before work is handed in, QU tries merging it first. If it doesn't fit, the session sorts it out on the spot. See Prototypes & acceptance.
- If merging a version back into main hits a conflict and the original session is gone, QU opens another session to sort it out, so shipping isn't held up waiting for someone.
- If another session or a deploy is using the project folder, the merge waits in line and goes ahead once it's free.
- When several computers change the same repo and someone else pushed to the remote first, it pulls and merges again. Conflicts go back to the session. It never force-pushes (it never overwrites other people's work with its own).
- Once all of a version's tasks are done and merged, their task branches on the remote are cleaned up automatically.
FAQ
Does it ship automatically once everything is accepted? No. It only starts when you say to ship. For Q to ship for you, Q has to quote the sentence you typed yourself.
Which computer ships releases? The one with "Can sign releases" ticked. A computer whose keychain has a Developer ID certificate gets it ticked automatically the first time it connects; after that, only what you tick counts.
Do website projects need versions too? No. With "Ships as soon as it's merged" on, each piece is live once it's accepted and merged into main.
Can I work on two versions at once? Yes. Each gets its own version branch, and the later one is merged into main after the earlier one ships. If both change the same part of the code, they can still clash. See Best practices.