Skip to main content

Per-project board template

A reusable template for the board the github-project-backlog skill creates at project kickoff. Companion to the Paid Work board, which is the cross-client one.

Why a template at all​

Views cannot be created through the API. There is no gh project view-create, and no public GraphQL mutation for it. gh project can create fields but never views.

So a script can only ever produce a board with one unnamed table view, which is what the skill does today. The only way to get a configured board from a script is:

  1. Build one template project by hand, with the fields and views wanted
  2. gh project mark-template it
  3. Have the skill run gh project copy instead of gh project create

Copying carries fields and views across. That's the whole reason this page exists.

The trap: two boards don't share field values​

An issue can sit on both this board and Paid Work. Custom field values are per-project, so they do not sync. Setting Status to In progress here does nothing to the same issue on Paid Work, and card order is independent too.

That's not a bug to work around, it's a reason to give each board a job and not overlap them.

BoardOwnsQuestion it answers
Paid WorkStatus, Priority, Up nextWhat am I doing today, across everything
Per-projectPhase, Target date, epicsWhat's in this project, and when does it land

Rule: Paid Work is the truth for status. The per-project board is for scoping at kickoff and for showing a client where things are. If Status gets set on both, they will drift, and the global one wins.

Status is a built-in field so it can't be removed from the project board. Ignore it there rather than fighting it.

Fields​

FieldTypeWhy
PrioritySingle select: High, Medium, LowMatches Paid Work, so the same word means the same thing on both
Target dateDateDrives the roadmap view
PhaseSingle select: Discovery, Build, Launch, AftercareWhere in delivery this sits

Milestones are native to the repo and already show up as a field, so no custom field for them.

Deliberately not included:

FieldWhy not
Size, EstimateI don't estimate, so they'd sit empty
IterationI don't run iterations. It came free with GitHub's template, which isn't a reason to keep it
Start dateOnly useful with a Gantt-style plan, which this isn't

GitHub's built-in template ships all four of those. They're the same trap as the eight-field version of Paid Work: fields nobody fills in stop meaning anything, and then the board stops being trusted.

Views​

ViewLayoutShowsFor
BoardBoard, by StatusEverything openDay-to-day working view
BacklogTableEverything open, sorted Priority then Target dateDeciding what's next in this project
By phaseTable, grouped by PhaseEverything openWhat's left before this ships
RoadmapRoadmap, by Target dateEverything with a dateShowing a client when things land
Waiting on clientTableStatus is Waiting on clientThe chase list for this client
Recently doneTableStatus Done, sorted newestWriting an update, and invoicing

Dropped from GitHub's defaults:

  • My items — everything is mine, so it's the same as Backlog
  • Current iteration — no iterations to be current in

Roadmap and Recently done are the two that earn their keep here rather than on Paid Work. A client wants a timeline and a "what did you do this month", and neither question is cross-client.

Building it​

  1. Create a project called Project template, set up the fields and views above by hand
  2. gh project mark-template <number> --owner nathan-roberts
  3. Change create_github_backlog.py so ensure_project() runs gh project copy <template> --source-owner nathan-roberts --target-owner nathan-roberts --title "<project> backlog" instead of gh project create
  4. Keep the existing gh project link step so the board attaches to the repo

Worth checking after the first copy: whether the copy brings view filters across or only the view names and layouts. If filters don't survive, they're a one-off manual fix per project and the template is still worth having.