CEN 5016 · SDE Project

Issues & project boards, step by step

From a user story
to merged work.

How to write stories, turn them into real issues, break them into sub-issues, link them, and move them across the board.

Draft storyUser Stories column. As a / I want / so that.
→
Real issueConverted, numbered, all 10 fields.
→
Sub-issuesTechnical pieces with owners and hours.
→
Branch + PRCloses #42, reviewed.
→
DoneMerged. The card moves itself.
  1. We'll walk one example all the way through: a PDF export feature for a documents app.
  2. Five stops. Every stop has fields that need to be filled in, and we will see each one.
Step 1Set up the board
UCF-CEN-5016 / your-team-repoCodeIssuesPull requestsProjects BoardTableRoadmap
User Storiesdrafts

Ideas written as user stories. Draft items are fine here.

Backlogissues

Real repo issues you plan to build.

To-Do

Picked for the current sprint.

In Progress

Someone owns it and has a branch open.

Done

The PR is merged.

Need another stage?

Add one, such as In Review between In Progress and Done. Keep the five required columns in this order.

Slips we saw

  • To-Do placed after Done
  • No To-Do column at all
  • Several boards, only one used
  1. Open your repo, go to Projects, and open your team board in Board view.
  2. Five columns, left to right: User Stories, Backlog, To-Do, In Progress, Done.
  3. Each column means one thing. A card's column should always tell the truth about its state.
  4. Extra columns are fine. The order of the required five is not optional.
  5. Fix the order now by dragging column headers. Delete boards you don't use.
Step 2Write a user story as a draft
Team boardBoard
User Stories3
Draft
As a reviewer, I want to see who viewed a doc, so that I know it was read.
Draft
As an editor, I want to move many docs at once, so that cleanup is fast.
Draft
As a team lead, I want to export a document as PDF, so that I can share it with clients who don't have accounts.
+ Add item
Backlog
To-Do

As a team lead, I want to export a document as PDF, so that I can share it with clients who don't have accounts.

Role: whoFunction: whatValue: why
Draft · User Stories

As a team lead, I want to export a document as PDF, so that I can share it with clients who don't have accounts.

Impact

High. Clients without accounts can't read what we share today. Every team that works with outside people benefits.

Effort

Medium. The server already renders documents as HTML. We add a PDF step, a menu item, and tests.

Why it ranks #1

Highest impact for a moderate effort, and users keep asking for it.

Source

Upstream issue #2817, open for two years with 40+ upvotes.

Assignees
ANana (wrote this story)
  1. Stories start in the User Stories column. Click + Add item at the bottom.
  2. Type one sentence: As a [role], I want [function], so that [value].
  3. Each part has a job. Who it's for, what they can do, and why it matters to them.
  4. Open the draft. The body is where your team's reasoning goes.
  5. Impact: how much this helps the people who use the project.
  6. Effort: roughly how much work it takes, and why you think so.
  7. Why this rank and Source. Real upstream requests make the strongest stories.
  8. Assign the draft to the person who wrote it. That's how authorship is checked. Two stories per teammate.
Step 3Check it: INVEST and the 3 Cs
Weak story
As a user, I want a better dashboard.
Strong story
As a team lead, I want to export a document as PDF, so that I can share it with clients who don't have accounts.
Question to ask
Weak
Strong
I
Independent. Can it be scheduled in any order, without overlapping another story?
✓
✓
N
Negotiable. Does it capture the goal and leave the details for the team?
✓
✓
V
Valuable. Is there a "so that"? Who gains what?
✗
✓
E
Estimable. Could the team guess the hours?
✗
✓
S
Small. At most about two person-weeks of work.
✗
✓
T
Testable. Can you say exactly when it's done?
✗
✓
Card the one-sentence story
Conversation the body and your team's discussion
Confirmation acceptance criteria
  1. Before ranking, check each story. Here's a weak one next to a strong one.
  2. Independent and Negotiable: both pass. Good stories leave room to decide the details.
  3. "A better dashboard" has no value and no way to estimate it. Better for whom? How much work?
  4. It's also not small and not testable. You could never mark it Done. Rewrite or split stories like this.
  5. The 3 Cs: the card is the sentence, the conversation is the body, and the confirmation is the acceptance criteria.
Step 4Rank the stories by impact and effort
Impact →
Effort →
Do first
Split first
Fill-ins
APDF export
BWho viewed
COffline editing
DSidebar color
EBulk move
User Storiestop = highest priority
A · Impact high · Effort medium
As a team lead, I want to export a document as PDF…
B · Impact medium · Effort low
As a reviewer, I want to see who viewed a doc…
C · Impact high · Effort XL
As a field worker, I want to edit offline…
D · Impact low · Effort low · cosmetic
As a user, I want to change the sidebar color…
E · Impact medium · Effort medium
As an editor, I want to move many docs at once…

Write the why

Each body says why the story sits where it does. An empty body hides your reasoning.

Cosmetic only

Story D only changes a color. It can stay on the list, but it can't be your sprint work.
  1. Order in the column is information. The top card is your team's first priority.
  2. Place each story by impact and effort. High impact with moderate effort is the sweet spot.
  3. Then sort the column to match. A, B, E first. C is big: split it before you build it. D sinks.
  4. Put the reasoning in every story body, so anyone can see why the order is what it is.
Step 5Turn the chosen story into a real issue
Team boardBoard
User Stories
Backlog
To-Do
In Progress
Done
Draftyour-team-repo #41⋯
As a team lead, I want to export a document as PDF, so that I can share it…
Export a document as PDF
Draft
As a reviewer, I want to see who viewed a doc…
Draft
As an editor, I want to move many docs at once…
Draft
As a field worker, I want to edit offline…
Convert to issue
Move to column
Archive
Delete

Choose a repository

UCF-CEN-5016/your-team-repo

The draft becomes issue #41 in this repo.

Rename it like a task

Short and action-style. The full story sentence moves into the issue body under User story.

Backlog items must be real issues

Drafts don't exist in your repo. They can't take labels or milestones, and a PR can't close them. You can also create the issue from the Issues tab and add it to the board in the sidebar.
  1. Pick the stories you will build in the sprint. Here, story A: PDF export.
  2. Open the card's ⋯ menu and choose Convert to issue.
  3. Choose your team repository.
  4. Now it's issue #41. It has a number, so it can take labels and a milestone, and PRs can link to it.
  5. Move it to Backlog and retitle it as a task: Export a document as PDF.
  6. Every card in Backlog should show an issue number. If it says Draft, it isn't done yet.
Step 6Fill in every required field Required fields 1/103/105/107/108/109/1010/10
your-team-repoIssuesOpen

Export a document as PDF #41

Summary

Add "Download as PDF" to the document menu, so people without accounts can read shared docs.

User story

As a team lead, I want to export a document as PDF, so that I can share it with clients who don't have accounts.

Rough scope

Large. Touches the documents API, the menu, image and embed rendering, and tests.

Source

Upstream issue #2817 (40+ upvotes). Story A on our board.

Estimated effort

About 36 person-hours across 4 sub-issues.

Dependencies

None for the parent. Sub-issues are linked with "Blocked by".

Acceptance criteria
Given a doc with text, images, and a table, choosing Download as PDF downloads a PDF in under 5 seconds.
Headings, lists, images, and tables look the same as in the app.
A user without read access gets a 403, not a file.
Unit tests and one end-to-end test pass in CI.
Assignees
No one assignedANana
Labels
None yetscope: largetype: feature
Projects
Team board · No statusTeam board · Backlog
Milestone
No milestoneSprint 1 · due Fri Oct 9
Relationships
Sub-issues added next

Use the sidebar, not the body

"Assignee: TBD" or "Milestone: Sprint 1" typed in the body doesn't count. Set the real fields so they show on the board.
  1. Every Backlog issue needs the same 10 fields. Save them as an issue template so nobody forgets one.
  2. Summary: what, why, and who benefits. Then the full user story sentence.
  3. Rough scope (S, M, L, XL) with a one-sentence reason, and the source of the idea.
  4. Estimated effort in hours, and dependencies as issue numbers.
  5. Acceptance criteria as checkboxes. Each one is something you can test.
  6. In the sidebar: an assignee and two labels, one scope: and one type:.
  7. Then the milestone and the board status. That's 10 of 10.
Step 7Create the labels and milestones once
Issues › LabelsNew label
scope: smalla few hours, one person
scope: mediuma day or two of work
scope: largeseveral days, split into sub-issues
scope: xltoo big for one sprint, split it
type: featuresomething new
type: improvementbetter version of something that exists
type: bugsomething broken
Issues › MilestonesNew milestone

Sprint 1

Due Fri Oct 9, 2026 · 3 open · 0 closed

Sprint 2

Due Fri Oct 23, 2026 · Checkpoint 2

On every Backlog issue

One scope: label, one type: label, and one milestone. An issue whose sprint is "1–2" or "3" isn't planned yet.
  1. Labels and milestones are set up once per repo, under the Issues tab.
  2. Four scope labels. If something is XL, that's a signal to split it.
  3. Three type labels: feature, improvement, or bug.
  4. Two milestones, one per sprint, with real due dates. The milestone bar shows progress on its own.
  5. Pick exactly one sprint per issue. You can move it later if plans change.
Step 8Break the feature into sub-issues
#41 Export a document as PDFscope: largetype: feature
Sub-issues 0 of 00 of 10 of 30 of 4 Create sub-issue ▾
#TitleOwnerLabelsEst.
#42Add PDF export endpoint to the documents APIAN anascope: medium feature12 h
#43Add "Download as PDF" to the document menuBE benscope: small feature6 h
#44Render images and embeds in exported PDFsCA camscope: medium feature10 h
#45Add end-to-end test for PDF exportDE deescope: small improvement8 h

Titles name the change

"Add PDF export endpoint", not "As a user, I want…". Every sub-issue still gets all 10 fields and both labels.

Tests travel with code

Unit tests go inside the issue they test. Keep one end-to-end item at the end.

This story: 36 h of the team's ~128 h

0326496128 h

4 people × 8 h/week × 4 weeks. With agents, plan 2 to 4 stories this size.

Spread the work

Each teammate owns at least one sub-issue in Sprint 1. One person holding a whole feature is a risk for them and for the team.
  1. A Large issue is too big to hand to one person. Split it into technical sub-issues.
  2. On the parent issue, click Create sub-issue. First: the backend endpoint.
  3. Then the menu item and the rendering work. Each has one owner and an estimate.
  4. Each sub-issue is about 4 to 16 hours and ends in one PR. The parent shows progress: 0 of 4.
  5. Sub-issues are technical tasks. The user story stays on the parent.
  6. Add up the hours and compare them to your budget. Too little is a problem too: agents make small items fast.
  7. Look at the owner column. Everyone should have their name on Sprint 1 work.
Step 9Link issues that depend on each other
#42
Add PDF export endpoint
AN
#43
Add "Download as PDF" menu item
BE Blocked by #42
#44
Render images and embeds
CA Blocked by #42
#45
End-to-end test for PDF export
DE Blocked by #43, #44
#43 sidebar
Parent issue
#41 Export a document as PDF
Relationships
Mark as blocked by…Blocked by #42 Add PDF export endpoint
Body, Dependencies field
Blocked by #42
✓ Blocked by #42 in the sidebar and the body
✗ "Depends on Task 1"
✗ "After the backend is done"
✗ "Issue 1"
  1. Some sub-issues can't start until another one lands. Make that visible.
  2. The menu item and the rendering both need the endpoint, so they are blocked by #42.
  3. The end-to-end test needs both of those. Now the order of work is obvious.
  4. In each issue's sidebar, use Relationships → Mark as blocked by. Write the same issue number in the Dependencies field.
  5. Always use real issue numbers. "Task 1" or "Issue 1" can't be clicked and goes stale.
Step 10Smaller steps: a checklist inside the issue
#42 Add PDF export endpoint to the documents API0 of 5 tasks2 of 5 tasks5 of 5 tasks
Tasks
Add route GET /api/documents/:id/export?format=pdf
Add PdfExportService that turns the rendered HTML into a PDF
Check read permission first. Return 403 otherwise.
Unit tests for the service and the route
Document the new endpoint in the API docs
- [ ] Add route GET /api/documents/:id/export
- [ ] Unit tests for the service and the route

Make it a sub-issue when…

it needs its own owner, its own PR, or its own estimate, or other work is blocked by it.

Make it a checklist item when…

it's one step that the same person does inside the same PR.

Tip

Ask your coding agent to draft the checklist from the acceptance criteria. Then edit it as a team.

  1. Inside a sub-issue, break the work into steps you can tick off.
  2. Type - [ ] lines in the body. GitHub turns them into checkboxes and counts them.
  3. Tick them as you go. The count shows on the issue and on the board card.
  4. When the last box is ticked, the PR is ready for review.
  5. Rule of thumb: own owner, PR, or estimate means a sub-issue. A step inside one PR is a checklist item.
Step 11Move the work across the board
Team boardSprint 1
Backlog
To-Do
In Progress
Done
#42 AN
Add PDF export endpoint
#43 BlockedBE
Add "Download as PDF" menu item
#44 BlockedCA
Render images and embeds
#45DE
End-to-end test for PDF export
terminal
$ git switch -c feat/42-pdf-export
Switched to a new branch 'feat/42-pdf-export'
$ git commit -m "feat(api): add PDF export endpoint"
Pull request #51OpenMerged

feat(api): add PDF export endpoint

Adds the export route and service. Unit tests included.

Closes #42

lint passed
unit tests passed
Approved by BE ben
#41 parent: 1 of 4 sub-issues done
  1. Sprint planning: as a team, choose this sprint's issues from Backlog.
  2. Move them to To-Do. They already have owners, estimates, and the Sprint 1 milestone.
  3. Start work: create a branch named after the issue and move the card to In Progress.
  4. Open a PR whose description says Closes #42. That links the PR to the issue.
  5. CI runs and a teammate reviews and approves, as your Definition of Done says.
  6. Merge. Issue #42 closes, the card moves to Done, and the parent shows 1 of 4.
Before Sprint 1Check your board against this list

User Stories column

  • At least two stories per teammate, each assigned to its author
  • As a [role], I want [function], so that [value]
  • Every body has impact, effort, why this rank, and source
  • Column sorted from highest to lowest priority
  • No purely cosmetic stories chosen for the sprint

Backlog and sprint work

  • Real issues, not drafts, with action-style titles
  • All 10 fields filled in every issue
  • One scope: and one type: label each
  • Assignee and milestone set in the sidebar
  • Large work split into sub-issues of 4 to 16 hours, owned by everyone
  • Dependencies as Blocked by #N
  • Each PR says Closes #N and is approved before merge
  1. Here is the whole checklist. Start with the stories.
  2. Then the backlog. Fix these before Sprint 1 and your board will tell the truth all semester.

→ / Space next · ← back · P autoplay · F full screen