Merge branch 'update-migration-process' into 'master'

Update migration process

Closes #916

See merge request gitlab-org/gitaly!553

1 files changed, 18 insertions, 38 deletions

diff --git a/doc/MIGRATION_PROCESS.md b/doc/MIGRATION_PROCESS.md
index d512e067f..a9c24eee3 100644
--- a/doc/MIGRATION_PROCESS.md
+++ b/doc/MIGRATION_PROCESS.md
@@ -24,26 +24,6 @@ The order of migration is roughly determined using the formula described in the
 
 ---------------------------------------------------------------------
 
-## Migration Analysis: ~"Migration Analysis"  
-
-Once a route has been selected, the route in the client will be analysed and profiled in order to figure out the best way of migrating the route to Gitaly.
-
-During the migration analysis, the following factors should be taken into consideration:
-
-1. *Test coverage of the legacy code*: 
-   * How well covered is the legacy code? Use https://gitlab-org.gitlab.io/gitlab-ce/coverage-ruby to find out.
-   * Are there important codepaths in the legacy code base that are not being tested?
-   * If so, should we create tests for these codepaths before continuing with the migration?
-1.  
-
-The artefacts of this stage will be:
-
-1. **Rough estimation of the amount of work involved in the migration**: from the analysis, we should have a rough idea of how long this migration will take.
-1. **Decision to move ahead with migration**: At this stage of the project, we're working to achieve the best value for effort. If we feel that a migration will take too much effort for the value gained, then it may be shelved.
-1. **Optional: a new grpc Endpoint**: the analysis may show that the route can be migrated using an existing Gitaly endpoint, or that a new endpoint needs to be designed. If an existing endpoint is used, jump directly to **Client Implementation**, skipping **RPC design** and **Server Implementation**
-
----------------------------------------------------------------------
-
 ## RPC Design: ~"RPC Design"
 
 A new GRPC endpoint is added to the [`gitaly-proto`](https://gitlab.com/gitlab-org/gitaly-proto) project.
@@ -80,7 +60,7 @@ disabled by default until acceptance testing has been completed.
 
 This happens in three stages:
 * Feature Status: Ready-for-Testing
-* Feature Status Opt-In
+* Feature Status: Opt-In
 * Feature Status: Opt-Out
 * Feature Status: Mandatory
 
@@ -92,22 +72,10 @@ A feature is tested in dev, staging and gitlab.com. If the results are satisfact
 
 The following procedure should be used for testing:
 
-1. Create a new row in the Gitaly dashboard to monitor the feature in the [`gitaly-dashboards`](https://gitlab.com/gitlab-org/gitaly-dashboards) repo.
-  - Merge the chef-repo MRs
-  - Make sure new role file is on chef server `bundle exec knife role from file [role-path]`
-  - Run chef client and restart unicorn: `bundle exec knife ssh -C 1 roles:[role-name] 'sudo chef-client; sleep 60; sudo gitlab-ctl term unicorn; echo done $?'`
-  - Verify the process have the env values set: `bundle exec knife ssh roles:[role-name] 'for p in $(pgrep -f "unicorn master"); do ps -o pid,etime,args -p $p; sudo strings -f /proc/$p/environ | grep GITALY; done'`
-1. Enable the feature:
-  - For dev: ssh into dev.gitlab.org and run in a rails console: `Feature.get('gitaly_<my_feature>').enable`
-  - For staging: run the cog command `!feature-set gitaly_<my_feature> true` on channel #development
-  - For production: run the cog command `!feature-set gitaly_<my_feature> true` on channel #production
-1. Monitor dashboards and host systems to ensure that feature is working.
-1. Get the production engineer to roll the feature back.
-1. Review data:
-    1. Did the test route perform well?
-    1. Did the client or server processes consume excessive resources during the test?
-    1. Did error rates jump during the test?
-1. If the test if successful, proceed to next environment.
+1. Create a new ~"Acceptance Testing" issue
+  - Fill it with the content generated by [`_support/generate-acceptance-testing-issue`](https://gitlab.com/gitlab-org/gitaly/blob/master/_support/generate-acceptance-testing-issue)
+1. Follow the procedure in the generated issue.
+  - Note that the procedure might change, so keep an eye on [`.gitlab/issue_templates/Migration_Acceptance_Testing.md`](https://gitlab.com/gitlab-org/gitaly/blob/master/.gitlab/issue_templates/Migration_Acceptance_Testing.md)
 
 Once acceptance testing has been successfully completed in all three environments, we need to prepare for opt-in status.
 
@@ -124,7 +92,7 @@ As the maintainer of Gitaly, Jacob to review:
 * The alerts are in-place
 * The runbooks are good
 
-Once Jacob has approved, the feature flag will be enabled on dev.gitlab.org, staging and GitLab.com, but the feature flag will be disabled by default. On-premise installations can enable the feature if they wish, but it will be disabled by default.
+The feature flag will be enabled on dev.gitlab.org, staging and GitLab.com, but the feature flag will be disabled by default. On-premise installations can enable the feature if they wish, but it will be disabled by default.
 
 For a feature toggle `GITALY_EXAMPLE_FEATURE`, the toggle would be enabled by setting the environment variable:  
 
@@ -132,6 +100,12 @@ For a feature toggle `GITALY_EXAMPLE_FEATURE`, the toggle would be enabled by se
 GITALY_EXAMPLE_FEATURE=1 # "One" to enable
 ```
 
+Or by running this command in a Rails Console:
+
+```ruby
+Feature.enable("gitaly_example_feature")
+```
+
 If the flag is missing, the feature will be **disabled by default**.
 
 ---------------------------------------------------------------------
@@ -150,6 +124,12 @@ For a feature toggle `GITALY_EXAMPLE_FEATURE`, the toggle would be enabled by se
 GITALY_EXAMPLE_FEATURE=0 # "Zero" to disable
 ```
 
+Or by running this command in a Rails Console:
+
+```ruby
+Feature.disable("gitaly_example_feature")
+```
+
 If the flag is missing, the feature will be **enabled by default**.
 
 ---------------------------------------------------------------------