Reorders migrations readme file

The document is now split in two sections:
- Testing an ActiveRecord migration
- Testing an non-ActiveRecord migration

Both sections have an example

spec/migrations/README.md

@@ -22,39 +22,33 @@ migrate the database **down** to the previous migration version.
 With this approach you can test a migration against a database schema that this
 migration has been written for.
 
-Use `migrate!` helper to run the migration that is under test.
-
 The `after` hook will migrate the database **up** and reinstitutes the latest
 schema version, so that the process does not affect subsequent specs and
 ensures proper isolation.
 
-## Testing a class that is not an ActiveRecord::Migration
-
-In order to test a class that is not a migration itself, you will need to
-manually provide a required schema version. Please add a `schema` tag to a
-context that you want to switch the database schema within.
-
-Example: `describe SomeClass, :migration, schema: 20170608152748`.
-
 ## Available helpers
 
 Use `table` helper to create a temporary `ActiveRecord::Base` derived model
 for a table.
 
-Use `migrate!` helper to run the migration that is under test. It will not only
+See `spec/support/helpers/migrations_helpers.rb` for all the available helpers.
+
+## Testing a class that is an ActiveRecord::Migration
+
+In order to test a class that is an `ActiveRecord::Migration`, you will need to
+manually `require` the migration file because it is not autoloaded with Rails.
+
+Use `migrate!` helper to run the migration that is under test.  It will not only
 run migration, but will also bump the schema version in the `schema_migrations`
 table. It is necessary because in the `after` hook we trigger the rest of
 the migrations, and we need to know where to start.
 
-See `spec/support/migrations_helpers.rb` for all the available helpers.
+### Example
 
-## An example
+This spec tests the [`db/post_migrate/20170526185842_migrate_pipeline_stages.rb`](https://gitlab.com/gitlab-org/gitlab-ce/blob/v11.6.5/db/post_migrate/20170526185842_migrate_pipeline_stages.rb) migration. You can find the complete spec on [`spec/migrations/migrate_pipeline_stages_spec.rb`](https://gitlab.com/gitlab-org/gitlab-ce/blob/v11.6.5/spec/migrations/migrate_pipeline_stages_spec.rb).
 
 ```ruby
 require 'spec_helper'
-
-# Load a migration class.
-
 require Rails.root.join('db', 'post_migrate', '20170526185842_migrate_pipeline_stages.rb')
 
 describe MigratePipelineStages, :migration do
@@ -86,6 +80,56 @@ describe MigratePipelineStages, :migration do
 end
 ```
 
+## Testing a class that is not an ActiveRecord::Migration
+
+To test a class that is not an `ActiveRecord::Migration` (a background migration),
+you will need to manually provide a required schema version. Please add a
+schema tag to a context that you want to switch the database schema within.
+
+Example: `describe SomeClass, :migration, schema: 20170608152748`.
+
+### Example
+
+This spec tests the [`lib/gitlab/background_migration/archive_legacy_traces.rb`](https://gitlab.com/gitlab-org/gitlab-ce/blob/v11.6.5/lib/gitlab/background_migration/archive_legacy_traces.rb)
+background migration. You can find the complete spec on 
+[`spec/lib/gitlab/background_migration/archive_legacy_traces_spec.rb`](https://gitlab.com/gitlab-org/gitlab-ce/blob/v11.6.5/spec/lib/gitlab/background_migration/archive_legacy_traces_spec.rb)
+
+```ruby
+require 'spec_helper'
+
+describe Gitlab::BackgroundMigration::ArchiveLegacyTraces, :migration, schema: 20180529152628 do
+  include TraceHelpers
+
+  let(:namespaces) { table(:namespaces) }
+  let(:projects) { table(:projects) }
+  let(:builds) { table(:ci_builds) }
+  let(:job_artifacts) { table(:ci_job_artifacts) }
+
+  before do
+    namespaces.create!(id: 123, name: 'gitlab1', path: 'gitlab1')
+    projects.create!(id: 123, name: 'gitlab1', path: 'gitlab1', namespace_id: 123)
+    @build = builds.create!(id: 1, project_id: 123, status: 'success', type: 'Ci::Build')
+  end
+
+  context 'when trace file exsits at the right place' do
+    before do
+      create_legacy_trace(@build, 'trace in file')
+    end
+
+    it 'correctly archive legacy traces' do
+      expect(job_artifacts.count).to eq(0)
+      expect(File.exist?(legacy_trace_path(@build))).to be_truthy
+
+      described_class.new.perform(1, 1)
+
+      expect(job_artifacts.count).to eq(1)
+      expect(File.exist?(legacy_trace_path(@build))).to be_falsy
+      expect(File.read(archived_trace_path(job_artifacts.first))).to eq('trace in file')
+    end
+  end
+end
+```
+
 ## Best practices
 
 1. Note that this type of tests do not run within the transaction, we use