Improves documentation regarding the pull mirror feature

app/models/ee/project.rb

@@ -85,13 +85,14 @@ module EE
     end
 
     def mirror_with_content?
-      mirror? && !empty_repo
+      mirror? && !empty_repo?
     end
 
     def scheduled_mirror?
-      enqueued = self.mirror_data.next_execution_timestamp < Time.now
+      return false unless mirror_with_content?
+      return true if import_scheduled?
 
-      mirror_with_content? && import_scheduled? && enqueued
+      self.mirror_data.next_execution_timestamp <= Time.now
     end
 
     def updating_mirror?

app/views/shared/_mirror_update_button.html.haml

 - if @project.mirror? && can?(current_user, :push_code, @project)
   .append-bottom-default
     - if @project.scheduled_mirror?
+      %span.btn.disabled
         = icon("refresh spin")
         Update Scheduled…
     - elsif @project.updating_mirror?

doc/workflow/repository_mirroring.md

@@ -6,8 +6,8 @@ Repository Mirroring is a way to mirror repositories from external sources.
 It can be used to mirror all branches, tags, and commits that you have
 in your repository.
 
-Your mirror at GitLab will be updated automatically once an hour, but you can
-also manually update it whenever you need.
+Your mirror at GitLab will be updated automatically. You can
+also manually trigger an update at most once every 5 minutes.
 
 ## Overview
 
@@ -19,10 +19,11 @@ There are two kinds of repository mirroring features supported by GitLab:
 to another location, whereas the **pull** method mirrors an external repository
 in one in GitLab.
 
-By default, mirror repositories are updated every hour, and all new branches,
+Once the mirror repository is updated, all new branches,
 tags, and commits will be visible in the project's activity feed.
 Users with at least [developer access][perms] to the project can also force an
-immediate update with a click of a button.
+immediate update with the click of a button. This button will not be available if
+the mirror is already being updated or 5 minutes still haven't passed since its last update.
 
 A few things/limitations to consider:
 
@@ -82,6 +83,18 @@ this branch to prevent any changes from being lost.
 
 ![Diverged branch](repository_mirroring/repository_mirroring_diverged_branch.png)
 
+## How it works
+
+Once you activate the pull mirroring feature, the mirror will be inserted into a queue.
+A scheduler will start every minute and schedule a fixed amount of mirrors for update, based
+on the configured maximum capacity.
+
+If the mirror successfully updates it will be enqueued once again with a small backoff
+period.
+
+If the mirror fails (eg: branch diverged from upstream), the project's
+backoff period will be penalized each time it fails up to a maximum amount of time.
+
 ## Pushing to a remote repository
 
 For an existing project, you can set up mirror pushing by visiting your project's

spec/models/project_spec.rb

@@ -1864,6 +1864,28 @@ describe Project, models: true do
     end
   end
 
+  describe '#scheduled_mirror?' do
+    context 'when mirror is expected to run soon' do
+      it 'returns true' do
+        timestamp = Time.now
+        project = create(:project, :mirror, :import_finished)
+
+        project.mirror_last_update_at = timestamp - 3.minutes
+        project.mirror_data.next_execution_timestamp = timestamp - 2.minutes
+
+        expect(project.scheduled_mirror?).to be true
+      end
+    end
+
+    context 'when mirror was scheduled' do
+      it 'returns true' do
+        project = create(:project, :mirror, :import_scheduled)
+
+        expect(project.scheduled_mirror?).to be true
+      end
+    end
+  end
+
   describe  '#updating_mirror?' do
     context 'when repository is empty' do
       it 'returns false' do
@@ -1881,25 +1903,13 @@ describe Project, models: true do
       end
     end
 
-    context 'when project is in progress' do
+    context 'when mirror is in progress' do
       it 'returns true' do
         project = create(:project, :mirror, :import_started)
 
         expect(project.updating_mirror?).to be true
       end
     end
-
-    context 'when project is expected to run soon' do
-      it 'returns true' do
-        timestamp = Time.now
-        project = create(:project, :mirror, :import_finished)
-
-        project.mirror_last_update_at = timestamp - 3.minutes
-        project.mirror_data.next_execution_timestamp = timestamp - 2.minutes
-
-        expect(project.updating_mirror?).to be true
-      end
-    end
   end
 
   describe '#force_import_job!' do