Merge branch 'master' into 62788-graphql-pagination62788-graphql-pagination

* master: (61 commits)
  Add dependency list documentation
  added code differences from EE to CE
  Remove metrics_time_window feature flag
  SSoT audit fixes
  Integrate demo link into content more
  Add styles and animations for onboarding helper
  Add git 2.21 install from update_source
  IDE trigger files change event
  Remove 'build-page' from 'ide-terminal' element
  Add section to dev docs on accessing chatops
  Fix OpenID Connect documentation
  Make OpenID Connect work without requiring a name
  Apply reviewer feedback
  Change text to match screencaps
  Reword for clarity
  Upgrade jira user permissions workflow docs
  Fix some typoes
  Removes duplicated shared_context folder
  Add frontend support for cluster health alerts
  Add changelog entry for sidekiq metrics
  ...

1 files changed, 82 insertions, 0 deletions

diff --git a/doc/administration/troubleshooting/migration.md b/doc/administration/troubleshooting/migration.md
new file mode 100644
index 00000000000..4d2d268b9df
--- /dev/null
+++ b/doc/administration/troubleshooting/migration.md
@@ -0,0 +1,82 @@
+# Migrations problems
+
+## Legacy upload migration
+
+> Introduced in GitLab 12.0.
+
+  The migration takes all attachments uploaded by legacy `AttachmentUploader` and
+  migrate them to the path that current uploaders expect.
+
+Although it should not usually happen there could possibly be some attachments belonging to
+LegacyDiffNotes. These attachments can't be seen before running the migration by users and
+they should not be present in your instance.
+
+However, if you have some of them, you will need to handle them manually.
+You can find the ids of failed notes in logs as "MigrateLegacyUploads: LegacyDiffNote"
+
+1. Run a Rails console:
+
+    ```sh
+    sudo gitlab-rails console production
+    ```
+
+    or for source installs:
+
+    ```sh
+    bundle exec rails console production
+    ```
+
+ 1. Check the failed upload and find the note (you can see their ids in the logs)
+
+    ```ruby
+    upload = Upload.find(upload_id)
+    note = Note.find(note_id)
+    ```
+
+
+ 1. Check the path - it should contain `system/note/attachment`
+
+    ```ruby
+    upload.absolut_path
+    ```
+    
+ 1. Check the path in the uploader - it should differ from the upload path and should contain  `system/legacy_diff_note`
+ 
+    ```ruby
+    uploader = upload.build_uploader
+    uploader.file
+    ```
+    
+ 1. First, you need to move the file to the path that is expected from the uploader
+
+    ```ruby
+    old_path = upload.absolute_path
+    new_path = upload.absolute_path.sub('-/system/note/attachment', '-/system/legacy_diff_note')
+    new_dir = File.dirname(new_path)
+    FileUtils.mkdir_p(new_dir)
+    
+    FileUtils.mv(old_path, new_path)
+    ```
+
+ 1. You then need to move the file to the `FileUploader` and create a new `Upload` object
+ 
+    ```ruby
+    file_uploader = UploadService.new(note.project, File.read(new_path)).execute
+    ```
+ 
+ 1. And update the legacy note to contain the file.
+ 
+    ```ruby
+    new_text = "#{note.note} \n #{file_uploader.markdown_link}"
+    note.update!(
+      note: new_text
+    )
+    ```
+
+ 1. And finally, you can remove the old upload
+ 
+    ```ruby
+    upload.destroy
+    ```
+
+If you have any problems feel free to contact [GitLab Support](https://about.gitlab.com/support/).