Skip to content

Refresh + simplify the epic template #16652

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 7 commits into from
Mar 21, 2023
Merged

Refresh + simplify the epic template #16652

Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
3f90c1b
Update epic.yml
loujaybee Mar 3, 2023
1f7f8d3
Update .github/ISSUE_TEMPLATE/epic.yml
loujaybee Mar 3, 2023
1805e29
Update .github/ISSUE_TEMPLATE/epic.yml
loujaybee Mar 3, 2023
09bfcd2
Update .github/ISSUE_TEMPLATE/epic.yml
loujaybee Mar 3, 2023
2b3c538
Update .github/ISSUE_TEMPLATE/epic.yml
loujaybee Mar 3, 2023
2d033d2
Update .github/ISSUE_TEMPLATE/epic.yml
loujaybee Mar 3, 2023
255c2f2
Update .github/ISSUE_TEMPLATE/epic.yml
loujaybee Mar 3, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
69 changes: 17 additions & 52 deletions .github/ISSUE_TEMPLATE/epic.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,104 +1,69 @@
name: Epic
description: Create an epic
name: Epic (User Impacting)
description: A group of related issues which MUST be delivered together, as small in scope as possible and finite (e.g not a grouping). This template is not designed for investigations, spikes, or tech-debt.
title: "Epic: "
labels: ["type: epic"]
body:
- type: markdown
attributes:
value: Before raising an epic, please search for existing epics[[1](https://github.com/gitpod-io/gitpod/issues?q=is%3Aopen+is%3Aissue+label%3A%22type%3A+epic%22)][[2](https://github.com/gitpod-io/gitpod/issues?q=is%3Aopen+is%3Aissue+%22Epic%3A+%22)] to avoid creating duplicates. Read more about [Epics](https://www.notion.so/gitpod/Development-Process-2-0-6681854173ab4d2f92880f9f3d85cab5#321619f5a4bd4391be83c66feb2cdb49) (internal) in **Development Process**.
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I believe this "don't duplicate" can be implied, I'm not sure it adds much value, only select Gitpodders are really creating or concerned with epics. Also, I think we should remove the template from the RFC, and have this template as the single source of truth, making a link back redundant.

- type: textarea
id: summary
id: press-release
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Removed summary, pulled the press release field up top. @laushinka mentioned we could rename, however I would suggest to keep for now, since it's part of the (well documented) PRFAQ framework, so by keeping the name it makes it more clear that it's aligned with that philosophy. As with all other fields, is now optional, though.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

suggestion: A better alternative could be Release Notes. However, this would require us to be more intentional with this field and how we use it. Let's give it a go.

attributes:
label: Summary
description: TLDR description of the epic. Give a succinct and plain overview of what the epic is about.
placeholder: Give a succinct and plain overview of what the epic is about.
label: Press release (and FAQ's)
description: What would the future feature announcement look like from a customer/user point of view? Think about questions both Gitpodders, and users/customers might ask about this feature.
validations:
required: true
required: false
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

suggestion: Since we're making this optional it could be nice to stress this is optional in the description above since not every epic will have a press release or announcement bit.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

not every epic will have a press release or announcement

Good point. It could be "If this feature would have an announcement, what would it look like from ..."
I think this Press Release section aims to encourage epic authors to explain the value of the feature to everyone regardless of technical background.

- type: textarea
id: context
attributes:
label: Context
description: What thinking led to this? Provide any necessary historical context required to understand this epic.
placeholder: Provide any necessary historical context required to understand this epic.
description: What thinking led to this issue? Provide any necessary historical context required to understand this epic.
validations:
required: true
required: false
- type: textarea
id: value
attributes:
label: Value
description: Why should we do it? How do we know this is a real problem and worth solving?
placeholder: Explicitly describe the value to Gitpod and/or our users. I.e. why answer should we undertake this epic?
description: Why should we do this work? How do we know this is a real problem and worth solving?
validations:
required: true
required: false
- type: textarea
id: acceptance-criteria
attributes:
label: Acceptance Criteria
description: What needs to be done before the work is considered complete? The checks which must be complete for this epic to be considered done.
placeholder: Defines clearly when the work is complete. Acts as a litmus test for "done" and avoids "done" being ambiguous. Useful for implicit assumptions, e.g. ensuring docs updates are not forgotten.
validations:
required: true
required: false
- type: textarea
id: measurement
attributes:
label: Measurement
description: How will we know whether we've been successful / solved the problem? How will you measure the success of the epic? Ideally this metric is one of our key product metrics.
placeholder: Important as it's how we track the outcomes (not just output) of the work and prove a change was worth it. Or it should be removed or iterated.
validations:
required: true
- type: textarea
id: growth-area
attributes:
label: Growth Area
description: Which aspect of Gitpod do we expect improvements in? Acquisition/Onboarding/Exploration/Expansion as defined in [Funnel Proposal](https://www.notion.so/gitpod/Funnel-Proposal-d7d0dba8aced4184b660092a74f8dd3a) (internal)
placeholder: Growth is key. This allows us to frame epics from a growth context. Which areas are we expecting this epic to help us with our growth initiatives?
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Whilst I believe to be valuable, I don't think the growth area model is well understood in Gitpod right now, I suggest removing, and consider re-adding in future.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

thought: Good point—something to consider improving collectively. 💭

description: What will we measure to know whether we've been successful?
validations:
required: false
- type: textarea
id: personas
attributes:
label: Persona(s)
description: Who will be impacted by this change? Which of our personas will be impacted by this change?
placeholder: Why? To bring persona's into our work. Persona's can help us prioritise our markets. Currently, we are not focusing on the education/training persona currently. We should avoid epics which target this persona.
validations:
required: false
- type: textarea
id: hypothesis
attributes:
label: Hypothesis
description: If we do X, we expect Y
placeholder: Can be useful if the work is explicitly experimental.
description: Optionally specifiy which user will be impacted by this change?
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

thought: Removing this is also a sign of low maturity level on how we use personas during our product development flow. It would be nice if instead we could reuse and reinforce some past reference work regarding personas, see relevant section in the handbook. 📙

placeholder: Developer/Installer/Project Configurer/Customer/Security Reviewer - optionally the ecosystem persona e.g. Python Developers
validations:
required: false
- type: textarea
id: in-scope
attributes:
label: In scope
description: Explicitly define the items in scope.
placeholder: Optional, sometimes is useful for explicitness.
description: Optionally define items explicitly in scope.
validations:
required: false
- type: textarea
id: out-of-scope
attributes:
label: Out of scope
description: Explicitly define the items out of scope.
placeholder: Optional, sometimes is useful for explicitness.
description: Optionally define items explicitly out of scope, to avoid side-quests and rabbitholes.
validations:
required: false
- type: textarea
id: complexities
attributes:
label: Complexities
description: Discuss any known complexities
placeholder: Optional, sometimes is useful for explicitness.
validations:
required: false
- type: textarea
id: press-release
attributes:
label: Press release
description: Create excitement about the idea
placeholder: Useful if you want to spend the extra time to get stakeholders, the team, or customers excited.
description: Optionally make explicit any complexities, e.g. dependencies on other teams, technical challenges, unknowns.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

question: Does it help to have the optionally prefix in the label? If yes, is it accurate to use a comma or prefix it with parenthesis in all text labels? For example:

// Option :A:
Optionally, make explicit any complexities, e.g. dependencies on other teams, technical challenges, unknowns. 

// Option B:
(Optional) Make explicit any complexities, e.g. dependencies on other teams, technical challenges, unknowns.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Option B looks good - it gives more emphasis to the part in brackets.

validations:
required: false