-
Notifications
You must be signed in to change notification settings - Fork 19
Writing Issues
Issues fall in to one of three categories:
The most common type of issue will likely be the user story. User stories describe the needs of a user persona for our project. User stories should be written in the following form:
_As a_ {{user persona}} _I want_ {{need}} _so that_ {{rationale}}Replace {{user persona}} with the name of the persona the need is for, {{need}} with the need, and {{rationale}} with the reason the persona has that need. Titles of User Stories should be in the form of {{user persona}}: {{need}} with the body including the full user story as above.
User stories also need their requirements for being considered complete written out in addition to their user story. To do so, features and scenarios should be written to describe the expected behavior in Gherkin syntax. The following template can be used for writing a Gherkin behavior (copy the whole thing):
```gherkin
Feature:
As a
I want
So that
Scenario:
Given
When
Then
```
User stories should have a task list created with each feature/scenario pair from the Gherkin behaviors as tasks in order to track progress on each behavior.
A User Story is considered done when all feature/scenario pairs defined in the issue have been completed with passing tests for said functionality.
Team stories represent work that does not directly provide value to the end user. This can be design thinking activities, like To-be scenarios or hills workshops, or generative research. This could also include site/product infrastructure tasks.
Other than the user being a team member, the only distinction between this and a user story is the label team story.
A Team Story is considered done when all feature/scenario pairs defined in the issue have been completed. Where tests make sense, tests should be written (and pass) for each feature/scenario pair.
Bug reports represent a problem in one of our environments. If the problem exists because something isn't working as it was designed and implemented to work, it should be filed as a bug report. If the problem exists because something isn't working as expected or working as liked but is working as it was designed and implemented to work, it should be filed as a user story.
Titles of bug reports should be in the form of Issue: {{short description}} with {{short description}} being a very short (5-10 word) description of the issue. Bug reports should all include the following information:
- Long description of issue
- Step-by-step instructions on how to reproduce the issue
- Screenshots and if possible animated GIFs (ideally at least one for every step)
- Browsers, browser versions, operating systems, and operating system versions affected
- Environments affected
A Bug Report is considered done when the described issue no longer manifests itself in the described browsers/versions and environments, as well as having passing tests written for the bug.
An epic is a collection of user stories and team stories that together track a larger desired outcome change for one or many user personas. Epics should be constructed identically to user stories, with the exception that instead of Gherkin behaviors and Gherkin driven task lists, the task lists should be the titles of tracked user stories with links to said user stories.
An Epic is considered done when all linked stories have been closed.
Any issue filed that does not follow the structure of a User Story, Bug Report, or Epic is considered a stub and needs to be rewritten to align with one of those issue types.
Working on Punchcard
Org Maintenance
Architecture Planning
These architectural discussions may be out-of-date given the current state of Punchcard.