diff options
author | GitLab Bot <gitlab-bot@gitlab.com> | 2019-11-27 09:06:40 +0300 |
---|---|---|
committer | GitLab Bot <gitlab-bot@gitlab.com> | 2019-11-27 09:06:40 +0300 |
commit | 688e33953d34ab8cd348d02ce79d8fdfe5353a03 (patch) | |
tree | ee102361fc8a5bf5b2f4b05ca79ccef27b5c3102 /doc/development | |
parent | 91f027ede40879af0bce406f2872e8d35c01e334 (diff) |
Add latest changes from gitlab-org/gitlab@master
Diffstat (limited to 'doc/development')
-rw-r--r-- | doc/development/api_graphql_styleguide.md | 2 | ||||
-rw-r--r-- | doc/development/contributing/issue_workflow.md | 24 | ||||
-rw-r--r-- | doc/development/documentation/index.md | 4 | ||||
-rw-r--r-- | doc/development/documentation/site_architecture/index.md | 6 | ||||
-rw-r--r-- | doc/development/documentation/site_architecture/release_process.md | 2 | ||||
-rw-r--r-- | doc/development/documentation/styleguide.md | 20 | ||||
-rw-r--r-- | doc/development/feature_flags/controls.md | 2 | ||||
-rw-r--r-- | doc/development/internal_api.md | 10 | ||||
-rw-r--r-- | doc/development/merge_request_performance_guidelines.md | 2 | ||||
-rw-r--r-- | doc/development/packages.md | 6 | ||||
-rw-r--r-- | doc/development/pipelines.md | 8 | ||||
-rw-r--r-- | doc/development/rake_tasks.md | 2 | ||||
-rw-r--r-- | doc/development/sidekiq_style_guide.md | 2 |
13 files changed, 45 insertions, 45 deletions
diff --git a/doc/development/api_graphql_styleguide.md b/doc/development/api_graphql_styleguide.md index b0d94511c6e..1cf2ca3667d 100644 --- a/doc/development/api_graphql_styleguide.md +++ b/doc/development/api_graphql_styleguide.md @@ -548,7 +548,7 @@ found, we should raise a `Gitlab::Graphql::Errors::ResourceNotAvailable` error. Which will be correctly rendered to the clients. -## Gitlab's custom scalars +## GitLab's custom scalars ### `Types::TimeType` diff --git a/doc/development/contributing/issue_workflow.md b/doc/development/contributing/issue_workflow.md index f32400d44a2..a385a7dc83a 100644 --- a/doc/development/contributing/issue_workflow.md +++ b/doc/development/contributing/issue_workflow.md @@ -40,17 +40,17 @@ scheduling into milestones. Labelling is a task for everyone. Most issues will have labels for at least one of the following: -- Type: ~feature, ~bug, ~backstage, etc. -- Stage: ~"devops::plan", ~"devops::create", etc. -- Group: ~"group::source code", ~"group::knowledge", ~"group::editor", etc. -- Category: ~"Category:Code Analytics", ~"Category:DevOps Score", ~"Category:Templates", etc. -- Feature: ~wiki, ~ldap, ~api, ~issues, ~"merge requests", etc. -- Department: ~UX, ~Quality -- Team: ~"Technical Writing", ~Delivery -- Specialization: ~frontend, ~backend, ~documentation -- Release Scoping: ~Deliverable, ~Stretch, ~"Next Patch Release" -- Priority: ~P1, ~P2, ~P3, ~P4 -- Severity: ~S1, ~S2, ~S3, ~S4 +- Type: `~feature`, `~bug`, `~backstage`, etc. +- Stage: `~"devops::plan"`, `~"devops::create"`, etc. +- Group: `~"group::source code"`, `~"group::knowledge"`, `~"group::editor"`, etc. +- Category: `~"Category:Code Analytics"`, `~"Category:DevOps Score"`, `~"Category:Templates"`, etc. +- Feature: `~wiki`, `~ldap`, `~api`, `~issues`, `~"merge requests"`, etc. +- Department: `~UX`, `~Quality` +- Team: `~"Technical Writing"`, `~Delivery` +- Specialization: `~frontend`, `~backend`, `~documentation` +- Release Scoping: `~Deliverable`, `~Stretch`, `~"Next Patch Release"` +- Priority: `~P1`, `~P2`, `~P3`, `~P4` +- Severity: ~`S1`, `~S2`, `~S3`, `~S4` All labels, their meaning and priority are defined on the [labels page](https://gitlab.com/gitlab-org/gitlab-foss/-/labels). @@ -210,7 +210,7 @@ If you are an expert in a particular area, it makes it easier to find issues to work on. You can also subscribe to those labels to receive an email each time an issue is labeled with a feature label corresponding to your expertise. -Examples of feature labels are ~wiki, ~ldap, ~api, ~issues, ~"merge requests" etc. +Examples of feature labels are `~wiki`, `~ldap`, `~api`, `~issues`, `~"merge requests"` etc. #### Naming and color convention diff --git a/doc/development/documentation/index.md b/doc/development/documentation/index.md index 7d575e9b0b1..a6474b8b141 100644 --- a/doc/development/documentation/index.md +++ b/doc/development/documentation/index.md @@ -41,7 +41,7 @@ However, anyone can contribute [documentation improvements](improvement-workflow ## Markdown and styles [GitLab docs](https://gitlab.com/gitlab-org/gitlab-docs) uses [GitLab Kramdown](https://gitlab.com/gitlab-org/gitlab_kramdown) -as its markdown rendering engine. See the [GitLab Markdown Guide](https://about.gitlab.com/handbook/product/technical-writing/markdown-guide/) for a complete Kramdown reference. +as its Markdown rendering engine. See the [GitLab Markdown Guide](https://about.gitlab.com/handbook/product/technical-writing/markdown-guide/) for a complete Kramdown reference. Adhere to the [Documentation Style Guide](styleguide.md). If a style standard is missing, you are welcome to suggest one via a merge request. @@ -449,7 +449,7 @@ A file with `proselint` configuration must be placed in a #### `markdownlint` -[`markdownlint`](https://github.com/DavidAnson/markdownlint) checks that markdown +[`markdownlint`](https://github.com/DavidAnson/markdownlint) checks that Markdown syntax follows [certain rules](https://github.com/DavidAnson/markdownlint/blob/master/doc/Rules.md#rules), and is used by the [`docs-lint` test](#testing) with a [configuration file](#markdownlint-configuration). Our [Documentation Style Guide](styleguide.md#markdown) and [Markdown Guide](https://about.gitlab.com/handbook/product/technical-writing/markdown-guide/) diff --git a/doc/development/documentation/site_architecture/index.md b/doc/development/documentation/site_architecture/index.md index bf873995e54..8a5018df9b7 100644 --- a/doc/development/documentation/site_architecture/index.md +++ b/doc/development/documentation/site_architecture/index.md @@ -128,9 +128,9 @@ We can then loop over the `versions` array with something like: Note that the data file must have the `yaml` extension (not `yml`) and that we reference the array with a symbol (`:versions`). -## Bumping versions of CSS and Javascript +## Bumping versions of CSS and JavaScript -Whenever the custom CSS and Javascript files under `content/assets/` change, +Whenever the custom CSS and JavaScript files under `content/assets/` change, make sure to bump their version in the frontmatter. This method guarantees that your changes will take effect by clearing the cache of previous files. @@ -180,7 +180,7 @@ for its search function. This is how it works: 1. On the docs side, we use a [docsearch layout](https://gitlab.com/gitlab-org/gitlab-docs/blob/master/layouts/docsearch.html) which is present on pretty much every page except <https://docs.gitlab.com/search/>, which uses its [own layout](https://gitlab.com/gitlab-org/gitlab-docs/blob/master/layouts/instantsearch.html). In those layouts, - there's a javascript snippet which initiates docsearch by using an API key + there's a JavaScript snippet which initiates docsearch by using an API key and an index name (`gitlab`) that are needed for Algolia to show the results. NOTE: **For GitLab employees:** diff --git a/doc/development/documentation/site_architecture/release_process.md b/doc/development/documentation/site_architecture/release_process.md index 6f723531f4c..76bd74b0bdc 100644 --- a/doc/development/documentation/site_architecture/release_process.md +++ b/doc/development/documentation/site_architecture/release_process.md @@ -117,7 +117,7 @@ version and rotates the old one: There's a temporary hack for now: 1. Edit `content/404.html`, making sure all offline versions under - `content/_data/versions.yaml` are in the Javascript snippet at the end of + `content/_data/versions.yaml` are in the JavaScript snippet at the end of the document. 1. **Update the `:latest` and `:archives` Docker images:** diff --git a/doc/development/documentation/styleguide.md b/doc/development/documentation/styleguide.md index d4f64b25bfa..359bac75e0d 100644 --- a/doc/development/documentation/styleguide.md +++ b/doc/development/documentation/styleguide.md @@ -102,7 +102,7 @@ Note that Kramdown-specific markup (e.g., `{:.class}`) will not render properly Hard-coded HTML is valid, although it's discouraged to be used while we have `/help`. HTML is permitted as long as: -- There's no equivalent markup in markdown. +- There's no equivalent markup in Markdown. - Advanced tables are necessary. - Special styling is required. - Reviewed and approved by a technical writer. @@ -245,7 +245,7 @@ Do not include the same information in multiple places. [Link to a SSOT instead. ## Text -- [Write in markdown](#markdown). +- [Write in Markdown](#markdown). - Splitting long lines (preferably up to 100 characters) can make it easier to provide feedback on small chunks of text. - Insert an empty line for new paragraphs. - Use sentence case for titles, headings, labels, menu items, and buttons. @@ -453,7 +453,7 @@ to mix types, that is also possible, as long as you don't mix items at the same ## Quotes -Valid for markdown content only, not for frontmatter entries: +Valid for Markdown content only, not for frontmatter entries: - Standard quotes: double quotes (`"`). Example: "This is wrapped in double quotes". - Quote within a quote: double quotes (`"`) wrap single quotes (`'`). Example: "I am 'quoting' something within a quote". @@ -464,7 +464,7 @@ For other punctuation rules, please refer to the ## Headings - Add **only one H1** in each document, by adding `#` at the beginning of - it (when using markdown). The `h1` will be the document `<title>`. + it (when using Markdown). The `h1` will be the document `<title>`. - Start with an `h2` (`##`), and respect the order `h2` > `h3` > `h4` > `h5` > `h6`. Never skip the hierarchy level, such as `h2` > `h4` - Avoid putting numbers in headings. Numbers shift, hence documentation anchor @@ -490,7 +490,7 @@ For other punctuation rules, please refer to the ## Links -- Use inline link markdown markup `[Text](https://example.com)`. +- Use inline link Markdown markup `[Text](https://example.com)`. It's easier to read, review, and maintain. **Do not** use `[Text][identifier]`. - Use [meaningful anchor texts](https://www.futurehosting.com/blog/links-should-have-meaningful-anchor-text-heres-why/). @@ -533,7 +533,7 @@ For other punctuation rules, please refer to the [issue tags](../../issues/tags.md#stages) ``` -- Using the markdown extension is necessary for the [`/help`](index.md#gitlab-help) +- Using the Markdown extension is necessary for the [`/help`](index.md#gitlab-help) section of GitLab. ### Links requiring permissions @@ -656,7 +656,7 @@ to readers. To embed a video, follow the instructions below and make sure you have your MR reviewed and approved by a technical writer. -1. Copy the code below and paste it into your markdown file. +1. Copy the code below and paste it into your Markdown file. Leave a blank line above and below it. Do NOT edit the code (don't remove or add any spaces, etc). 1. On YouTube, visit the video URL you want to display. Copy @@ -694,7 +694,7 @@ This is how it renders on the GitLab Docs site: class is necessary to make sure the video is responsive and displays nicely on different mobile devices. > - The `<div class="video-fallback">` is a fallback necessary for GitLab's -`/help`, as GitLab's markdown processor does not support iframes. It's hidden on the docs site but will be displayed on GitLab's `/help`. +`/help`, as GitLab's Markdown processor does not support iframes. It's hidden on the docs site but will be displayed on GitLab's `/help`. ## Code blocks @@ -725,7 +725,7 @@ nicely on different mobile devices. ``` ~~~ -- To display raw markdown instead of rendered markdown, you can use triple backticks +- To display raw Markdown instead of rendered Markdown, you can use triple backticks with `md`, like the `Markdown code` example above, unless you want to include triple backticks in the code block as well. In that case, use triple tildes (`~~~`) instead. - For a complete reference on code blocks, check the [Kramdown guide](https://about.gitlab.com/handbook/product/technical-writing/markdown-guide/#code-blocks). @@ -739,7 +739,7 @@ _Note that the alert boxes only work for one paragraph only. Multiple paragraphs lists, headers, etc will not render correctly. For multiple lines, use blockquotes instead._ Alert boxes only render on the GitLab Docs site (<https://docs.gitlab.com>). -Within GitLab itself, they will appear as plain markdown text (like the examples +Within GitLab itself, they will appear as plain Markdown text (like the examples above the rendered versions, below). ### Note diff --git a/doc/development/feature_flags/controls.md b/doc/development/feature_flags/controls.md index cbbbe1cd5ea..3799672ee11 100644 --- a/doc/development/feature_flags/controls.md +++ b/doc/development/feature_flags/controls.md @@ -19,7 +19,7 @@ run: ## Where to run commands To increase visibility, we recommend that GitLab team members run feature flag -related Chatops commands within certain slack channels based on the environment +related Chatops commands within certain Slack channels based on the environment and related feature. For the [staging](https://staging.gitlab.com) and [development](https://dev.gitlab.org) environments of GitLab.com, the commands should run in a channel for the stage the feature is relevant too. diff --git a/doc/development/internal_api.md b/doc/development/internal_api.md index b08112aacb2..18d88c37147 100644 --- a/doc/development/internal_api.md +++ b/doc/development/internal_api.md @@ -4,8 +4,8 @@ The internal API is used by different GitLab components, it can not be used by other consumers. This documentation is intended for people working on the GitLab codebase. -This documentation does not yet include the internal api used by -GitLab pages. +This documentation does not yet include the internal API used by +GitLab Pages. ## Authentication @@ -19,7 +19,7 @@ file, and include the token Base64 encoded in a `secret_token` param or in the `Gitlab-Shared-Secret` header. NOTE: **Note:** -The internal api used by GitLab pages uses a different kind of +The internal API used by GitLab Pages uses a different kind of authentication. ## Git Authentication @@ -119,7 +119,7 @@ curl --request POST --header "Gitlab-Shared-Secret: <Base64 encoded token>" --da ## Authorized Keys Check This endpoint is called by the GitLab-shell authorized keys -check. Which is called by OpenSSH for [fast ssh key +check. Which is called by OpenSSH for [fast SSH key lookup](../administration/operations/fast_ssh_key_lookup.md). | Attribute | Type | Required | Description | @@ -292,7 +292,7 @@ Example response: ## PostReceive Called from Gitaly after a receiving a push. This triggers the -`PostReceive`-worker in sidekiq, processes the passed push options and +`PostReceive`-worker in Sidekiq, processes the passed push options and builds the response including messages that need to be displayed to the user. diff --git a/doc/development/merge_request_performance_guidelines.md b/doc/development/merge_request_performance_guidelines.md index 2e80e813a4b..43059d23c79 100644 --- a/doc/development/merge_request_performance_guidelines.md +++ b/doc/development/merge_request_performance_guidelines.md @@ -75,7 +75,7 @@ data set is for this feature to process, and what problems it might cause. If you would think about the following example that puts a strong emphasis of data set being processed. The problem is simple: you want to filter a list of files from -some git repository. Your feature requests a list of all files +some Git repository. Your feature requests a list of all files from the repository and perform search for the set of files. As an author you should in context of that problem consider the following: diff --git a/doc/development/packages.md b/doc/development/packages.md index 30f22c13525..951a8f2b346 100644 --- a/doc/development/packages.md +++ b/doc/development/packages.md @@ -90,14 +90,14 @@ model for that package type. ## File uploads -File uploads should be handled by GitLab workhorse using object accelerated uploads. What this means is that +File uploads should be handled by GitLab Workhorse using object accelerated uploads. What this means is that the workhorse proxy that checks all incoming requests to GitLab will intercept the upload request, upload the file, and forward a request to the main GitLab codebase only containing the metadata and file location rather than the file itself. An overview of this process can be found in the [development documentation](uploads.md#workhorse-object-storage-acceleration). In terms of code, this means a route will need to be added to the -[gitlab-workhorse project](https://gitlab.com/gitlab-org/gitlab-workhorse) for each level of remote being added +[GitLab Workhorse project](https://gitlab.com/gitlab-org/gitlab-workhorse) for each level of remote being added (instance, group, project). [This merge request](https://gitlab.com/gitlab-org/gitlab-workhorse/merge_requests/412/diffs) demonstrates adding an instance-level endpoint for Conan to workhorse. You can also see the Maven project level endpoint implemented in the same file. @@ -164,7 +164,7 @@ process. These changes represent all that is needed to deliver a minimally usable package management system. -1. Empty file structure (api file, base service for this package) +1. Empty file structure (API file, base service for this package) 1. Authentication system for 'logging in' to the package manager 1. Identify metadata and create applicable tables 1. Workhorse route for [object storage accelerated uploads](uploads.md#workhorse-object-storage-acceleration) diff --git a/doc/development/pipelines.md b/doc/development/pipelines.md index 39384f9bcbe..07943c60647 100644 --- a/doc/development/pipelines.md +++ b/doc/development/pipelines.md @@ -1,6 +1,6 @@ # Pipelines for the GitLab project -Pipelines for `gitlab-org/gitlab` and `gitlab-org/gitlab-foss` (as well as the +Pipelines for <https://gitlab.com/gitlab-org/gitlab> and <https://gitlab.com/gitlab-org/gitlab-foss> (as well as the `dev` instance's mirrors) are configured in the usual [`.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/blob/master/.gitlab-ci.yml) which itself includes files under @@ -15,8 +15,8 @@ as much as possible. The current stages are: -- `sync`: This stage is used to synchronize changes from gitlab-org/gitlab to - gitlab-org/gitlab-foss. +- `sync`: This stage is used to synchronize changes from <https://gitlab.com/gitlab-org/gitlab> to + <https://gitlab.com/gitlab-org/gitlab-foss>. - `prepare`: This stage includes jobs that prepare artifacts that are needed by jobs in subsequent stages. - `quick-test`: This stage includes test jobs that should run first and fail the @@ -33,7 +33,7 @@ The current stages are: - `post-test`: This stage includes jobs that build reports or gather data from the previous stages' jobs (e.g. coverage, Knapsack metadata etc.). - `pages`: This stage includes a job that deploys the various reports as - GitLab pages (e.g. <https://gitlab-org.gitlab.io/gitlab/coverage-ruby/>, + GitLab Pages (e.g. <https://gitlab-org.gitlab.io/gitlab/coverage-ruby/>, <https://gitlab-org.gitlab.io/gitlab/coverage-javascript/>, <https://gitlab-org.gitlab.io/gitlab/webpack-report/>). diff --git a/doc/development/rake_tasks.md b/doc/development/rake_tasks.md index 369806d462b..ae2dbc5c340 100644 --- a/doc/development/rake_tasks.md +++ b/doc/development/rake_tasks.md @@ -96,7 +96,7 @@ In order to run the test you can use the following commands: - `bin/rake spec:unit` to run the only the unit tests - `bin/rake spec:integration` to run the only the integration tests - `bin/rake spec:system` to run the only the system tests -- `bin/rake karma` to run the karma test suite +- `bin/rake karma` to run the Karma test suite Note: `bin/rake spec` takes significant time to pass. Instead of running full test suite locally you can save a lot of time by running diff --git a/doc/development/sidekiq_style_guide.md b/doc/development/sidekiq_style_guide.md index e433691c1ed..77663b0bb29 100644 --- a/doc/development/sidekiq_style_guide.md +++ b/doc/development/sidekiq_style_guide.md @@ -211,7 +211,7 @@ end We use the following approach to determine whether a worker is CPU-bound: -- In the sidekiq structured JSON logs, aggregate the worker `duration` and +- In the Sidekiq structured JSON logs, aggregate the worker `duration` and `cpu_s` fields. - `duration` refers to the total job execution duration, in seconds - `cpu_s` is derived from the |