### Problem to solve - When a milestone ends, issues are typically moved to the next milestone. Burndown charts on the previous milestone then don't accurately reflect what was completed on that given milestone. We add a `missed xx.xx` label to all issues as a current workaround. - If issues are added to a milestone once it begins, that represents "scope creep" and there is no way to surface this on a milestone level. - By not storing the amount of missed issues in a given milestone, teams don't have effective feedback to help them set better expectations for the next milestone. ### Intended users <!-- Who will use this feature? If known, include any of the following: types of users (e.g. Developer), personas, or specific company roles (e.g. Release Manager). It's okay to write "Unknown" and fill this field in later. * [Parker (Product Manager)](https://about.gitlab.com/handbook/marketing/product-marketing/roles-personas/#parker-product-manager) * [Delaney (Development Team Lead)](https://about.gitlab.com/handbook/marketing/product-marketing/roles-personas/#delaney-development-team-lead) * [Sasha (Software Developer)](https://about.gitlab.com/handbook/marketing/product-marketing/roles-personas/#sasha-software-developer) * [Presley (Product Designer)](https://about.gitlab.com/handbook/marketing/product-marketing/roles-personas/#presley-product-designer) * [Devon (DevOps Engineer)](https://about.gitlab.com/handbook/marketing/product-marketing/roles-personas/#devon-devops-engineer) * [Sidney (Systems Administrator)](https://about.gitlab.com/handbook/marketing/product-marketing/roles-personas/#sidney-systems-administrator) * [Sam (Security Analyst)](https://about.gitlab.com/handbook/marketing/product-marketing/roles-personas/#sam-security-analyst) * [Dana (Data Analyst)](https://about.gitlab.com/handbook/marketing/product-marketing/roles-personas/#dana-data-analyst) Personas are described at https://about.gitlab.com/handbook/marketing/product-marketing/roles-personas/ --> Primary: * [Parker (Product Manager)](https://about.gitlab.com/handbook/marketing/product-marketing/roles-personas/#parker-product-manager) * [Delaney (Development Team Lead)](https://about.gitlab.com/handbook/marketing/product-marketing/roles-personas/#delaney-development-team-lead) * Scrum masters, Agile coaches, Managers, Directors, Executives Secondary: * [Sasha (Software Developer)](https://about.gitlab.com/handbook/marketing/product-marketing/roles-personas/#sasha-software-developer) * [Presley (Product Designer)](https://about.gitlab.com/handbook/marketing/product-marketing/roles-personas/#presley-product-designer) * [Devon (DevOps Engineer)](https://about.gitlab.com/handbook/marketing/product-marketing/roles-personas/#devon-devops-engineer) * [Sidney (Systems Administrator)](https://about.gitlab.com/handbook/marketing/product-marketing/roles-personas/#sidney-systems-administrator) * [Sam (Security Analyst)](https://about.gitlab.com/handbook/marketing/product-marketing/roles-personas/#sam-security-analyst) * [Dana (Data Analyst)](https://about.gitlab.com/handbook/marketing/product-marketing/roles-personas/#dana-data-analyst) ### Further details <!-- Include use cases, benefits, and/or goals (contributes to our vision?) --> - This is one of the important steps towards our goal of providing better first class support for modern "agile" methodologies. - Not having this is currently a deal breaker for a lot of customers switching their project management functionality over to GitLab as there is currently no way to easily to see the difference between original commitment and the actual outcome of a milestone. ### Proposal <!-- How are we going to solve the problem? Try to include the user journey! https://about.gitlab.com/handbook/journeys/#user-journey --> - Include a second chart on the milestone view for `burnup`, which tracks two lines throughout a milestone - `scope` and `completed`. The scope line is variable depending on the amount of scope added or removed to a milestone once it begins. - Completed tracks the number of issues `closed` during the given milestone. - Include the total count of issues (and weight) added/removed from a given milestone. - The scope line is time series like data where it is simply the count of issues in a milestone at a given point in time. Count should be immutable once it is recorded.  Follow on iterations: - See the epic: https://gitlab.com/groups/gitlab-org/-/epics/1957 **Important Consideration:** - This is also happening (https://gitlab.com/gitlab-org/gitlab/issues/19445) so the designs should be based on the current Project Milestone view (Example: https://gitlab.com/gitlab-org/gitlab/-/milestones/30). Once we have this issue and that issue completed, we will revisit the content and overall design of the milestone view. - In the coming releases, we will also be working towards segmenting data on milestones by teams/groups so that each team has meaningful insights into their contribution towards a company level milestone. This will include calculating additional derived data such as [velocity and volatility](https://gitlab.com/groups/gitlab-org/-/epics/435) as well as providing burndown/burnup charts scoped to [teams](https://gitlab.com/gitlab-org/gitlab/issues/30611) and/or [issue boards](https://gitlab.com/gitlab-org/gitlab/issues/6864). ### Permissions and Security <!-- What permissions are required to perform the described actions? Are they consistent with the existing permissions as documented for users, groups, and projects as appropriate? Is the proposed behavior consistent between the UI, API, and other access methods (e.g. email replies)?--> - This presents no suggested deviations from our current security and permissions model. ### Documentation <!-- See the Feature Change Documentation Workflow https://docs.gitlab.com/ee/development/documentation/feature-change-workflow.html Add all known Documentation Requirements here, per https://docs.gitlab.com/ee/development/documentation/feature-change-workflow.html#documentation-requirements If this feature requires changing permissions, this document https://docs.gitlab.com/ee/user/permissions.html must be updated accordingly. --> - We will want to add documentation around the additional data points now available on Milestones. ### Testing <!-- What risks does this change pose? How might it affect the quality of the product? What additional test coverage or changes to tests will be needed? Will it require cross-browser testing? See the test engineering process for further help: https://about.gitlab.com/handbook/engineering/quality/test-engineering/ --> - We should write acceptance and unit tests for this. ### What does success look like, and how can we measure that? <!-- Define both the success metrics and acceptance criteria. Note that success metrics indicate the desired business outcomes, while acceptance criteria indicate when the solution is working correctly. If there is no way to measure success, link to an issue that will implement a way to measure this. --> #### Success Metrics - Quantitative: - Milestones and the burndown chart load in two seconds or less. - Qualitative: - We make significant progress converting some customers over to using GitLab's Issue Tracking capabilities. #### Acceptance Criteria - [ ] The behavior in the proposal is working. - [ ] Necessary tests added. - [ ] Uses GraphQL first. - [ ] Necessary updates to public GraphQL and REST APIs. - [ ] Documentation added. - [ ] Pajamas first. If major changes are required for the graph, consider contributing to the unified dashboard project. - [ ] Milestones load faster than did before making this change. ### What is the type of buyer? <!-- Which leads to: in which enterprise tier should this feature go? See https://about.gitlab.com/handbook/product/pricing/#four-tiers --> - The problems this issue would solve and the corresponding additional data added to a milestone is not something an individual contributor would necessarily care about. According to our [pricing strategy](https://about.gitlab.com/handbook/product/pricing/#four-tiers) the likely buyer is Manager and above, so this would fall within the ~"GitLab Starter" tier. ### Links / references - Directly related open issues are linked below the description. ### Pre-Build Task List - [x] ~UX / ~"workflow::solution validation" completed - [x] ~backend implementation spiked and documented (please consider using a checklist in the description and/or adding a description of the suggested implementation approach) - [x] ~"needs weight" resolved - [x] Prioritize and schedule Original Description: <details> - Display distribution of issues `dropped`, `moved`, `closed`, `added`, and `missed` grouped by the `X` axis date. - `dropped` - The issue was removed from the current milestone and not immediately associated to another milestone within a certain period from the time the current milestone was removed. - `moved` - The issue is open and the milestone changed to a different milestone than the one it was currently associated to BEFORE the end of the milestone. - `closed` - The issue was closed while still associated to the milestone. - `added` - The issue was added a day or more after the start date. This is to account for teams that may do planning on the same day they start a milestone. - `missed` - The issue is open and not closed/completed before the end of the milestone. It may be moved after the milestone is done, but it would only be marked as missed. Somewhere else: - Display a report of total counts of each event over the duration of the milestone period. (i.e. `dropped`, `moved`, ...) - It might also be nice to consider displaying a list of the issue corresponding to each event, but this could also get noisy. ### Background - [Burndown charts](https://docs.gitlab.com/ee/user/project/milestones/burndown_charts.html) as currently implemented, are largely stateless. - We will introduce a little more state to account for issues added to a milestone in the middle of a milestone. See https://gitlab.com/gitlab-org/gitlab-ee/issues/6174. - But even with that change, burndown charts are mainly stateless. In particular, when you remove an issue from a particular milestone, the burndown chart treats that issue as if it was never part of it. - We plan to introduce [burndown charts into boards](https://gitlab.com/gitlab-org/gitlab-ee/issues/6864). This will allow the scoping of issues to be flexible/customizable based on the board scope/configuration. So instead of bringing scoping to the milestone page (where the burndown chart currently exists), the idea is to bring the burndown chart to the board, which already has a scoping. ### Problems - Burndown charts currently do not capture state. In particular: - If in the past, an issue was part of a milestone, but then subsequently removed that milestone, our current implementation doesn't account for it. - If in the past, an issue had a certain label, but then subsequently that label was removed, even our burndown chart in board feature (https://gitlab.com/gitlab-org/gitlab-ee/issues/6864), will not account for it. - This problem above is not a major problem currently. We have not received any requests (per my knowledge) to have those more accurate burndowns. My suspicion is that teams typically use burndowns during a milestone as the issue counts/weights are burning down. After the iteration is over, they do not care and even if the issue is moved to another milestone, that is okay. - However, what is a real problem for GitLabbers right now, is the ability to track missed deliverable rates. We have some ongoing work to do this outside of the product. See https://gitlab.com/gitlab-org/gitlab-ce/issues/49201. But eventually we want to solve this inside GitLab. If the burndown chart can account for historical state, then perhaps it can be used to address that particular problem. ### Proposed solution - Long-term (we might never need the long-term solution), we entirely use events (https://gitlab.com/groups/gitlab-org/-/epics/224, https://gitlab.com/groups/gitlab-org/-/epics/48) to build historically accurate burndown charts. - In particular, this will solve tracking missed deliverables for GitLabbers. You would look at a burndown chart, and be able to see (given a particular scoping of labels and other attributes), how many issues that were open at the beginning of the milestone, and how many were closed at the end of the milestone. So you can capture the missed deliverable rates immediately from there. - In the first iteration, we only use milestone events for historically accurate milestones. This will probably be enough for GitLabbers to track missed deliverables rate, since our team/product area labels are unlikely to change significantly for issues. - In the second iteration (which we might not need), we consider label events, and make that accurate. - In iterations after that (again, which we might not need), we consider weight events, assignee events, etc. </details> #### Solution We are moving forward for now with adding a BurnUp chart to the Milestone view. Users will be able to filter by issues and weights on the two charts at once but they will be viewed side by side as separate metrics. Ideally, they should be side by side in a horizontal row until they reach a min size of 500px. At that point they should stack vertically. https://gitlab.com/gitlab-org/gitlab/uploads/9b77c01d96649b5ee784f248b73233bd/Screen_Shot_2019-10-25_at_2.12.14_PM.png ### Release Notes A Milestone's burndown chart is helpful for tracking progress during the course of an Iteration or Sprint, but it doesn't provide insight into how the scope changed during the course of the timebox nor has it previously retained historical accuracy regarding how much of the scope that was committed to at the start of the Milestone was actually completed. To solve these problems and help teams have better insights into scope creep, Milestones now have a Burnup chart that tracks the daily total count and weight of Issues added to and completed within a given Milestone. Burndown charts have also been refactored to use immutable [resource state events](https://docs.gitlab.com/ee/api/resource_state_events.html#issues) that further enables Milestone charts to be historically accurate [1] even after you've shifted Issues from one Milestone to the next. [1] Only applies to Milestones created in 13.4 or higher.  https://docs.gitlab.com/ee/user/project/milestones/ <!-- triage-serverless v3 PLEASE DO NOT REMOVE THIS SECTION --> *This page may contain information related to upcoming products, features and functionality. It is important to note that the information presented is for informational purposes only, so please do not rely on the information for purchasing or planning purposes. Just like with all projects, the items mentioned on the page are subject to change or delay, and the development, release, and timing of any products, features, or functionality remain at the sole discretion of GitLab Inc.* <!-- triage-serverless v3 PLEASE DO NOT REMOVE THIS SECTION -->