High Level Planning Process
This document describes how to work with the Quarkus high-level planning process. The process is focused around GitHub issues modelled as Epics and tracked on this GitHub project: https://github.com/orgs/quarkusio/projects/5.
An Epic should be used for a requirement that is large/significant, needs external visibility and/or requires the focus of the team. An Epic is also typically composable from several smaller tasks. Some of which might result in released code changes, prior to the completion of the overall Epic.
A regular issue, on the other hand, can represent a piece of work that is important enough to spend time on, yet does not need the level of visibility or tracking that an Epic does. These are the small things that still get done but fit around the bigger tasks (Epics).
This criteria is rather subjective and may not be exactly consistent between people. However, the result should be that the Epics form the basis of the high-level plan providing a clearer view free of the clutter from the (more numerous) small issues.
Here you can see all the Epics, and where they are in the process from backlog to completion. Also notice that many in-progress Epics have a progress bar showing how many sub-tasks are complete.
Epics are created similarly to regular issues. However, they have some extra requirements that assist with visibility and planning:
-
Visit https://github.com/quarkusio/quarkus/issues/new/choose
-
Select the "Epic" issue type.
-
Fill out the description based on the template. At this point you might not have an analysis docs or subtasks to add. This is OK, they can come later.
-
Notice that the 'Epic' label is already set (leave it).
-
Add the Epic to the Roadmap project, by clicking on the 'projects' item in the right-hand side-bar and selecting the roadmap project. See:
Each Epic has a lead/assignee. The Epic lead is the person who is organising the work. It’s not necessarily the person doing the bulk of it. It provides a point of contact when an update is needed. It also ensures a single person is responsible for fleshing out the tasks in the Epic, driving it forward and generally being an advocate for the work
In particular you also need to doing the following with the Epic:
-
Ensure the description reflects the work to be done
-
Provide links to any design/analysis documents or any other supporting content that is related to the work.
-
Populate the task list and keep it updated with the status of the work. Typically the task list will consist of a checklist of links (with description) to other issues. When those issues are completed the checkbox needs manually checking. This ensures that the progress of the Epic is kept up-to-date.
For example:
GitHub will use the checklist to display the overall progress of the Epic on the project board(s). See:
As the assignee of the Epic you need to do two things to report on the progress of the Epic:
When an item in the checklist is completed, you need to tick the associated box in the checklist. You do this by clicking on the box when viewing the Epic (no need to edit). Unfortunately, this does not happen automatically when the linked issue is closed.
See the Planning project here: https://github.com/orgs/quarkusio/projects/5
As the work progresses you will also need to ensure the Epic proceeds through the stages on the project board. The Stages are defined as follows:
-
Backlog. This is for work that is not in progress or planned for the next few releases. In general this work should not be started without checking with @emmanuelbernard or @n1hility first.
-
Planned. This work is not in progress, but is planned to be delivered in one of the upcoming releases. Work in this column should typically have an assignee and they should be thinking about how they plan it into their upcoming workload.
-
In Progress. The actual work has begun. The issue must now have an assignee and should have the task-list defined (although maybe not complete, especially for more exploratory work).
-
In Review. All the tasks are complete and the Epic is ready for a final review.
-
Done. The Epic was completed and will be part of the upcoming release.
-
Done 1.x. The Epic is completed and was released as part of the stated release.
There will be times when the initial plan for the Epic is rather optimistic and contains a few nice-to-have items in the checklist. When the important items are done, it could be considered "good enough" to call the Epic done. What happens to the outstanding work?
In this situation the 'anti pattern' would be to move the Epic back to the backlog "as is", and schedule it for completion later when the remainder of the work is needed. The problem with this approach is that Epics can become everlasting themes of work (E.g "Security Improvements") rather than self-contained pieces of work. There is also no log of the completed work in the 'Done' column meaning it could get missed when publicising the big features of the new release.
The correct approach is to remove the incomplete work from the Epic’s check-list. At this point the description/title of the Epic may need updating to reflect the reduced scope. For example, "Implement Spec ABC" may become "Implement MVP of Spec ABC" to indicate that this work has now become a Minimal Viable Product, rather than the full 'thing'. The outstanding issues might go onto a follow-up Epic scheduled for a later release. For example, "Implement full compliance for spec ABC". Alternatively the outstanding issues might be small and unrelated and no longer warrant being part of an Epic.