Merge branch '196066-add-milestone-expired-info-be-3' into 'master'

Add include_parent_group_milestones to milestones API endpoints

See merge request gitlab-org/gitlab!38800

changelogs/unreleased/196066-add-milestone-expired-info-be.yml

+---
+title: Add include_parent_milestones param to project and group milestones API endpoints
+merge_request: 38800
+author:
+type: added

doc/api/group_milestones.md

@@ -27,13 +27,14 @@ GET /groups/:id/milestones?search=version
 
 Parameters:
 
-| Attribute | Type   | Required | Description |
-| --------- | ------ | -------- | ----------- |
-| `id`      | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) owned by the authenticated user |
-| `iids[]`  | integer array | no | Return only the milestones having the given `iid` |
-| `state`   | string | no | Return only `active` or `closed` milestones |
-| `title`   | string | no | Return only the milestones having the given `title` |
-| `search`  | string | no | Return only milestones with a title or description matching the provided string |
+| Attribute                   | Type   | Required | Description |
+| ---------                   | ------ | -------- | ----------- |
+| `id`                        | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) owned by the authenticated user |
+| `iids[]`                    | integer array | no | Return only the milestones having the given `iid` (Note: ignored if `include_parent_milestones` is set as `true`) |
+| `state`                     | string | no | Return only `active` or `closed` milestones |
+| `title`                     | string | no | Return only the milestones having the given `title` |
+| `search`                    | string | no | Return only milestones with a title or description matching the provided string |
+| `include_parent_milestones` | boolean | optional | Include milestones from parent group and its ancestors. Introduced in [GitLab 13.4](https://gitlab.com/gitlab-org/gitlab/-/issues/196066) |
 
 ```shell
 curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/5/milestones"

doc/api/milestones.md

@@ -25,13 +25,14 @@ GET /projects/:id/milestones?search=version
 
 Parameters:
 
-| Attribute | Type   | Required | Description |
-| --------- | ------ | -------- | ----------- |
-| `id`      | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user |
-| `iids[]`  | integer array | optional | Return only the milestones having the given `iid` |
-| `state`   | string | optional | Return only `active` or `closed` milestones |
-| `title`   | string | optional | Return only the milestones having the given `title` |
-| `search`  | string | optional | Return only milestones with a title or description matching the provided string |
+| Attribute                         | Type   | Required | Description |
+| ----------------------------      | ------ | -------- | ----------- |
+| `id`                              | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user |
+| `iids[]`                          | integer array | optional | Return only the milestones having the given `iid` (Note: ignored if `include_parent_milestones` is set as `true`) |
+| `state`                           | string | optional | Return only `active` or `closed` milestones |
+| `title`                           | string | optional | Return only the milestones having the given `title` |
+| `search`                          | string | optional | Return only milestones with a title or description matching the provided string |
+| `include_parent_milestones`       | boolean | optional | Include group milestones from parent group and its ancestors. Introduced in [GitLab 13.4](https://gitlab.com/gitlab-org/gitlab/-/issues/196066) |
 
 ```shell
 curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/milestones"

lib/api/milestone_responses.rb

@@ -14,10 +14,12 @@ module API
 
         params :list_params do
           optional :state, type: String, values: %w[active closed all], default: 'all',
-                           desc: 'Return "active", "closed", or "all" milestones'
+                         desc: 'Return "active", "closed", or "all" milestones'
           optional :iids, type: Array[Integer], coerce_with: ::API::Validations::Types::CommaSeparatedToIntegerArray.coerce, desc: 'The IIDs of the milestones'
           optional :title, type: String, desc: 'The title of the milestones'
           optional :search, type: String, desc: 'The search criteria for the title or description of the milestone'
+          optional :include_parent_milestones, type: Grape::API::Boolean, default: false,
+                    desc: 'Include group milestones from parent and its ancestors'
           use :pagination
         end
 
@@ -25,15 +27,18 @@ module API
           requires :milestone_id, type: Integer, desc: 'The milestone ID number'
           optional :title, type: String, desc: 'The title of the milestone'
           optional :state_event, type: String, values: %w[close activate],
-                                 desc: 'The state event of the milestone '
+                               desc: 'The state event of the milestone '
           use :optional_params
           at_least_one_of :title, :description, :start_date, :due_date, :state_event
         end
 
         def list_milestones_for(parent)
-          milestones = parent.milestones.order_id_desc
+          milestones = init_milestones_collection(parent)
           milestones = Milestone.filter_by_state(milestones, params[:state])
-          milestones = filter_by_iid(milestones, params[:iids]) if params[:iids].present?
+          if params[:iids].present? && !params[:include_parent_milestones]
+            milestones = filter_by_iid(milestones, params[:iids])
+          end
+
           milestones = filter_by_title(milestones, params[:title]) if params[:title]
           milestones = filter_by_search(milestones, params[:search]) if params[:search]
 
@@ -96,6 +101,41 @@ module API
             [MergeRequestsFinder, Entities::MergeRequestBasic]
           end
         end
+
+        def init_milestones_collection(parent)
+          milestones = if params[:include_parent_milestones].present?
+                         parent_and_ancestors_milestones(parent)
+                       else
+                         parent.milestones
+                       end
+
+          milestones.order_id_desc
+        end
+
+        def parent_and_ancestors_milestones(parent)
+          project_id, group_ids = if parent.is_a?(Project)
+                                    [parent.id, project_group_ids(parent)]
+                                  else
+                                    [nil, parent_group_ids(parent)]
+                                  end
+
+          Milestone.for_projects_and_groups(project_id, group_ids)
+        end
+
+        def project_group_ids(parent)
+          group = parent.group
+          return unless group.present?
+
+          group.self_and_ancestors.select(:id)
+        end
+
+        def parent_group_ids(group)
+          return unless group.present?
+
+          group.self_and_ancestors
+            .public_or_visible_to_user(current_user)
+            .select(:id)
+        end
       end
     end
   end

spec/requests/api/group_milestones_spec.rb

@@ -3,15 +3,65 @@
 require 'spec_helper'
 
 RSpec.describe API::GroupMilestones do
-  let(:user) { create(:user) }
-  let(:group) { create(:group, :private) }
-  let(:project) { create(:project, namespace: group) }
-  let!(:group_member) { create(:group_member, group: group, user: user) }
-  let!(:closed_milestone) { create(:closed_milestone, group: group, title: 'version1', description: 'closed milestone') }
-  let!(:milestone) { create(:milestone, group: group, title: 'version2', description: 'open milestone') }
-
-  it_behaves_like 'group and project milestones', "/groups/:id/milestones" do
-    let(:route) { "/groups/#{group.id}/milestones" }
+  let_it_be(:user) { create(:user) }
+  let_it_be(:group) { create(:group, :private) }
+  let_it_be(:project) { create(:project, namespace: group) }
+  let_it_be(:group_member) { create(:group_member, group: group, user: user) }
+  let_it_be(:closed_milestone) { create(:closed_milestone, group: group, title: 'version1', description: 'closed milestone') }
+  let_it_be(:milestone) { create(:milestone, group: group, title: 'version2', description: 'open milestone') }
+  let(:route) { "/groups/#{group.id}/milestones" }
+
+  it_behaves_like 'group and project milestones', "/groups/:id/milestones"
+
+  describe 'GET /groups/:id/milestones' do
+    context 'when include_parent_milestones is true' do
+      let_it_be(:ancestor_group) { create(:group, :private) }
+      let_it_be(:ancestor_group_milestone) { create(:milestone, group: ancestor_group) }
+      let_it_be(:params) { { include_parent_milestones: true } }
+
+      before_all do
+        group.update(parent: ancestor_group)
+      end
+
+      shared_examples 'listing all milestones' do
+        it 'returns correct list of milestones' do
+          get api(route, user), params: params
+
+          expect(response).to have_gitlab_http_status(:ok)
+          expect(json_response.size).to eq(milestones.size)
+          expect(json_response.map { |entry| entry["id"] }).to eq(milestones.map(&:id))
+        end
+      end
+
+      context 'when user has access to ancestor groups' do
+        let(:milestones) { [ancestor_group_milestone, milestone, closed_milestone] }
+
+        before do
+          ancestor_group.add_guest(user)
+          group.add_guest(user)
+        end
+
+        it_behaves_like 'listing all milestones'
+
+        context 'when iids param is present' do
+          let_it_be(:params) { { include_parent_milestones: true, iids: [milestone.iid] } }
+
+          it_behaves_like 'listing all milestones'
+        end
+      end
+
+      context 'when user has no access to ancestor groups' do
+        let(:user) { create(:user) }
+
+        before do
+          group.add_guest(user)
+        end
+
+        it_behaves_like 'listing all milestones' do
+          let(:milestones) { [milestone, closed_milestone] }
+        end
+      end
+    end
   end
 
   def setup_for_group

spec/requests/api/project_milestones_spec.rb

@@ -3,17 +3,68 @@
 require 'spec_helper'
 
 RSpec.describe API::ProjectMilestones do
-  let(:user) { create(:user) }
-  let!(:project) { create(:project, namespace: user.namespace ) }
-  let!(:closed_milestone) { create(:closed_milestone, project: project, title: 'version1', description: 'closed milestone') }
-  let!(:milestone) { create(:milestone, project: project, title: 'version2', description: 'open milestone') }
+  let_it_be(:user) { create(:user) }
+  let_it_be(:project) { create(:project, namespace: user.namespace ) }
+  let_it_be(:closed_milestone) { create(:closed_milestone, project: project, title: 'version1', description: 'closed milestone') }
+  let_it_be(:milestone) { create(:milestone, project: project, title: 'version2', description: 'open milestone') }
+  let_it_be(:route) { "/projects/#{project.id}/milestones" }
 
   before do
     project.add_developer(user)
   end
 
-  it_behaves_like 'group and project milestones', "/projects/:id/milestones" do
-    let(:route) { "/projects/#{project.id}/milestones" }
+  it_behaves_like 'group and project milestones', "/projects/:id/milestones"
+
+  describe 'GET /projects/:id/milestones' do
+    context 'when include_parent_milestones is true' do
+      let_it_be(:ancestor_group) { create(:group, :private) }
+      let_it_be(:group) { create(:group, :private, parent: ancestor_group) }
+      let_it_be(:ancestor_group_milestone) { create(:milestone, group: ancestor_group) }
+      let_it_be(:group_milestone) { create(:milestone, group: group) }
+      let(:params) { { include_parent_milestones: true } }
+
+      shared_examples 'listing all milestones' do
+        it 'returns correct list of milestones' do
+          get api(route, user), params: params
+
+          expect(response).to have_gitlab_http_status(:ok)
+          expect(json_response.size).to eq(milestones.size)
+          expect(json_response.map { |entry| entry["id"] }).to eq(milestones.map(&:id))
+        end
+      end
+
+      context 'when project parent is a namespace' do
+        it_behaves_like 'listing all milestones' do
+          let(:milestones) { [milestone, closed_milestone] }
+        end
+      end
+
+      context 'when project parent is a group' do
+        let(:milestones) { [group_milestone, ancestor_group_milestone, milestone, closed_milestone] }
+
+        before_all do
+          project.update(namespace: group)
+        end
+
+        it_behaves_like 'listing all milestones'
+
+        context 'when iids param is present' do
+          let(:params) { { include_parent_milestones: true, iids: [group_milestone.iid] } }
+
+          it_behaves_like 'listing all milestones'
+        end
+
+        context 'when user is not a member of the private project' do
+          let(:external_user) { create(:user) }
+
+          it 'returns a 404 error' do
+            get api(route, external_user), params: params
+
+            expect(response).to have_gitlab_http_status(:not_found)
+          end
+        end
+      end
+    end
   end
 
   describe 'DELETE /projects/:id/milestones/:milestone_id' do