Improve issues organization with sub-issues convention
Problem to solve
Issue boards are hard to follow for the different stakeholders participating in iteration planning, scheduling, and processing.
So we need to improve the readability of our issues boards so that:
- PMs get a better view of what's planned and achieved (effectively shipping) in the milestone.
- EMs get a better view of milestone's scheduled workload (as a team and per individual) and ongoing progress.
- Engineers are able to focus on their respective tasks when an issue involves multiple functions (Frontend, Backend) but still able to have a good grasp of what's necessary to complete the work and reach that issue's goal.
This should be achieved with as less overhead as possible in issues management.
Intended users
PMs, EMs, Engineers
Proposal
Based on several discussions, previous usages of separate issues, and the upcoming transition to CD we should:
- Formalize the organization of work with a Main Issue and Sub-issues.
- Experiment this workflow to Secure::Software Composition Analysis group for
12.1
milestone and12.2
. - Get feedback from all stakeholders.
- Share this experiment with other teams.
- Put this proposal into the handbook as soon as it gets reorganized with new departments and groups pages.
Convention
1. Main issue
- The main issue gets prioritized by PM and labeled with usual labels.
- The main issue holds public-facing communication (planning, kickoff, overall status updates) and main discussions about the goal to achieve (feature behavior, bug details, etc.).
- The main issue must have no weight (sub-issues will have them).
- The main issue's description must contain an implementation plan, which is a numbered checkbox list of high-level tasks.
- The main issue's assignees list must contain all people working on the issue (don't unassign yourself after creating your sub-issues) to quickly identify them.
For scheduling and other engineering organization, EM and Engineers may find necessary to create sub-issues for some or all of the main issue's high-level tasks. E.g. when a feature involves both ~backend
and ~frontend
, we need to split respective tasks into sub-issues so that we can set distinct assignees and weights. Another good opportunity to split is when a feature involves completely decoupled tasks (but still mandatory for achieving the main goal) that can be worked on simultaneously by different persons, even from the same engineering team.
To also align with our goal to ship continuously on a weekly basis, any implementation issue weighing more than a week should be broken down into sub-issues (Discovery and Research are excluded).
2. Sub-issues
- All sub-issues must use the same prefix for their title, preferably a meaningful shortened version of the main issue's title if it's too long. This is a visual helper to quickly identify sub-issues and their main issue.
- Each sub-issue must have proper labels:
- the
~sub-issue
label - the same type label as the main issue
- the same release scoping label as the main issue
- the same priority label and severity label as the main issue
- the relevant specialization label to that particular sub-issue
-
sub-issues must NOT have the
~direction
,~customer
,~customer+
labels and generally any label that provides similar qualification. Rationale: Sub-issues are implementation details, we don't want to clutter other issues lists/boards leveraging these labels.
- the
- Each sub-issue must have its own weight.
- Each sub-issue must have its own implementation plan, which is a numbered checkbox list of low-level tasks. Tasks must be marked as completed by Engineers as the corresponding Merge Request(s) are merged to reflect progress. It is not required to have a perfect matching of one MR per task.
3. Example
This could end up in the following organization:
-
Dependency List MVC -
~feature
~direction
~backend
~frontend
~UX
-
Dependency List MVC - Extract dependency list from project -
~feature
~sub-issue
~backend
~Deliverable
- weight: 3 -
Dependency List MVC - Internal API endpoint -
~feature
~sub-issue
~backend
~Deliverable
- weight: 2 -
Dependency List MVC - View and components -
~feature
~sub-issue
~frontend
~Deliverable
- weight: 3
-
Dependency List MVC - Extract dependency list from project -
4. Guidelines
There is no hard rule about how the split into sub-issues. This must be done on a case by case basis, in a way that best suits the need for achieving the main issue's goal. In doubt, use your best judgment. Some general guidelines:
- if the main issue involves multiple people from distinct teams, we should split with at least one sub-issue per team.
- if the weight of a sub-issue is too important, it's a signal that we should consider splitting into separate sub-issues.
- avoid creating several sub-issues for very small tasks, prefer grouping them in the implementation plan of the same sub-issue as separate checkboxes.
- if work is done (and sub-issue is closed) but we discover a bug or a gap in implementation, no follow-up issue should be created but the corresponding sub-issue should be reopened instead, and a new task added to its implementation plan if necessary. If the main issue was closed, it should be reopened too and PM and EM must be warned. NB: this also aligns with the auto-deploy transition guideline.
5. FAQ
- Why must the sub-issues be also labeled with
~feature
?- Each issue must have at least one type label
- This will be easier to apply
~feature
label automatically to MRs, which is required for throughput measurement.
- Should MRs be linked to sub-issue or main issue or both?
- As we're asking for more smaller MRs, it would make it clearer to link to sub-issue to avoid having a huge number of MRs in the main issue, making it less readable.
- Why not using Epics instead?
- feature-wise, epics are not at par with issues (no assignee, no board, group-level only, etc.)
- Why not using tasks or child-issues?
What does success look like, and how can we measure that?
- Each engineering team can define weight for their own function, making it possible for EMs to measure the velocity of their respective team.
- EMs can easily track the progress of their report's work when several functions are involved in the same feature, reducing the time spent in asking for status reporting.
- with upcoming negative filters, PMs will be able get a readable view of the milestone for their Group, without issues about technical implementation clobbering it. TODO: In the meantime, we could have a chrome extension to remove issues with the
~sub-issue
label. - Engineers can quickly see what are the high-level tasks they are assigned too, but also what's the other stakeholders' tasks for the same feature and how they progress.
- Engineers can break the implementation of big feature down into distinct sub-issues to reduce the scope and the complexity which implies smaller but more numerous Merge Request (increase throughput).