Merge branch 'docs-aqualls-20200417-reflinks' into 'master'

Docs: update links to use standard style

See merge request gitlab-org/gitlab!29837

doc/development/api_styleguide.md

@@ -9,7 +9,7 @@ to access them as we do in Rails views), local variables are fine.
 
 ## Entities
 
-Always use an [Entity] to present the endpoint's payload.
+Always use an [Entity](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/api/entities) to present the endpoint's payload.
 
 ## Documentation
 
@@ -29,7 +29,7 @@ for a good example):
   - If the endpoint is deprecated, and if so, when will it be removed
 
 - `params` for the method parameters. This acts as description,
-  [validation, and coercion of the parameters]
+  [validation, and coercion of the parameters](https://github.com/ruby-grape/grape#parameter-validation-and-coercion)
 
 A good example is as follows:
 
@@ -106,7 +106,7 @@ For `DELETE` requests, you should also generally use the `destroy_conditionally!
 
 ## Using API path helpers in GitLab Rails codebase
 
-Because we support [installing GitLab under a relative URL], one must take this
+Because we support [installing GitLab under a relative URL](../install/relative_url.md), one must take this
 into account when using API path helpers generated by Grape. Any such API path
 helper usage must be in wrapped into the `expose_path` helper call.
 
@@ -121,10 +121,6 @@ For instance:
 The [internal API](./internal_api.md) is documented for internal use. Please keep it up to date so we know what endpoints
 different components are making use of.
 
-[Entity]: https://gitlab.com/gitlab-org/gitlab/blob/master/lib/api/entities
-[validation, and coercion of the parameters]: https://github.com/ruby-grape/grape#parameter-validation-and-coercion
-[installing GitLab under a relative URL]: https://docs.gitlab.com/ee/install/relative_url.html
-
 ## Avoiding N+1 problems
 
 In order to avoid N+1 problems that are common when returning collections

doc/development/diffs.md

@@ -8,12 +8,7 @@ Currently we rely on different sources to present diffs, these include:
 
 ## Deep Dive
 
-In January 2019, Oswaldo Ferreira hosted a [Deep Dive] on GitLab's Diffs and Commenting on Diffs functionality to share his domain specific knowledge with anyone who may work in this part of the code base in the future. You can find the [recording on YouTube], and the slides on [Google Slides] and in [PDF]. Everything covered in this deep dive was accurate as of GitLab 11.7, and while specific details may have changed since then, it should still serve as a good introduction.
-
-[Deep Dive]: https://gitlab.com/gitlab-org/create-stage/issues/1
-[recording on YouTube]: https://www.youtube.com/watch?v=K6G3gMcFyek
-[Google Slides]: https://docs.google.com/presentation/d/1bGutFH2AT3bxOPZuLMGl1ANWHqFnrxwQwjiwAZkF-TU/edit
-[PDF]: https://gitlab.com/gitlab-org/create-stage/uploads/b5ad2f336e0afcfe0f99db0af0ccc71a/Create_Deep_Dive__Diffs_and_commenting_on_diffs.pdf
+In January 2019, Oswaldo Ferreira hosted a [Deep Dive](https://gitlab.com/gitlab-org/create-stage/issues/1) on GitLab's Diffs and Commenting on Diffs functionality to share his domain specific knowledge with anyone who may work in this part of the code base in the future. You can find the [recording on YouTube](https://www.youtube.com/watch?v=K6G3gMcFyek), and the slides on [Google Slides](https://docs.google.com/presentation/d/1bGutFH2AT3bxOPZuLMGl1ANWHqFnrxwQwjiwAZkF-TU/edit) and in [PDF](https://gitlab.com/gitlab-org/create-stage/uploads/b5ad2f336e0afcfe0f99db0af0ccc71a/). Everything covered in this deep dive was accurate as of GitLab 11.7, and while specific details may have changed since then, it should still serve as a good introduction.
 
 ## Architecture overview
 

doc/development/fe_guide/design_patterns.md

@@ -75,6 +75,4 @@ class Foo {
 new Foo({ container: '.my-element' });
 ```
 
-You can find an example of the above in this [class][container-class-example];
-
-[container-class-example]: https://gitlab.com/gitlab-org/gitlab/blob/master/app/assets/javascripts/mini_pipeline_graph_dropdown.js
+You can find an example of the above in this [class](https://gitlab.com/gitlab-org/gitlab/blob/master/app/assets/javascripts/mini_pipeline_graph_dropdown.js);

doc/development/fe_guide/vue.md

@@ -12,17 +12,17 @@ What is described in the following sections can be found in these examples:
 
 ## Vue architecture
 
-All new features built with Vue.js must follow a [Flux architecture][flux].
+All new features built with Vue.js must follow a [Flux architecture](https://facebook.github.io/flux/).
 The main goal we are trying to achieve is to have only one data flow and only one data entry.
 In order to achieve this goal we use [vuex](#vuex).
 
-You can also read about this architecture in vue docs about [state management][state-management]
-and about [one way data flow][one-way-data-flow].
+You can also read about this architecture in vue docs about [state management](https://vuejs.org/v2/guide/state-management.html#Simple-State-Management-from-Scratch)
+and about [one way data flow](https://vuejs.org/v2/guide/components.html#One-Way-Data-Flow).
 
 ### Components and Store
 
-In some features implemented with Vue.js, like the [issue board][issue-boards]
-or [environments table][environments-table]
+In some features implemented with Vue.js, like the [issue board](https://gitlab.com/gitlab-org/gitlab-foss/tree/master/app/assets/javascripts/boards)
+or [environments table](https://gitlab.com/gitlab-org/gitlab-foss/tree/master/app/assets/javascripts/environments)
 you can find a clear separation of concerns:
 
 ```plaintext
@@ -47,7 +47,7 @@ of the new feature should be.
 The Store and the Service should be imported and initialized in this file and
 provided as a prop to the main component.
 
-Be sure to read about [page-specific JavaScript][page_specific_javascript].
+Be sure to read about [page-specific JavaScript](./performance.md#page-specific-javascript).
 
 ### Bootstrapping Gotchas
 
@@ -162,7 +162,7 @@ For example, tables are used in a quite amount of places across GitLab, a table
 would be a good fit for a component. On the other hand, a table cell used only
 in one table would not be a good use of this pattern.
 
-You can read more about components in Vue.js site, [Component System][component-system]
+You can read more about components in Vue.js site, [Component System](https://vuejs.org/v2/guide/#Composing-with-Components).
 
 ### A folder for the Store
 
@@ -278,7 +278,7 @@ const vm = mountComponent(Component, data);
 ### Test the component's output
 
 The main return value of a Vue component is the rendered output. In order to test the component we
-need to test the rendered output. [Vue][vue-test] guide's to unit test show us exactly that:
+need to test the rendered output. [Vue](https://vuejs.org/v2/guide/unit-testing.html) guide's to unit test show us exactly that:
 
 ## Vue.js Expert Role
 
@@ -289,13 +289,3 @@ One should apply to be a Vue.js expert by opening an MR when the Merge Request's
 - Full understanding of testing a Vue and Vuex application
 - Vuex code follows the [documented pattern](vuex.md#actions-pattern-request-and-receive-namespaces)
 - Knowledge about the existing Vue and Vuex applications and existing reusable components
-
-[issue-boards]: https://gitlab.com/gitlab-org/gitlab-foss/tree/master/app/assets/javascripts/boards
-[environments-table]: https://gitlab.com/gitlab-org/gitlab-foss/tree/master/app/assets/javascripts/environments
-[page_specific_javascript]: ./performance.md#page-specific-javascript
-[component-system]: https://vuejs.org/v2/guide/#Composing-with-Components
-[state-management]: https://vuejs.org/v2/guide/state-management.html#Simple-State-Management-from-Scratch
-[one-way-data-flow]: https://vuejs.org/v2/guide/components.html#One-Way-Data-Flow
-[vue-test]: https://vuejs.org/v2/guide/unit-testing.html
-[flux]: https://facebook.github.io/flux/
-[axios]: https://github.com/axios/axios

doc/development/testing_guide/best_practices.md

@@ -17,7 +17,7 @@ our test design. We can find some helpful heuristics documented in the Handbook
 
 ## Test speed
 
-GitLab has a massive test suite that, without [parallelization], can take hours
+GitLab has a massive test suite that, without [parallelization](ci.md#test-suite-parallelization-on-the-ci), can take hours
 to run. It's important that we make an effort to write tests that are accurate
 and effective _as well as_ fast.
 
@@ -30,8 +30,6 @@ Here are some things to keep in mind regarding test performance:
 - Don't mark a feature as requiring JavaScript (through `:js` in RSpec) unless it's _actually_ required for the test
   to be valid. Headless browser testing is slow!
 
-[parallelization]: ci.md#test-suite-parallelization-on-the-ci
-
 ## RSpec
 
 To run rspec tests:
@@ -651,7 +649,7 @@ end
 
 ### Factories
 
-GitLab uses [factory_bot] as a test fixture replacement.
+GitLab uses [factory_bot](https://github.com/thoughtbot/factory_bot) as a test fixture replacement.
 
 - Factory definitions live in `spec/factories/`, named using the pluralization
   of their corresponding model (`User` factories are defined in `users.rb`).
@@ -666,8 +664,6 @@ GitLab uses [factory_bot] as a test fixture replacement.
 - Factories don't have to be limited to `ActiveRecord` objects.
   [See example](https://gitlab.com/gitlab-org/gitlab-foss/commit/0b8cefd3b2385a21cfed779bd659978c0402766d).
 
-[factory_bot]: https://github.com/thoughtbot/factory_bot
-
 ### Fixtures
 
 All fixtures should be placed under `spec/fixtures/`.

doc/development/testing_guide/frontend_testing.md

@@ -5,7 +5,7 @@ at GitLab. We use Karma with Jasmine and Jest for JavaScript unit and integratio
 and RSpec feature tests with Capybara for e2e (end-to-end) integration testing.
 
 Unit and feature tests need to be written for all new features.
-Most of the time, you should use [RSpec] for your feature tests.
+Most of the time, you should use [RSpec](https://github.com/rspec/rspec-rails#feature-specs) for your feature tests.
 
 Regression tests should be written for bug fixes to prevent them from recurring
 in the future.
@@ -15,7 +15,7 @@ information on general testing practices at GitLab.
 
 ## Vue.js testing
 
-If you are looking for a guide on Vue component testing, you can jump right away to this [section][vue-test].
+If you are looking for a guide on Vue component testing, you can jump right away to this [section](../fe_guide/vue.md#testing-vue-components).
 
 ## Jest
 
@@ -30,7 +30,7 @@ Jest tests can be found in `/spec/frontend` and `/ee/spec/frontend` in EE.
 
 ## Karma test suite
 
-While GitLab is switching over to [Jest][jest] you'll still find Karma tests in our application. [Karma][karma] is a test runner which uses [Jasmine] as its test
+While GitLab is switching over to [Jest](https://jestjs.io) you'll still find Karma tests in our application. [Karma](http://karma-runner.github.io/) is a test runner which uses [Jasmine](https://jasmine.github.io/) as its test
 framework. Jest also uses Jasmine as foundation, that's why it's looking quite similar.
 
 Karma tests live in `spec/javascripts/` and `/ee/spec/javascripts` in EE.
@@ -549,7 +549,8 @@ TBU
 
 Jasmine provides stubbing and mocking capabilities. There are some subtle differences in how to use it within Karma and Jest.
 
-Stubs or spies are often used synonymously. In Jest it's quite easy thanks to the `.spyOn` method. [Official docs][jestspy]
+Stubs or spies are often used synonymously. In Jest it's quite easy thanks to the `.spyOn` method.
+[Official docs](https://jestjs.io/docs/en/jest-object#jestspyonobject-methodname)
 The more challenging part are mocks, which can be used for functions or even dependencies.
 
 ### Manual module mocks
@@ -642,7 +643,7 @@ multiple browsers at once to have it run the tests on each in parallel.
 
 While Karma is running, any changes you make will instantly trigger a recompile
 and retest of the **entire test suite**, so you can see instantly if you've broken
-a test with your changes. You can use [Jasmine focused][jasmine-focus] or
+a test with your changes. You can use [Jasmine focused](https://jasmine.github.io/2.5/focused_specs.html) or
 excluded tests (with `fdescribe` or `xdescribe`) to get Karma to run only the
 tests you want while you're working on a specific feature, but make sure to
 remove these directives when you commit your code.
@@ -906,13 +907,3 @@ You can download any older version of Firefox from the releases FTP server, <htt
 ---
 
 [Return to Testing documentation](index.md)
-
-<!-- URL References -->
-
-[jasmine-focus]: https://jasmine.github.io/2.5/focused_specs.html
-[karma]: http://karma-runner.github.io/
-[vue-test]: ../fe_guide/vue.md#testing-vue-components
-[rspec]: https://github.com/rspec/rspec-rails#feature-specs
-[jasmine]: https://jasmine.github.io/
-[jest]: https://jestjs.io
-[jestspy]: https://jestjs.io/docs/en/jest-object#jestspyonobject-methodname

doc/development/testing_guide/index.md

@@ -11,8 +11,8 @@ importance.
 
 ## Overview
 
-GitLab is built on top of [Ruby on Rails](https://rubyonrails.org/), and we're using [RSpec] for all
-the backend tests, with [Capybara] for end-to-end integration testing.
+GitLab is built on top of [Ruby on Rails](https://rubyonrails.org/), and we're using [RSpec](https://github.com/rspec/rspec-rails#feature-specs) for all
+the backend tests, with [Capybara](https://github.com/teamcapybara/capybara) for end-to-end integration testing.
 On the frontend side, we're using [Jest](https://jestjs.io/) and [Karma](http://karma-runner.github.io/)/[Jasmine](https://jasmine.github.io/) for JavaScript unit and
 integration testing.
 
@@ -58,14 +58,10 @@ Everything you should know about how to test Rake tasks.
 ## [End-to-end tests](end_to_end/index.md)
 
 Everything you should know about how to run end-to-end tests using
-[GitLab QA][gitlab-qa] testing framework.
+[GitLab QA](ttps://gitlab.com/gitlab-org/gitlab-qa) testing framework.
 
 ## [Migrations tests](testing_migrations_guide.md)
 
 Everything you should know about how to test migrations.
 
 [Return to Development documentation](../README.md)
-
-[RSpec]: https://github.com/rspec/rspec-rails#feature-specs
-[Capybara]: https://github.com/teamcapybara/capybara
-[gitlab-qa]: https://gitlab.com/gitlab-org/gitlab-qa

doc/development/testing_guide/testing_levels.md

@@ -356,7 +356,7 @@ possible).
 
 | Tests path | Testing engine | Notes |
 | ---------- | -------------- | ----- |
-| `spec/features/` | [Capybara] + [RSpec] | If your test has the `:js` metadata, the browser driver will be [Poltergeist], otherwise it's using [RackTest]. |
+| `spec/features/` | [Capybara](https://github.com/teamcapybara/capybara) + [RSpec](https://github.com/rspec/rspec-rails#feature-specs) | If your test has the `:js` metadata, the browser driver will be [Poltergeist], otherwise it's using [RackTest]. |
 
 ### Frontend feature tests
 
@@ -487,7 +487,7 @@ Every new feature should come with a [test plan].
 
 | Tests path | Testing engine | Notes |
 | ---------- | -------------- | ----- |
-| `qa/qa/specs/features/` | [Capybara] + [RSpec] + Custom QA framework | Tests should be placed under their corresponding [Product category] |
+| `qa/qa/specs/features/` | [Capybara](https://github.com/teamcapybara/capybara) + [RSpec](https://github.com/rspec/rspec-rails#feature-specs) + Custom QA framework | Tests should be placed under their corresponding [Product category] |
 
 > See [end-to-end tests](end_to_end/index.md) for more information.
 
@@ -517,14 +517,11 @@ These tests run against the UI and ensure that basic functionality is working.
 
 ### GitLab QA orchestrator
 
-[GitLab QA orchestrator] is a tool that allows to test that all these pieces
+[GitLab QA orchestrator](https://gitlab.com/gitlab-org/gitlab-qa) is a tool that allows to test that all these pieces
 integrate well together by building a Docker image for a given version of GitLab
 Rails and running end-to-end tests (i.e. using Capybara) against it.
 
-Learn more in the [GitLab QA orchestrator README][gitlab-qa-readme].
-
-[GitLab QA orchestrator]: https://gitlab.com/gitlab-org/gitlab-qa
-[gitlab-qa-readme]: https://gitlab.com/gitlab-org/gitlab-qa/tree/master/README.md
+Learn more in the [GitLab QA orchestrator README](https://gitlab.com/gitlab-org/gitlab-qa/tree/master/README.md).
 
 ## EE-specific tests
 
@@ -538,7 +535,9 @@ trade-off:
 - Unit tests are usually cheap, and you should consider them like the basement
   of your house: you need them to be confident that your code is behaving
   correctly. However if you run only unit tests without integration / system
-  tests, you might [miss] the [big] / [picture] !
+  tests, you might [miss](https://twitter.com/ThePracticalDev/status/850748070698651649) the
+  [big](https://twitter.com/timbray/status/822470746773409794) /
+  [picture](https://twitter.com/withzombies/status/829716565834752000) !
 - Integration tests are a bit more expensive, but don't abuse them. A system test
   is often better than an integration test that is stubbing a lot of internals.
 - System tests are expensive (compared to unit tests), even more if they require
@@ -546,8 +545,8 @@ trade-off:
   section.
 
 Another way to see it is to think about the "cost of tests", this is well
-explained [in this article][tests-cost] and the basic idea is that the cost of a
-test includes:
+explained [in this article](https://medium.com/table-xi/high-cost-tests-and-high-value-tests-a86e27a54df#.2ulyh3a4e)
+and the basic idea is that the cost of a test includes:
 
 - The time it takes to write the test
 - The time it takes to run the test every time the suite runs
@@ -562,13 +561,6 @@ running the full application, for example, if you are testing styling, animation
 edge cases or small actions that don't involve the backend,
 you should write an integration test using Jasmine.
 
-[miss]: https://twitter.com/ThePracticalDev/status/850748070698651649
-[big]: https://twitter.com/timbray/status/822470746773409794
-[picture]: https://twitter.com/withzombies/status/829716565834752000
-[tests-cost]: https://medium.com/table-xi/high-cost-tests-and-high-value-tests-a86e27a54df#.2ulyh3a4e
-[RSpec]: https://github.com/rspec/rspec-rails#feature-specs
-[Capybara]: https://github.com/teamcapybara/capybara
-
 ---
 
 [Return to Testing documentation](index.md)