add prepare for upgrade section

helps detect and correct issues that may occur during upgrade before
they have already occurred. easier to address issues before you start
upgrade process.

1 files changed, 67 insertions, 29 deletions

diff --git a/doc/update/5.1-to-6.0.md b/doc/update/5.1-to-6.0.md
index 8870f5bc859..a76b371e6d6 100644
--- a/doc/update/5.1-to-6.0.md
+++ b/doc/update/5.1-to-6.0.md
@@ -28,7 +28,7 @@ Any changes to group members will immediately be reflected in the project permis
 
 You can even have multiple owners for a group, greatly simplifying administration.
 
-## 0. Backup
+## 0. Backup & prepare for update
 
 It's useful to make a backup just in case things go south:
 (With MySQL, this may require granting "LOCK TABLES" privileges to the GitLab user on the database version)
@@ -38,6 +38,72 @@ cd /home/git/gitlab
 sudo -u git -H bundle exec rake gitlab:backup:create RAILS_ENV=production
 ```
 
+The migrations in this update are very sensitive to incomplete or inconsistent data. If you have a long-running GitLab installation and some of the previous upgrades did not work out 100% correct this may bite you now. The following can help you have a more smooth upgrade.
+
+### Find projets with invalid project names
+
+#### MySQL
+Login to MySQL:
+
+    mysql -u root -p
+
+Find projects with invalid names:
+
+```bash
+mysql> use gitlabhq_production;
+
+# find projects with invalid first char, projects must start with letter
+mysql> select name from projects where name REGEXP '^[^A-Za-z]';
+
+# find projects with other invalid chars
+## names must only contain alphanumeric chars, underscores, spaces, periods, and dashes
+mysql> select name from projects where name REGEXP '[^a-zA-Z0-9_ .-]+';
+```
+
+If any projects have invalid names try correcting them from the web interface before starting the upgrade.
+If correcting them from the web interface fails you can correct them using MySQL:
+
+```bash
+# e.g. replace invalid / with allowed _
+mysql> update projects set name = REPLACE(name,'/','_');
+# repeat for all invalid chars found in project names
+```
+
+#### PostgreSQL
+Make sure all project names start with a letter and only contain alphanumeric chars, underscores, spaces, periods, and dashes (a-zA-Z0-9_ .-).
+
+### Find other common errors
+
+```
+cd /home/git/gitlab
+# Start rails console
+sudo -u git -H bin/rails console production
+
+# Make sure none of the following rails commands return results
+
+# All project owners should have an owner:
+Project.all.select { |project| project.owner.blank? }
+
+# Every user should have a namespace:
+User.all.select { |u| u.namespace.blank? }
+
+# Projects in the global namespace should not conflict with projects in the owner namespace:
+Project.where(namespace_id: nil).select { |p| Project.where(path: p.path, namespace_id: p.owner.try(:namespace).try(:id)).present? }
+```
+
+If any of the above rails commands returned results other than `=> []` try correcting the issue from the web interface.
+
+If you find projects without an owner (first rails command above), correct it. For MySQL setups:
+
+```bash
+# get your user id
+mysql> select id, name from users order by name;
+
+# set yourself as owner of project
+# replace your_user_id with your user id and bad_project_id with the project id from the rails command
+mysql> update projects set creator_id=your_user_id where id=bad_project_id;
+```
+
 ## 1. Stop server
 
     sudo service gitlab stop
@@ -147,31 +213,3 @@ Follow the [upgrade guide from 5.0 to 5.1](5.0-to-5.1.md), except for the databa
 cd /home/git/gitlab
 sudo -u git -H bundle exec rake gitlab:backup:restore RAILS_ENV=production
 ```
-
-## Troubleshooting
-
-The migrations in this update are very sensitive to incomplete or inconsistent data. If you have a long-running GitLab installation and some of the previous upgrades did not work out 100% correct this may bite you now. The following commands can be run in the rails console to look for 'bad' data.
-
-Start rails console:
-
-```
-sudo -u git -H rails console production
-```
-
-All project owners should have an owner:
-
-```
-Project.all.select { |project| project.owner.blank? }
-```
-
-Every user should have a namespace:
-
-```
-User.all.select { |u| u.namespace.blank? }
-```
-
-Projects in the global namespace should not conflict with projects in the owner namespace:
-
-```
-Project.where(namespace_id: nil).select { |p| Project.where(path: p.path, namespace_id: p.owner.try(:namespace).try(:id)).present? }
-```