Remove future instances from the Development guide

doc/development/diffs.md

@@ -6,7 +6,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w
 
 # Working with diffs
 
-Currently we rely on different sources to present diffs, these include:
+We rely on different sources to present diffs. These include:
 
 - Gitaly service
 - Database (through `merge_request_diff_files`)
@@ -63,8 +63,7 @@ of hitting the repository every time we need the diff of the file, we:
 ## Diff limits
 
 As explained above, we limit single diff files and the size of the whole diff. There are scenarios where we collapse the diff file,
-and cases where the diff file is not presented at all, and the user is guided to the Blob view. Here we'll go into details about
-these limits.
+and cases where the diff file is not presented at all, and the user is guided to the Blob view.
 
 ### Diff collection limits
 
@@ -74,7 +73,7 @@ Limits that act onto all diff files collection. Files number, lines number and f
 Gitlab::Git::DiffCollection.collection_limits[:safe_max_files] = Gitlab::Git::DiffCollection::DEFAULT_LIMITS[:max_files] = 100
 ```
 
-File diffs will be collapsed (but be expandable) if 100 files have already been rendered.
+File diffs are collapsed (but are expandable) if 100 files have already been rendered.
 
 ```ruby
 Gitlab::Git::DiffCollection.collection_limits[:safe_max_lines] = Gitlab::Git::DiffCollection::DEFAULT_LIMITS[:max_lines] = 5000
@@ -86,28 +85,28 @@ File diffs will be collapsed (but be expandable) if 5000 lines have already been
 Gitlab::Git::DiffCollection.collection_limits[:safe_max_bytes] = Gitlab::Git::DiffCollection.collection_limits[:safe_max_files] * 5.kilobytes = 500.kilobytes
 ```
 
-File diffs will be collapsed (but be expandable) if 500 kilobytes have already been rendered.
+File diffs are collapsed (but be expandable) if 500 kilobytes have already been rendered.
 
 ```ruby
 Gitlab::Git::DiffCollection.collection_limits[:max_files] = Commit::DIFF_HARD_LIMIT_FILES = 1000
 ```
 
-No more files will be rendered at all if 1000 files have already been rendered.
+No more files are rendered at all if 1000 files have already been rendered.
 
 ```ruby
 Gitlab::Git::DiffCollection.collection_limits[:max_lines] = Commit::DIFF_HARD_LIMIT_LINES = 50000
 ```
 
-No more files will be rendered at all if 50,000 lines have already been rendered.
+No more files are rendered at all if 50,000 lines have already been rendered.
 
 ```ruby
 Gitlab::Git::DiffCollection.collection_limits[:max_bytes] = Gitlab::Git::DiffCollection.collection_limits[:max_files] * 5.kilobytes = 5000.kilobytes
 ```
 
-No more files will be rendered at all if 5 megabytes have already been rendered.
+No more files are rendered at all if 5 megabytes have already been rendered.
 
-All collection limit parameters are currently sent and applied on Gitaly. That is, once the limit is surpassed,
-Gitaly will only return the safe amount of data to be persisted on `merge_request_diff_files`.
+All collection limit parameters are sent and applied on Gitaly. That is, after the limit is surpassed,
+Gitaly only returns the safe amount of data to be persisted on `merge_request_diff_files`.
 
 ### Individual diff file limits
 
@@ -117,24 +116,24 @@ Limits that act onto each diff file of a collection. Files number, lines number
 
 Diff patches are collapsed when surpassing 10% of the value set in `ApplicationSettings#diff_max_patch_bytes`.
 That is, it's equivalent to 10kb if the maximum allowed value is 100kb.
-The diff will still be persisted and expandable if the patch size doesn't
+The diff is persisted and expandable if the patch size doesn't
 surpass `ApplicationSettings#diff_max_patch_bytes`.
 
 Although this nomenclature (Collapsing) is also used on Gitaly, this limit is only used on GitLab (hardcoded - not sent to Gitaly).
-Gitaly will only return `Diff.Collapsed` (RPC) when surpassing collection limits.
+Gitaly only returns `Diff.Collapsed` (RPC) when surpassing collection limits.
 
 #### Not expandable patches (too large)
 
 The patch not be rendered if it's larger than `ApplicationSettings#diff_max_patch_bytes`.
-Users will see a `This source diff could not be displayed because it is too large` message.
+Users see a `This source diff could not be displayed because it is too large` message.
 
 ```ruby
 Commit::DIFF_SAFE_LINES = Gitlab::Git::DiffCollection::DEFAULT_LIMITS[:max_lines] = 5000
 ```
 
-File diff will be suppressed (technically different from collapsed, but behaves the same, and is expandable) if it has more than 5000 lines.
+File diff is suppressed (technically different from collapsed, but behaves the same, and is expandable) if it has more than 5000 lines.
 
-This limit is currently hardcoded and only applied on GitLab.
+This limit is hardcoded and only applied on GitLab.
 
 ## Viewers
 

doc/development/multi_version_compatibility.md

@@ -21,7 +21,7 @@ We must make sure that the application works properly in these states.
 For GitLab.com, we also run a set of canary servers which run a more recent version of the application. Users with
 the canary cookie set would be handled by these servers. Some URL patterns may also be forced to the canary servers,
 even without the cookie being set. This also means that some pages may match the pattern and get handled by canary servers,
-but AJAX requests to URLs (like the GraphQL endpoint) won't match the pattern.
+but AJAX requests to URLs (like the GraphQL endpoint) fail to match the pattern.
 
 With this canary setup, we'd be in this mixed-versions state for an extended period of time until canary is promoted to
 production and post-deployment migrations run.
@@ -38,7 +38,7 @@ default. The feature flag can be enabled when the deployment is in a
 consistent state. However, this method of synchronization doesn't
 guarantee that customers with on-premise instances can [upgrade with
 zero downtime](https://docs.gitlab.com/omnibus/update/#zero-downtime-updates)
-since point releases bundle many changes together. Minimizing the time
+because point releases bundle many changes together. Minimizing the time
 between when versions are out of sync across the fleet may help mitigate
 errors caused by upgrades.
 
@@ -70,7 +70,7 @@ This type of change may look like an immediate switch between the two implementa
 especially with the canary stage, there is an extended period of time where both version of the code
 coexists in production.
 
-1. **expand**: a new route is added, pointing to the same controller as the old one. But nothing in the application will generate links for the new routes.
+1. **expand**: a new route is added, pointing to the same controller as the old one. But nothing in the application generates links for the new routes.
 1. **migrate**: now that every machine in the fleet can understand the new route, we can generate links with the new routing.
 1. **contract**: the old route can be safely removed. (If the old route was likely to be widely shared, like the link to a repository file, we might want to add redirects and keep the old route for a longer period.)
 
@@ -84,7 +84,7 @@ When we need to add a new parameter to a Sidekiq worker class, we can split this
 1. **migrate**: we add the new parameter to all the invocations of the worker.
 1. **contract**: we remove the default value.
 
-At a first look, it may seem safe to bundle expand and migrate into a single milestone, but this will cause an outage if Puma restarts before Sidekiq.
+At a first look, it may seem safe to bundle expand and migrate into a single milestone, but this causes an outage if Puma restarts before Sidekiq.
 Puma enqueues jobs with an extra parameter that the old Sidekiq cannot handle.
 
 ### Database migrations
@@ -134,12 +134,12 @@ And these deployments align perfectly with application changes.
 
 With all those details in mind, let's imagine we need to replace a query, and this query has an index to support it.
 
-1. **expand**: this is the from `Schema A` to `Schema B` deployment. We add the new index, but the application will ignore it for now
-1. **migrate**: this is the `Version N` to `Version N+1` application deployment. The new code is deployed, at this point in time only the new query will run.
+1. **expand**: this is the from `Schema A` to `Schema B` deployment. We add the new index, but the application ignores it for now.
+1. **migrate**: this is the `Version N` to `Version N+1` application deployment. The new code is deployed, at this point in time only the new query runs.
 1. **contract**: from `Schema B` to `Schema C` (post-deployment migration). Nothing uses the old index anymore, we can safely remove it.
 
-This is only an example. More complex migrations, especially when background migrations are needed will
-still require more than one milestone. For details please refer to our [migration style guide](migration_style_guide.md).
+This is only an example. More complex migrations, especially when background migrations are needed may
+require more than one milestone. For details please refer to our [migration style guide](migration_style_guide.md).
 
 ## Examples of previous incidents
 

doc/development/query_recorder.md

@@ -30,7 +30,7 @@ In some cases the query count might change slightly between runs for unrelated r
 
 ## Cached queries
 
-By default, QueryRecorder will ignore [cached queries](merge_request_performance_guidelines.md#cached-queries) in the count. However, it may be better to count
+By default, QueryRecorder ignores [cached queries](merge_request_performance_guidelines.md#cached-queries) in the count. However, it may be better to count
 all queries to avoid introducing an N+1 query that may be masked by the statement cache.
 To do this, this requires the `:use_sql_query_cache` flag to be set.
 You should pass the `skip_cached` variable to `QueryRecorder` and use the `exceed_all_query_limit` matcher:
@@ -73,7 +73,7 @@ There are multiple ways to find the source of queries.
 
 - View the call backtrace for the specific `QueryRecorder` instance you want
   by using `ActiveRecord::QueryRecorder.new(query_recorder_debug: true)`. The output
-  will be in `test.log`
+  is stored in file `test.log`.
 
 - Enable the call backtrace for all tests using the `QUERY_RECORDER_DEBUG` environment variable.
 
@@ -83,7 +83,7 @@ There are multiple ways to find the source of queries.
   QUERY_RECORDER_DEBUG=1 bundle exec rspec spec/requests/api/projects_spec.rb
   ```
 
-  This will log calls to QueryRecorder into the `test.log` file. For example:
+  This logs calls to QueryRecorder into the `test.log` file. For example:
 
   ```sql
    QueryRecorder SQL: SELECT COUNT(*) FROM "issues" WHERE "issues"."deleted_at" IS NULL AND "issues"."project_id" = $1 AND ("issues"."state" IN ('opened')) AND "issues"."confidential" = $2