diff options
Diffstat (limited to 'doc/development')
25 files changed, 68 insertions, 66 deletions
diff --git a/doc/development/architecture.md b/doc/development/architecture.md index fd2a6cb0f3c..8d5368bdd28 100644 --- a/doc/development/architecture.md +++ b/doc/development/architecture.md @@ -207,7 +207,7 @@ Consul is a tool for service discovery and configuration. Consul is distributed, #### Elasticsearch -- [Project page](https://github.com/elastic/elasticsearch/blob/master/README.textile) +- [Project page](https://github.com/elastic/elasticsearch/blob/master/README.asciidoc) - Configuration: [Omnibus][elasticsearch-omnibus], [Charts][elasticsearch-charts], [Source][elasticsearch-source], [GDK][elasticsearch-gdk] - Layer: Core Service (Data) diff --git a/doc/development/documentation/index.md b/doc/development/documentation/index.md index 8897b61d6dc..21e94a3464e 100644 --- a/doc/development/documentation/index.md +++ b/doc/development/documentation/index.md @@ -447,7 +447,7 @@ Where `MD_DOC_PATH` points to the file or directory you would like to run lint c If you omit it completely, it will default to the `doc/` directory. The output should be similar to: -``` +```plaintext => Linting documents at path /path/to/gitlab as <user>... => Checking for cURL short options... => Checking for CHANGELOG.md duplicate entries... diff --git a/doc/development/documentation/styleguide.md b/doc/development/documentation/styleguide.md index 16a175ec115..1fe83f1ea37 100644 --- a/doc/development/documentation/styleguide.md +++ b/doc/development/documentation/styleguide.md @@ -521,7 +521,7 @@ For ordered lists, use three spaces for each level of indentation: You can nest full lists inside other lists using the same rules as above. If you wish to mix types, that is also possible, as long as you don't mix items at the same level: -``` +```markdown 1. Ordered list item one. 1. Ordered list item two. - Nested unordered list item one. diff --git a/doc/development/elasticsearch.md b/doc/development/elasticsearch.md index 16a86c06317..20f9fb95440 100644 --- a/doc/development/elasticsearch.md +++ b/doc/development/elasticsearch.md @@ -184,7 +184,7 @@ If the current version is `v12p1`, and we need to create a new version for `v12p You might get an error such as -``` +```plaintext [2018-10-31T15:54:19,762][WARN ][o.e.c.r.a.DiskThresholdMonitor] [pval5Ct] flood stage disk watermark [95%] exceeded on [pval5Ct7SieH90t5MykM5w][pval5Ct][/usr/local/var/lib/elasticsearch/nodes/0] free: 56.2gb[3%], @@ -195,20 +195,20 @@ This is because you've exceeded the disk space threshold - it thinks you don't h In addition, the `read_only_allow_delete` setting will be set to `true`. It will block indexing, `forcemerge`, etc -``` +```shell curl "http://localhost:9200/gitlab-development/_settings?pretty" ``` Add this to your `elasticsearch.yml` file: -``` +```yaml # turn off the disk allocator cluster.routing.allocation.disk.threshold_enabled: false ``` _or_ -``` +```yaml # set your own limits cluster.routing.allocation.disk.threshold_enabled: true cluster.routing.allocation.disk.watermark.flood_stage: 5gb # ES 6.x only diff --git a/doc/development/experiment_guide/index.md b/doc/development/experiment_guide/index.md index 66b7bd8ed0f..edfde53f5ec 100644 --- a/doc/development/experiment_guide/index.md +++ b/doc/development/experiment_guide/index.md @@ -58,7 +58,7 @@ The author then adds a comment to this piece of code and adds a link to the issu - Track necessary events. See the [telemetry guide](../../telemetry/index.md) for details. - After the merge request is merged, use [`chatops`](../../ci/chatops/README.md) to enable the feature flag and start the experiment. For visibility, please run the command in the `#s_growth` channel: - ``` + ```shell /chatops run feature set --project=gitlab-org/gitlab experimental_sign_up_flow true ``` diff --git a/doc/development/fe_guide/development_process.md b/doc/development/fe_guide/development_process.md index 92f3c82a6ea..6e078f097cd 100644 --- a/doc/development/fe_guide/development_process.md +++ b/doc/development/fe_guide/development_process.md @@ -10,9 +10,9 @@ Copy the content over to your issue or merge request and if something doesn't ap This checklist is intended to help us during development of bigger features/refactorings, it's not a "use it always and every point always matches" list. -Please use your best judgement when to use it and please contribute new points through merge requests if something comes to your mind. +Please use your best judgment when to use it and please contribute new points through merge requests if something comes to your mind. -``` +```markdown ### Frontend development #### Planning development diff --git a/doc/development/fe_guide/graphql.md b/doc/development/fe_guide/graphql.md index a8c78903612..620ed06765c 100644 --- a/doc/development/fe_guide/graphql.md +++ b/doc/development/fe_guide/graphql.md @@ -149,7 +149,7 @@ Using local Apollo Cache is handy when we have a need to mock some GraphQL API r For example, we have a [fragment](#fragments) on `DesignVersion` used in our queries: -``` +```javascript fragment VersionListItem on DesignVersion { id sha @@ -158,7 +158,7 @@ fragment VersionListItem on DesignVersion { We need to fetch also version author and the 'created at' property to display them in the versions dropdown but these changes are still not implemented in our API. We can change the existing fragment to get a mocked response for these new fields: -``` +```javascript fragment VersionListItem on DesignVersion { id sha diff --git a/doc/development/fe_guide/style/vue.md b/doc/development/fe_guide/style/vue.md index 8f69792287b..b571707edfd 100644 --- a/doc/development/fe_guide/style/vue.md +++ b/doc/development/fe_guide/style/vue.md @@ -294,7 +294,7 @@ Please check this [rules](https://github.com/vuejs/eslint-plugin-vue#bulb-rules) 1. Tag order in `.vue` file - ``` + ```html <script> // ... </script> diff --git a/doc/development/fe_guide/tooling.md b/doc/development/fe_guide/tooling.md index 066c2575e2d..0e8f5ed05ed 100644 --- a/doc/development/fe_guide/tooling.md +++ b/doc/development/fe_guide/tooling.md @@ -64,36 +64,36 @@ The easiest way to include prettier in your workflow is by setting up your prefe Please take care that you only let Prettier format the same file types as the global Yarn script does (.js, .vue, and .scss). In VSCode by example you can easily exclude file formats in your settings file: -``` +```json "prettier.disableLanguages": [ "json", "markdown" - ], + ] ``` ### Yarn Script The following yarn scripts are available to do global formatting: -``` +```shell yarn prettier-staged-save ``` Updates all currently staged files (based on `git diff`) with Prettier and saves the needed changes. -``` +```shell yarn prettier-staged ``` Checks all currently staged files (based on `git diff`) with Prettier and log which files would need manual updating to the console. -``` +```shell yarn prettier-all ``` Checks all files with Prettier and logs which files need manual updating to the console. -``` +```shell yarn prettier-all-save ``` @@ -103,13 +103,13 @@ The source of these Yarn scripts can be found in `/scripts/frontend/prettier.js` #### Scripts during Conversion period -``` +```shell node ./scripts/frontend/prettier.js check-all ./vendor/ ``` This will go over all files in a specific folder check it. -``` +```shell node ./scripts/frontend/prettier.js save-all ./vendor/ ``` diff --git a/doc/development/fe_guide/vue.md b/doc/development/fe_guide/vue.md index 96bc89675fe..aeedd57fd83 100644 --- a/doc/development/fe_guide/vue.md +++ b/doc/development/fe_guide/vue.md @@ -25,7 +25,7 @@ In some features implemented with Vue.js, like the [issue board][issue-boards] or [environments table][environments-table] you can find a clear separation of concerns: -``` +```plaintext new_feature ├── components │ └── component.vue diff --git a/doc/development/fe_guide/vuex.md b/doc/development/fe_guide/vuex.md index fd8ba0297c5..65661b0cc3b 100644 --- a/doc/development/fe_guide/vuex.md +++ b/doc/development/fe_guide/vuex.md @@ -22,7 +22,7 @@ _Note:_ The action itself will not update the state, only a mutation should upda When using Vuex at GitLab, separate these concerns into different files to improve readability: -``` +```plaintext └── store ├── index.js # where we assemble modules and export the store ├── actions.js # actions diff --git a/doc/development/feature_flags/controls.md b/doc/development/feature_flags/controls.md index a9a75791db7..f17ac55a809 100644 --- a/doc/development/feature_flags/controls.md +++ b/doc/development/feature_flags/controls.md @@ -12,7 +12,7 @@ Follow the Chatops document to [request access](../chatops_on_gitlabcom.md#reque Once you are added to the project test if your access propagated, run: -``` +```shell /chatops run feature --help ``` @@ -70,7 +70,7 @@ and <https://dev.gitlab.org>. For example, to enable a feature for 25% of all users, run the following in Slack: -``` +```shell /chatops run feature set new_navigation_bar 25 --dev /chatops run feature set new_navigation_bar 25 --staging ``` @@ -92,7 +92,7 @@ feature enabled, you can roll out the change to GitLab.com. Similar to above, to enable a feature for 25% of all users, run the following in Slack: -``` +```shell /chatops run feature set new_navigation_bar 25 ``` @@ -117,13 +117,13 @@ Feature gates can also be actor based, for example a feature could first be enabled for only the `gitlab` project. The project is passed by supplying a `--project` flag: -``` +```shell /chatops run feature set --project=gitlab-org/gitlab some_feature true ``` For groups the `--group` flag is available: -``` +```shell /chatops run feature set --group=gitlab-org some_feature true ``` @@ -131,7 +131,7 @@ Note that actor-based gates are applied before percentages. For example, conside `group/project` as `gitlab-org/gitlab` and a given example feature as `some_feature`, if you run these 2 commands: -``` +```shell /chatops run feature set --project=gitlab-org/gitlab some_feature true /chatops run feature set some_feature 25 ``` diff --git a/doc/development/file_storage.md b/doc/development/file_storage.md index bc3c16bd45d..adfb92acc54 100644 --- a/doc/development/file_storage.md +++ b/doc/development/file_storage.md @@ -60,7 +60,7 @@ hash of the project ID instead, if project migrates to the new approach (introdu Files are stored at multiple locations and use different path schemes. All the `GitlabUploader` derived classes should comply with this path segment schema: -``` +```plaintext | GitlabUploader | ----------------------- + ------------------------- + --------------------------------- + -------------------------------- | | `<gitlab_root>/public/` | `uploads/-/system/` | `user/avatar/:id/` | `:filename` | diff --git a/doc/development/geo.md b/doc/development/geo.md index c4ce9fed283..d3df2b421de 100644 --- a/doc/development/geo.md +++ b/doc/development/geo.md @@ -134,7 +134,7 @@ The **secondary** node authenticates itself via a [JWT request](https://jwt.io/) When the **secondary** node wishes to download a file, it sends an HTTP request with the `Authorization` header: -``` +```plaintext Authorization: GL-Geo <access_key>:<JWT payload> ``` @@ -146,7 +146,7 @@ file for the right database ID. For example, for an LFS object, the request must also include the SHA256 sum of the file. An example JWT payload looks like: -``` +```yaml { "data": { sha256: "31806bb23580caab78040f8c45d329f5016b0115" }, iat: "1234567890" } ``` @@ -199,13 +199,13 @@ contains the schema and migrations for this database. To write a migration for the database, use the `GeoMigrationGenerator`: -``` +```shell rails g geo_migration [args] [options] ``` To migrate the tracking database, run: -``` +```shell bundle exec rake geo:db:migrate ``` @@ -252,7 +252,7 @@ Failure to do this will prevent the **secondary** node from functioning properly. The **secondary** node will generate error messages, as the following PostgreSQL error: -``` +```sql ERROR: relation "gitlab_secondary.ci_job_artifacts" does not exist at character 323 STATEMENT: SELECT a.attname, format_type(a.atttypid, a.atttypmod), pg_get_expr(d.adbin, d.adrelid), a.attnotnull, a.atttypid, a.atttypmod diff --git a/doc/development/gotchas.md b/doc/development/gotchas.md index 5e9722d9586..8f077e613b7 100644 --- a/doc/development/gotchas.md +++ b/doc/development/gotchas.md @@ -101,7 +101,7 @@ end in a prepended module, which is very likely the case in EE. We could see error like this: - ``` + ```plaintext 1.1) Failure/Error: expect_any_instance_of(ApplicationSetting).to receive_messages(messages) Using `any_instance` to stub a method (elasticsearch_indexing) that has been defined on a prepended module (EE::ApplicationSetting) is not supported. ``` diff --git a/doc/development/i18n/externalization.md b/doc/development/i18n/externalization.md index 2595ee5b6d3..5c6e31d0a37 100644 --- a/doc/development/i18n/externalization.md +++ b/doc/development/i18n/externalization.md @@ -488,7 +488,7 @@ The linter will take the following into account: The errors are grouped per file, and per message ID: -``` +```plaintext Errors in `locale/zh_HK/gitlab.po`: PO-syntax errors SimplePoParser::ParserErrorSyntax error in lines diff --git a/doc/development/import_export.md b/doc/development/import_export.md index 9dde5422642..c969523cd40 100644 --- a/doc/development/import_export.md +++ b/doc/development/import_export.md @@ -63,7 +63,7 @@ class StuckImportJobsWorker Marked stuck import jobs as failed. JIDs: xyz ``` -``` +```plaintext +-----------+ +-----------------------------------+ |Export Job |--->| Calls ActiveRecord `as_json` and | +-----------+ | `to_json` on all project models | diff --git a/doc/development/import_project.md b/doc/development/import_project.md index 3cdf2b8977a..5059608ad5c 100644 --- a/doc/development/import_project.md +++ b/doc/development/import_project.md @@ -148,7 +148,7 @@ In this section we'll detail any known issues we've seen when trying to import a If you're attempting to import a large project into a development environment, you may see Gitaly throw an error about too many calls or invocations, for example: -``` +```plaintext Error importing repository into qa-perf-testing/gitlabhq - GitalyClient#call called 31 times from single request. Potential n+1? ``` diff --git a/doc/development/instrumentation.md b/doc/development/instrumentation.md index 55b42bb6ef9..fd01d0ea405 100644 --- a/doc/development/instrumentation.md +++ b/doc/development/instrumentation.md @@ -87,7 +87,7 @@ Ruby code. In case of the above snippet you'd run the following: This will print out something along the lines of: -``` +```plaintext From: /path/to/your/gitlab/lib/gitlab/metrics/instrumentation.rb @ line 148: Owner: #<Module:0x0055f0865c6d50> Visibility: public diff --git a/doc/development/integrations/jira_connect.md b/doc/development/integrations/jira_connect.md index 838358cb540..8e619c3b0a2 100644 --- a/doc/development/integrations/jira_connect.md +++ b/doc/development/integrations/jira_connect.md @@ -31,7 +31,7 @@ The following are required to install and test the app: For example: - ``` + ```plaintext https://xxxx.serveo.net/-/jira_connect/app_descriptor.json ``` diff --git a/doc/development/internal_api.md b/doc/development/internal_api.md index b0c35b57422..b9d287d11b0 100644 --- a/doc/development/internal_api.md +++ b/doc/development/internal_api.md @@ -34,7 +34,7 @@ Gitaly. When called from Gitaly in a `pre-receive` hook the changes are passed and those are validated to determine if the push is allowed. -``` +```plaintext POST /internal/allowed ``` @@ -57,7 +57,7 @@ curl --request POST --header "Gitlab-Shared-Secret: <Base64 encoded token>" --da Example response: -``` +```json { "status": true, "gl_repository": "project-3", @@ -103,7 +103,7 @@ Example request: curl --request POST --header "Gitlab-Shared-Secret: <Base64 encoded token>" --data "key_id=11&project=gnuwget/wget2" http://localhost:3001/api/v4/internal/lfs_authenticate ``` -``` +```json { "username": "root", "lfs_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJkYXRhIjp7ImFjdG9yIjoicm9vdCJ9LCJqdGkiOiIyYWJhZDcxZC0xNDFlLTQ2NGUtOTZlMi1mODllYWRiMGVmZTYiLCJpYXQiOjE1NzAxMTc2NzYsIm5iZiI6MTU3MDExNzY3MSwiZXhwIjoxNTcwMTE5NDc2fQ.g7atlBw1QMY7QEBVPE0LZ8ZlKtaRzaMRmNn41r2YITM", @@ -126,7 +126,7 @@ lookup](../administration/operations/fast_ssh_key_lookup.md). |:----------|:-------|:---------|:------------| | `key` | string | yes | SSH key as passed by OpenSSH to GitLab-shell | -``` +```plaintext GET /internal/authorized_keys ``` @@ -138,7 +138,7 @@ curl --request GET --header "Gitlab-Shared-Secret: <Base64 encoded secret>""http Example response: -``` +```json { "id": 11, "title": "admin@example.com", @@ -161,7 +161,7 @@ discovers the user associated with an SSH key. | `key_id` | integer | no | The id of the SSH key used as found in the authorized-keys file or through the `/authorized_keys` check | | `username` | string | no | Username of the user being looked up, used by GitLab-shell when authenticating using a certificate | -``` +```plaintext GET /internal/discover ``` @@ -173,7 +173,7 @@ curl --request GET --header "Gitlab-Shared-Secret: <Base64 encoded secret>" "htt Example response: -``` +```json { "id": 7, "name": "Dede Eichmann", @@ -190,7 +190,7 @@ Example response: This get's some generic information about the instance. This is used by Geo nodes to get information about eachother -``` +```plaintext GET /internal/check ``` @@ -202,7 +202,7 @@ curl --request GET --header "Gitlab-Shared-Secret: <Base64 encoded secret>" "htt Example response: -``` +```json { "api_version": "v4", "gitlab_version": "12.3.0-pre", @@ -226,7 +226,7 @@ recovery codes based on their SSH key | `key_id` | integer | no | The id of the SSH key used as found in the authorized-keys file or through the `/authorized_keys` check | | `user_id` | integer | no | **Deprecated** User_id for which to generate new recovery codes | -``` +```plaintext GET /internal/two_factor_recovery_codes ``` @@ -238,7 +238,7 @@ curl --request POST --header "Gitlab-Shared-Secret: <Base64 encoded secret>" --d Example response: -``` +```json { "success": true, "recovery_codes": [ @@ -269,7 +269,7 @@ for a push that might be accepted. |:----------|:-------|:---------|:------------| | `gl_repository` | string | yes | repository identifier for the repository receiving the push | -``` +```plaintext POST /internal/pre_receive ``` @@ -281,7 +281,7 @@ curl --request POST --header "Gitlab-Shared-Secret: <Base64 encoded secret>" --d Example response: -``` +```json { "reference_counter_increased": true } @@ -301,7 +301,7 @@ the user. | `push_options` | string array | no | array of push options | | `changes` | string | no | refs to be updated in the push in the format `oldrev newrev refname\n`. | -``` +```plaintext POST /internal/post_receive ``` @@ -313,7 +313,7 @@ curl --request POST --header "Gitlab-Shared-Secret: <Base64 encoded secret>" --d Example response: -``` +```json { "messages": [ { diff --git a/doc/development/new_fe_guide/development/accessibility.md b/doc/development/new_fe_guide/development/accessibility.md index 7a15e9eb6be..8d9f7ca5069 100644 --- a/doc/development/new_fe_guide/development/accessibility.md +++ b/doc/development/new_fe_guide/development/accessibility.md @@ -27,7 +27,7 @@ On the other hand, if an icon is crucial to understand the context we should do In forms we should use the `for` attribute in the label statement: -``` +```html <div> <label for="name">Fill in your name:</label> <input type="text" id="name" name="name"> diff --git a/doc/development/new_fe_guide/tips.md b/doc/development/new_fe_guide/tips.md index 657da1be1a7..2e2f5e8f47d 100644 --- a/doc/development/new_fe_guide/tips.md +++ b/doc/development/new_fe_guide/tips.md @@ -4,7 +4,7 @@ To clear production compiled assets created with `yarn webpack-prod` you can run: -``` +```shell yarn clean ``` diff --git a/doc/development/routing.md b/doc/development/routing.md index 91b7ae7651e..97837a917a2 100644 --- a/doc/development/routing.md +++ b/doc/development/routing.md @@ -7,13 +7,13 @@ support subgroups, GitLab project and group routes use the wildcard character to match project and group routes. For example, we might have a path such as: -``` +```plaintext /gitlab-com/customer-success/north-america/west/customerA ``` However, paths can be ambiguous. Consider the following example: -``` +```plaintext /gitlab-com/edit ``` @@ -29,7 +29,7 @@ number of [reserved names](../user/reserved_names.md). We have a number of global routes. For example: -``` +```plaintext /-/health /-/metrics ``` @@ -40,7 +40,7 @@ Every group route must be under the `/-/` scope. Examples: -``` +```plaintext gitlab-org/-/edit gitlab-org/-/activity gitlab-org/-/security/dashboard @@ -56,7 +56,7 @@ client or other software requires something different. Examples: -``` +```plaintext gitlab-org/gitlab/-/activity gitlab-org/gitlab/-/jobs/123 gitlab-org/gitlab/-/settings/repository diff --git a/doc/development/shell_commands.md b/doc/development/shell_commands.md index 29fee58ed8a..b71fcbdc2ab 100644 --- a/doc/development/shell_commands.md +++ b/doc/development/shell_commands.md @@ -71,19 +71,21 @@ Make the difference between options and arguments clear to the argument parsers To understand what `--` does, consider the problem below. -``` +```shell # Example $ echo hello > -l $ cat -l + cat: illegal option -- l usage: cat [-benstuv] [file ...] ``` In the example above, the argument parser of `cat` assumes that `-l` is an option. The solution in the example above is to make it clear to `cat` that `-l` is really an argument, not an option. Many Unix command line tools follow the convention of separating options from arguments with `--`. -``` +```shell # Example (continued) $ cat -- -l + hello ``` @@ -203,7 +205,7 @@ validates :import_url, format: { with: URI.regexp(%w(ssh git http https)) } Suppose the user submits the following as their import URL: -``` +```plaintext file://git:/tmp/lol ``` |