Code Dungeon · The User Guide

Chapter IV

Quests: issues, pull requests and QA

Work in the dungeon is GitHub issues. An issue goes from the backlog to a coder, becomes a pull request, is tested in the assay room and is merged. You can watch every step on the chamber's notice board, and step in at any of them.

Where issues come from

  • Your project briefs: write what a chamber should build next in the ledger (DungeonMaster & recruits tab), and the DungeonMaster turns it into issues.
  • The Issues tab of the ledger, or the notice board, where you can file one yourself.
  • Anything already open on GitHub for that repo.

An issue that says Depends on #N waits until #N is closed. Of the rest, the ones holding up the most other work go first, then the oldest.

The notice board

Press E on the board at the far end of a chamber. Its columns:

  • Backlog: open issues nobody has picked up. Assign one to a coder from here.
  • In progress: coders at work.
  • In QA: pull requests being tested, or being fixed after a failed test. Pull requests that people opened (not coders) show here as not tested yet, with a Send to QA button.
  • Ready to merge: QA passed, waiting for you or for auto-merge.
  • Merged: done.

With auto-assign on for a chamber (in the ledger), free coders take the next issue by themselves. With it off, you hand out issues from the board or from a coder's terminal.

Pull requests

A coder works on a branch called swarm/issue-<n>-<name> and opens a pull request that says Closes #<n>. Coders never push to the default branch and never merge: the dungeon merges, after QA.

QA in the assay room

A free tester checks out the pull request, reads it and its issue, reviews the diff, runs the tests, linters and build, and tries the change in a real browser with screenshots. The dungeon posts the report on the pull request as a comment: the verdict, a table of checks, the commands run and the screenshots.

If QA fails, the report goes back to the coder who wrote it. They fix the branch and it goes back to QA. After three failed rounds the pull request is marked needs you.

Merging

With auto-merge on (the default), a pull request merges itself once QA has passed its latest commit and GitHub's checks are green. If checks fail or it conflicts with the default branch, a coder fixes it and QA tests it again. With auto-merge off, read the pull request and its QA comment on GitHub, then press Merge on the notice board. Merging something that hasn't passed QA asks you to confirm first.