Add documentation

app/assets/stylesheets/pages/milestone.scss

@@ -247,6 +247,11 @@
   }
 }
 
+.burndown_docs_link {
+  color: inherit;
+  text-decoration: underline;
+}
+
 .burndown-header {
   margin: 24px 0 12px;
 

app/models/burndown.rb

@@ -55,7 +55,7 @@ class Burndown
 
     closed =
       issues_with_closed_at.select do |issue|
-        (issue.closed_at&.to_date || @start_date) == current_date
+        (issue.closed_at&.to_date || start_date) == current_date
       end
 
     reopened = closed.select { |issue| issue.state == 'reopened' }

app/views/shared/milestones/_burndown.html.haml

@@ -10,7 +10,7 @@
 - unless burndown.accurate?
   #no-data-warning.settings-message.prepend-top-20
     Some issues can't be shown in the burndown chart, as they were closed before GitLab 9.1 update.
-    = link_to "More information.", help_page_path('workflow/milestones')
+    = link_to "More information.", help_page_path('workflow/milestones'), class: 'burndown_docs_link'
 
 - if can_generate_chart
   .burndown-header

changelogs/unreleased-ee/issue_2151.yml

 ---
-title: Set closed and reopened issues without closed_at to milestone start date
+title: Add warning when burndown data is not accurate
 merge_request:
 author:

doc/analytics/README.md

 # Analytics
 
 - [Contribution Analytics](contribution_analytics.md)
+- (EE) [Burndown](../workflow/milestones.md#burndown-ee-only) 

doc/workflow/milestones.md

@@ -26,3 +26,15 @@ special options available when filtering by milestone:
 * **Started** - show issues or merge requests from any milestone with a start
   date less than today. Note that this can return results from several
   milestones in the same project.
+
+## Burndown (EE-Only)
+
+A burndown chart is available for every project milestone that has a set start date and a set due date. It is located on the project milestone page. It indicates project progress throughout that milestone (for issues that have that milestone assigned to it). In particular, it shows how many issues were or are still open for a given day in the milestone period. Since GitLab only tracks when an issue was last closed (and not its full history) the chart assumes that issue was open on days prior to that date. Reopened issues are considered as open on one day after it was closed. The burndown chart can also be toggled to display the cumulative open issue weight for a given day. When using this feature, make sure your weights have been properly assigned, since an open issue with no weight adds zero to the cumulative value.
+
+![burndown chart](milestones/burndown_chart.png)
+
+Closed or reopened issues prior to GitLab 9.1 version won't have a `closed_at` value, so burndown considers it as closed on the milestone `start_date`. In that case a warning will be displayed.
+
+![burndown chart warning](milestones/burndown_warning.png)
+
+

spec/factories/issues.rb

@@ -10,6 +10,7 @@ FactoryGirl.define do
 
     trait :closed do
       state :closed
+      closed_at Time.now
     end
 
     trait :reopened do

spec/features/milestones/show_spec.rb

@@ -25,14 +25,12 @@ describe 'Milestone show', feature: true do
   end
 
   context 'burndown' do
-    before { issue_params.delete(:labels) }
+    let(:issue_params) { { project: project, assignee: user, author: user, milestone: milestone } }
 
     context 'when closed issues does not have closed_at value' do
       it 'shows warning' do
         create(:issue, issue_params)
-        issue = create(:issue, issue_params)
-        issue.update(state: 'closed')
-        issue.update(closed_at: nil)
+        create(:closed_issue, issue_params.merge(closed_at: nil))
 
         visit_milestone
 
@@ -43,8 +41,7 @@ describe 'Milestone show', feature: true do
     context 'data is accurate' do
       it 'does not show warning' do
         create(:issue, issue_params)
-        issue = create(:issue, issue_params)
-        issue.close
+        create(:closed_issue, issue_params)
 
         visit_milestone
 

spec/models/burndown_spec.rb

@@ -57,16 +57,18 @@ describe Burndown, models: true do
     expect(JSON.parse(subject).last[0]).to eq(Time.now.strftime("%Y-%m-%d"))
   end
 
-  it "it sets attribute has_data to true" do
+  it "sets attribute accurate to true" do
     burndown = described_class.new(milestone)
 
     expect(burndown.accurate?).to be_truthy
   end
 
   context "when closed and reopened issues does not have closed_at" do
-    before { milestone.issues.update_all(closed_at: nil) }
+    before do
+      milestone.issues.update_all(closed_at: nil)
+    end
 
-    it "it considers closed_at as milestone start date" do
+    it "considers closed_at as milestone start date" do
       expect(subject).to eq([
         ["2017-03-01", 15, 30],
         ["2017-03-02", 27, 54],
@@ -76,7 +78,7 @@ describe Burndown, models: true do
       ].to_json)
     end
 
-    it "it sets attribute has_data to false" do
+    it "setsattribute accurate to false" do
       burndown = described_class.new(milestone)
 
       expect(burndown.accurate?).to be_falsy