API: List repository commits in order with default

Introduce `default` option to the order parameter improving the API
usage and documentation.

doc/api/commits.md

@@ -18,7 +18,7 @@ GET /projects/:id/repository/commits
 | `all` | boolean | no | Retrieve every commit from the repository |
 | `with_stats` | boolean | no | Stats about each commit will be added to the response |
 | `first_parent` | boolean | no | Follow only the first parent commit upon seeing a merge commit |
-| `order` | string | no | List commits in order. Possible value: [`topo`](https://git-scm.com/docs/git-log#Documentation/git-log.txt---topo-order). |
+| `order` | string | no | List commits in order. Possible values: `default`, [`topo`](https://git-scm.com/docs/git-log#Documentation/git-log.txt---topo-order). Defaults to `default`, the commits are shown in reverse chronological order. |
 
 ```shell
 curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/repository/commits"

lib/api/commits.rb

@@ -38,7 +38,7 @@ module API
         optional :all, type: Boolean, desc: 'Every commit will be returned'
         optional :with_stats, type: Boolean, desc: 'Stats about each commit will be added to the response'
         optional :first_parent, type: Boolean, desc: 'Only include the first parent of merges'
-        optional :order, type: String, desc: 'List commits in order', values: %w[topo]
+        optional :order, type: String, desc: 'List commits in order', default: 'default', values: %w[default topo]
         use :pagination
       end
       get ':id/repository/commits' do

lib/gitlab/gitaly_client/commit_service.rb

@@ -324,7 +324,7 @@ module Gitlab
         request.after    = GitalyClient.timestamp(options[:after]) if options[:after]
         request.before   = GitalyClient.timestamp(options[:before]) if options[:before]
         request.revision = encode_binary(options[:ref]) if options[:ref]
-        request.order = options[:order].upcase if options[:order].present?
+        request.order = options[:order].upcase.sub('DEFAULT', 'NONE') if options[:order].present?
 
         request.paths = encode_repeated(Array(options[:path])) if options[:path].present?
 

spec/lib/gitlab/gitaly_client/commit_service_spec.rb

@@ -281,6 +281,19 @@ describe Gitlab::GitalyClient::CommitService do
   end
 
   describe '#find_commits' do
+    it 'sends an RPC request with NONE when default' do
+      request = Gitaly::FindCommitsRequest.new(
+        repository: repository_message,
+        disable_walk: true,
+        order: 'NONE'
+      )
+
+      expect_any_instance_of(Gitaly::CommitService::Stub).to receive(:find_commits)
+        .with(request, kind_of(Hash)).and_return([])
+
+      client.find_commits(order: 'default')
+    end
+
     it 'sends an RPC request' do
       request = Gitaly::FindCommitsRequest.new(
         repository: repository_message,

spec/requests/api/commits_spec.rb

@@ -266,8 +266,30 @@ describe API::Commits do
           end
         end
 
-        context 'set to blank' do
-          let(:order) { '' }
+        context 'set to default' do
+          let(:order) { 'default' }
+
+          # git log --graph -n 6 --pretty=format:"%h" --date-order 0031876
+          # *   0031876
+          # |\
+          # * | bf6e164
+          # | * 48ca272
+          # * | 9d526f8
+          # | * 335bc94
+          # |/
+          # * 1039376
+          it 'returns project commits ordered by default order' do
+            commits = project.repository.commits("0031876", limit: 6, order: 'default')
+
+            get api(route, current_user)
+
+            expect(json_response.size).to eq(6)
+            expect(json_response.map { |entry| entry["id"] }).to eq(commits.map(&:id))
+          end
+        end
+
+        context 'set to an invalid parameter' do
+          let(:order) { 'invalid' }
 
           it_behaves_like '400 response' do
             let(:request) { get api(route, current_user) }