[api] cleanup and document release api

"filter_source_repository" was just another name for "repository"
parameter.
 => Dropped it from api docu, but kept compat code to avoid
    api breakage

Clean'd up different internal method parameter namings, what could lead
to confusion about their meaning.

src/api/app/controllers/source_controller.rb

@@ -1028,8 +1028,8 @@ def package_command_release
           release_package(pkg,
                           releasetarget.target_repository,
                           pkg.release_target_name(releasetarget.target_repository, time_now),
-                          { filter_source_repository: repo,
-                            filter_architecture: params[:arch],
+                          { repository: repo,
+                            arch: params[:arch],
                             multibuild_container: multibuild_container,
                             setrelease: params[:setrelease],
                             manual: true,
@@ -1247,7 +1247,7 @@ def _package_command_release_manual_target(pkg, multibuild_container, time_now)
     release_package(pkg,
                     targetrepo,
                     pkg.release_target_name(targetrepo, time_now),
-                    { filter_source_repository: repo,
+                    { repository: repo,
                       multibuild_container: multibuild_container,
                       filter_architecture: params[:arch],
                       setrelease: params[:setrelease],

src/api/app/controllers/trigger_controller.rb

@@ -26,9 +26,9 @@ class TriggerController < ApplicationController
   def create
     authorize @token, :trigger?
 
-    opts = { project: @project, package: @package, repository: params[:repository], arch: params[:arch],
+    opts = { project: @project, package: @package, arch: params[:arch],
+             repository: params[:repository] || params[:filter_source_repository],
              targetproject: params[:targetproject], targetrepository: params[:targetrepository],
-             filter_source_repository: params[:filter_source_repository],
              setrelease: params[:setrelease] }
     opts[:multibuild_flavor] = @multibuild_container if @multibuild_container.present?
     @token.executor.run_as { @token.call(opts) }

src/api/app/helpers/maintenance_helper.rb

@@ -42,8 +42,8 @@ def _release_package(source_package, target_project, target_package_name, action
   end
 
   def release_package(source_package, target, target_package_name, opts = {})
-    filter_source_repository = opts[:filter_source_repository]
-    filter_architecture      = opts[:filter_architecture]
+    filter_source_repository = opts[:repository]
+    filter_architecture      = opts[:arch]
     multibuild_container     = opts[:multibuild_container]
     action                   = opts[:action]
     setrelease               = opts[:setrelease]

src/api/app/models/project.rb

@@ -1116,7 +1116,7 @@ def do_project_release(params)
             release_package(pkg,
                             releasetarget.target_repository,
                             pkg.release_target_name(releasetarget.target_repository, time_now),
-                            { filter_source_repository: repo,
+                            { repository: repo,
                               setrelease: params[:setrelease],
                               manual: true,
                               comment: comment })

src/api/app/models/token/release.rb

@@ -9,8 +9,8 @@ def call(options)
     time_now = Time.now.utc
 
     package_to_release = options[:package]
-    if options[:targetproject].present? && options[:targetrepository].present? && options[:filter_source_repository].present?
-      source_repository = Repository.find_by_project_and_name(options[:project].name, options[:filter_source_repository])
+    if options[:targetproject].present? && options[:targetrepository].present? && options[:repository].present?
+      source_repository = Repository.find_by_project_and_name(options[:project].name, options[:repository])
       target_repository = Repository.find_by_project_and_name(options[:targetproject], options[:targetrepository])
       raise InsufficientPermissionOnTargetRepository, "no permission to write in project #{target_repository.project.name}" unless User.session!.can_modify?(target_repository.project)
 
@@ -28,11 +28,11 @@ def package_find_options
   private
 
   def release(package_to_release, source_repository, target_repository, time_now, options)
-    opts = { filter_source_repository: source_repository,
+    opts = { repository: source_repository,
              manual: true,
              comment: 'Releasing via trigger event' }
     opts[:multibuild_container] = options[:multibuild_flavor] if options[:multibuild_flavor].present?
-    opts[:filter_architecture] = options[:arch] if options[:arch].present?
+    opts[:arch] = options[:arch] if options[:arch].present?
     opts[:setrelease] = options[:setrelease] if options[:setrelease].present?
 
     if package_to_release.present?
@@ -51,7 +51,7 @@ def release_manually_triggered_targets(package_to_release, time_now, options)
 
     # releasing ...
     manual_release_targets.each do |release_target|
-      next if options[:filter_source_repository].present? && options[:filter_source_repository] == release_target.repository.name
+      next if options[:repository].present? && options[:repository] != release_target.repository.name
 
       release_target.repository.check_valid_release_target!(release_target.target_repository, options[:arch])
       release(package_to_release, release_target.repository, release_target.target_repository, time_now, options)

src/api/public/apidocs/paths/trigger_operation.yaml

@@ -79,53 +79,6 @@ post:
       schema:
         type: string
       example: vim
-    - in: query
-      name: repository
-      description: |
-        Restrict the API token operation to this repository.
-        
-        Only has an effect if the API token operation is 'rebuild' or 'release'.
-      schema:
-        type: string
-      example: openSUSE_Factory
-    - in: query
-      name: arch
-      description: |
-        Restrict the API token operation to this architecture with this name.
-        
-        Only has an effect when the API token operation is 'rebuild' or 'release'.
-      schema:
-        type: string
-      example: x86_64
-    - in: query
-      name: targetproject
-      description: |
-        Release binaries only to the provided project with this name.
-        Setting this requires the 'targetrepository' parameter to be set also.
-
-        Only has an effect if the API token operation is 'release'.
-      schema:
-        type: string
-      example: devel:languages:ruby
-    - in: query
-      name: targetrepository
-      description: |
-        Release binaries only to the target repository with this name.
-        Setting this requires the 'targetproject' parameter to be set also.
-
-        Only has an effect if the API token operation is 'release'.
-      schema:
-        type: string
-      example: openSUSE_Factory
-    - in: query
-      name: filter_source_repository
-      description: |
-        Release binaries only from the repository with this name.
-
-        Only has an effect if the API token operation is 'release'.
-      schema:
-        type: string
-      example: openSUSE_Factory
   responses:
     '200':
       $ref: '../components/responses/succeeded.yaml'

src/api/public/apidocs/paths/trigger_rebuild.yaml

@@ -5,5 +5,20 @@ post:
     only allows API tokens with the operation 'rebuild' to be triggered.
   security:
     - GitLab_key_authentication: []
+  parameters:
+    - in: query
+      name: repository
+      description: |
+        Restrict the rebuild to this repository.
+      schema:
+        type: string
+      example: openSUSE_Factory
+    - in: query
+      name: arch
+      description: |
+        Restrict the rebuild to this scheduler architecture.
+      schema:
+        type: string
+      example: x86_64
   tags:
     - Trigger

src/api/public/apidocs/paths/trigger_release.yaml

@@ -5,5 +5,45 @@ post:
     only allows API tokens the the operation 'release' to be triggered.
   security:
     - GitLab_key_authentication: []
+  parameters:
+    - in: query
+      name: repository
+      description: |
+        Restrict the release to binaries from this repository.
+      schema:
+        type: string
+      example: openSUSE_Factory
+    - in: query
+      name: arch
+      description: |
+        Restrict the rebuild to this scheduler architecture.
+      schema:
+        type: string
+      example: x86_64
+    - in: query
+      name: targetproject
+      description: |
+        Release binaries only to the provided project with this name.
+        Setting this requires the 'targetrepository' parameter to be set also.
+      schema:
+        type: string
+      example: devel:languages:ruby
+    - in: query
+      name: targetrepository
+      description: |
+        Release binaries only to the target repository with this name.
+        Setting this requires the 'targetproject' parameter to be set also.
+      schema:
+        type: string
+      example: openSUSE_Factory
+    - in: query
+      name: setrelease
+      description: |
+        Defines a custom release name. This overwrites milestone definitions
+        or built-in defaults.
+        Renaming can be disabled entirely by using '-'.
+      schema:
+        type: string
+      example: openSUSE_Factory
   tags:
     - Trigger

src/api/spec/models/token/release_spec.rb

@@ -70,9 +70,9 @@
         allow(Backend::Connection).to receive(:post).with(backend_url).and_return("<status code=\"ok\" />\n")
       end
 
-      context 'when the target_project, targetrepository, filter_source_repository and arch parameters are provided' do
+      context 'when the target_project, targetrepository, repository and arch parameters are provided' do
         subject do
-          token.call(package: package, project: project_staging, targetproject: 'Baz', targetrepository: 'other_target_repository', filter_source_repository: 'other_source_repository')
+          token.call(package: package, project: project_staging, targetproject: 'Baz', targetrepository: 'other_target_repository', repository: 'other_source_repository')
         end
 
         it 'triggers the release process in the backend' do
@@ -86,7 +86,7 @@
 
       context 'when the user can not modify the target_repository' do
         subject do
-          token.call(package: package, project: project_staging, targetproject: 'Foo', targetrepository: 'other_target_repository', filter_source_repository: 'other_source_repository')
+          token.call(package: package, project: project_staging, targetproject: 'Foo', targetrepository: 'other_target_repository', repository: 'other_source_repository')
         end
 
         let(:other_target_project) { create(:project, name: 'Foo') }
@@ -102,7 +102,7 @@
 
       context 'when the architecture is provided through parameters and is not included in the target repository' do
         subject do
-          token.call(package: package, project: project_staging, targetproject: 'Baz', targetrepository: 'other_target_repository', filter_source_repository: 'other_source_repository',
+          token.call(package: package, project: project_staging, targetproject: 'Baz', targetrepository: 'other_target_repository', repository: 'other_source_repository',
                      arch: 's390x')
         end
 
@@ -115,7 +115,7 @@
 
       context 'when the architecture is provided through parameters and is included in the target repository' do
         subject do
-          token.call(package: package, project: project_staging, targetproject: 'Baz', targetrepository: 'other_target_repository', filter_source_repository: 'other_source_repository',
+          token.call(package: package, project: project_staging, targetproject: 'Baz', targetrepository: 'other_target_repository', repository: 'other_source_repository',
                      arch: 'x86_64')
         end