Improve and clarify the use of milestones in GitLab leveraging best practices for software develpment
Accepted milestone definition
In the software development / project management world, Milestone
is a term which refers to a specific point in time (date) within the project development flow where progress is measured and compared against the project plans.
For example, common milestones for many projects are:
- Project start date
- Project end date
- Any key deliverables to the customer (documents, reports, analysis)
Milestones are not fluid and do not move unless mutually agreed by all involved parties. It is expected that a project is measured against its milestones - whether hit or missed. Given that milestones are defined as a specific event, tasks are not assigned to milestones, but instead assigned to deliveries, epics, or sprints which should be scheduled to satisfy the defined milestones.
Problem
Here at GitLab, we utilize the term milestone to denote a release. This makes sense from the accepted definition of milestone. The release will ship on the 22nd of the month regardless of whether individual features are complete or not.
However, we're confusing ourselves and our customers by assigning issues to milestones. What this implies to many is that there is a dependent relationship between the issues assigned to the milestone and the milestone itself, which is not true since we will ship the release whether or not all assigned work is complete. It is for this reason that deliveries have fallen out of favor as milestones. Instead, maturity is being more commonly referred to as the milestone. For example, feature X reaches Lovable would be a great example of a milestone.
We're also making it very difficult for product management to schedule work to a specific release as we currently have no mechanism to do something such like assign the design portion of an issue to be worked during a specific timeframe.
This confusion around milestone usage manifests itself in the following problems that we're now facing:
- We're confusing our customers by assigning work to a milestone as the terminology is confusing and for many represents a firm commitment / dependency.
- We're not allowing our product management team to schedule work for a delivery effectively.
Possible solutions
In general, we need to decide if we want to influence the definition of the industry terminology Milestone
. If not, then we need to understand why we allow issues / epics to be assigned to milestones and whether or not this is in the best interest of our product.
With the emerging feature of iterations, we are providing ourselves a way to schedule work during a timeframe, so the milestone property no longer needs to be used for this mechanism.
Option One
One option is to lean into the emerging iteration functionality for scheduling portions of an issue (or stages in the product development flow) and then update our documentation to state that a milestone is a target. This has the benefit of being a very MVC change, but doesn't really solve the problem of the confusion around milestone terminology since many users may not understand / read our modified definition.
Option Two
The second (and more disruptive option) is to rename the milestone property to targeted release
. We could then implement true milestones at the product planning level (such as maturity level milestones) in the future. While this option seems more aligned with industry terminology, it fails to solve for the problem of assigning work to happen during a specific timeframe.
Next Steps
Further discussion is needed at the Product Development Flow working group level, as well as at the general team levels.